One markdown file turns a coding agent into a system-observer that asks ltop instead of scraping shell output.
The skill ships in the repo at
docs/skills/ltop-observe/SKILL.md — commands, schema semantics,
platform traps and diagnostic recipes included. No dependencies beyond ltop itself.
Any agent that loads skills from a directory works. Claude Code example; other agents: drop the folder wherever they read skills from.
The skill drives the CLI — install it first (channels). The eBPF helper is optional; the skill notes when UDP numbers degrade without it.
$ brew install uMaj35ty/ltop/ltopOne file, one folder — for Claude Code and compatible layouts:
$ git clone --depth 1 \ https://github.com/uMaj35ty/ltop /tmp/ltop $ mkdir -p ~/.claude/skills $ cp -r /tmp/ltop/docs/skills/ltop-observe \ ~/.claude/skills/
China mirror: git clone --depth 1 https://atomgit.com/uMaj35ty/ltop /tmp/ltop (same history, faster from CN networks).
"Why is the network slow?" — "Watch chrome for 10 minutes and report traffic." The skill's frontmatter triggers on these; the agent runs the right command and reads structured JSON back.
$ ltop watch --duration 10m --proc chrome $ ltop report <file> --json
Everything an agent needs to stop guessing and start reading structured output — the full text is the SKILL.md itself.
| command | what the agent gets |
|---|---|
| ltop --json | schema-v1 snapshot, all five domains, rates included (~1.2 s: two sampling rounds) |
| ltop --schema | versioned field reference — never drifts from the binary |
| ltop watch | headless JSONL capture: --duration / --stop sentinel / --proc focus, crash-safe, no root |
| ltop report | window sums, peaks, active time — table or ~2 KB JSON (~97% fewer tokens than polling) |
| jq | watch/monlog files are plain JSONL — arbitrary slices are one filter away |
Network slow → sort interfaces by rate, check link state, then the top connections on the busy NIC. Disk busy → device throughput vs capacity, then per-process writers. LAN inventory → neighbours with gateway flags and mDNS names. Time windows → watch + report, never poll.
meta.udp_helper says when UDP accounting is complete;
conns[].process: null means another user's socket, not
"unowned"; process totals are payload bytes while NIC totals include
headers — a 10–40% gap is by design; macOS MACs are sanitized by the
system, not hidden by ltop.