ltop skills — teach your agent to observe the system

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.

Install

Any agent that loads skills from a directory works. Claude Code example; other agents: drop the folder wherever they read skills from.

1

Have ltop on the machine

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/ltop
2

Copy the skill into place

One 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).

3

Ask naturally

"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

What the skill teaches

Everything an agent needs to stop guessing and start reading structured output — the full text is the SKILL.md itself.

▣Command surface

commandwhat the agent gets
ltop --jsonschema-v1 snapshot, all five domains, rates included (~1.2 s: two sampling rounds)
ltop --schemaversioned field reference — never drifts from the binary
ltop watchheadless JSONL capture: --duration / --stop sentinel / --proc focus, crash-safe, no root
ltop reportwindow sums, peaks, active time — table or ~2 KB JSON (~97% fewer tokens than polling)
jqwatch/monlog files are plain JSONL — arbitrary slices are one filter away

◉Diagnostic recipes

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.

⌦Semantics that prevent wrong answers

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.