Linux Troubleshooting with Inspektor Gadget

What it does

When your agent uses it

• Tracing DNS or TCP failures on a host where application logs show nothing
• Finding which process opened a missing file or was killed by the kernel
• Diagnosing permission, capability or seccomp denials in a container
• Investigating slow disk or file I/O on a CI runner or edge node

Example prompts

• “DNS lookups from this CI runner keep failing; trace them with ig.”
• “Find out which process is killing my container and whether it is an OOM kill.”
• “Which process tries to open /etc/app/config.yaml and gets ENOENT?”
• “Trace TCP retransmits on this VM for ten seconds and tell me who is affected.”

Requirements

• The standalone ig binary on PATH
• Root access (CAP_BPF and CAP_SYS_ADMIN)
• A BTF-enabled Linux kernel
• Compatibility (from SKILL.md): Requires the standalone `ig` binary on PATH, run as root (CAP_BPF + CAP_SYS_ADMIN), on a BTF-enabled kernel (`/sys/kernel/btf/vmlinux`) for CO-RE. An optional container runtime (containerd/Docker/CRI-O/podman) enriches events; `--host` traces bare-host processes. Read-only. If `ig` is missing, see references/install.md — ask the operator before installing.

Workflow steps

4 steps, taken from the first numbered list in SKILL.md.

1. 1Route. Map the symptom to a domain (networking / security /
2. 2Discover. Run :latest --help to read the real flags and fields.
3. 3Run bounded. Scope and time-box
4. 4Read the columns. Inspect the fields (runtime.*, proc.*, error codes)

What it can do on your machine

Read from SKILL.md and the folder at commit 1f292a7. It shows what the files ask for, not the result of running them.

• Tool permissions

  Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

  From allowed-tools in the SKILL.md frontmatter.

• Runs code

  Shell commands in SKILL.md call:

  • kubectl
  • jq

  From the folder's file list and the shell code blocks in SKILL.md.

• Network

  No URLs in SKILL.md. Its commands use kubectl, which can reach the network depending on how they are called.

  From URLs in SKILL.md, links to its own repository left out.

• Credentials

  Names no API keys, tokens, secrets or passwords.

  From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

• Compatibility

  Requires the standalone `ig` binary on PATH, run as root (CAP_BPF + CAP_SYS_ADMIN), on a BTF-enabled kernel (`/sys/kernel/btf/vmlinux`) for CO-RE. An optional container runtime (containerd/Docker/CRI-O/podman) enriches events; `--host` traces bare-host processes. Read-only. If `ig` is missing, see references/install.md — ask the operator before installing.

  From compatibility in the SKILL.md frontmatter.

Context cost

Linux Troubleshooting with Inspektor Gadget loads about 2.4k tokens when it runs, and up to ~6.8k if it reads all its reference files. Until then it costs about 200 tokens; SKILL.md has 889 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it

~200

When it runs · the whole SKILL.md, loaded when a task matches

~2.4k

With references · SKILL.md plus every file in references/, read only if the agent opens them

~6.8k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

• NoteRuns commands with sudoSKILL.md:27

  I runners, or any box where you can run `sudo ig`. Events are

• NoteRuns commands with sudoSKILL.md:53

  sudo ig run <gadget>:latest --help       # flags + a "--fields" block listing every data source & field

• NoteRuns commands with sudoSKILL.md:54

  sudo ig run <gadget>:latest --timeout 5 -o json \

• NoteRuns commands with sudoSKILL.md:69

  `sudo ig run <gadget>:latest --runtimes containerd -c <name> --timeout <sec> -o json`

• NoteRuns commands with sudoSKILL.md:127

  e-host skill, swap `kubectl gadget run`→`sudo ig run` and `-n`/`-p`→

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from inspektor-gadget/inspektor-gadget at commit 1f292a7, republished under its Apache-2.0 licence (© inspektor-gadget). 889 words, ~2,359 tokens.

name

linux-troubleshooting

description

Debug a single Linux host, VM, or container runtime at the kernel level with Inspektor Gadget via the standalone `ig` binary — no Kubernetes required. Use when something on a bare host, edge node, CI runner, or Docker/containerd/CRI-O box is failing and logs aren't enough: DNS or TCP failures, connection resets / retransmits / drops, processes exiting or being killed (OOM/signal), failed or missing file opens, permission / capability / seccomp / LSM denials, slow disk or file I/O, or "which process made this syscall / connection". Traces real kernel events with eBPF; enriches with container name/runtime when a runtime is present. Read-only. Not for Kubernetes clusters (use kubernetes-troubleshooting for `kubectl gadget`), plain application logs, or metrics dashboards.

compatibility

Requires the standalone `ig` binary on PATH, run as root (CAP_BPF + CAP_SYS_ADMIN), on a BTF-enabled kernel (`/sys/kernel/btf/vmlinux`) for CO-RE. An optional container runtime (containerd/Docker/CRI-O/podman) enriches events; `--host` traces bare-host processes. Read-only. If `ig` is missing, see references/install.md — ask the operator before installing.

command -v ig >/dev/null 2>&1 && ig version || echo "ig MISSING -> references/install.md"

sudo ig run <gadget>:latest --help       # flags + a "--fields" block listing every data source & field
sudo ig run <gadget>:latest --timeout 5 -o json \
  | jq -s '(.[0] // {}) | if type == "array" then (.[0] // {}) else . end | keys'

© inspektor-gadget, Apache-2.0. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 5 other files (references) in skills/linux-troubleshooting of inspektor-gadget/inspektor-gadget.

• SKILL.md
• references/common-flags.md
• references/discovering-params-and-fields.md
• references/gadget-catalog.md
• references/install.md
• references/kubernetes-companion.md

Open the folder on GitHubat commit 1f292a7