agent-docs

Documentation for the post-code era. You ship more code than you can read. That's fine, you just need to know how it works.

This skill writes and reads briefs that stay in sync with your code. Briefs are written by agents, for agents, read by you.

Invocation grammar

The user types one of:

/agent-docs write   <topic>     # generate or refresh a brief
/agent-docs explain <topic>     # read brief + verify vs code + explain
/agent-docs list                # list all briefs with staleness state
/agent-docs check   <topic>     # staleness check only, no explanation
/agent-docs explore [--limit N] # scan repo, suggest topics that deserve a brief

<topic> is a kebab-case slug (lowercase ASCII, hyphens, e.g. source-provenance-pipeline). For explain and check, the user may also pass a partial slug — fuzzy resolution will find the right brief.

If the user invokes the skill without one of the five verbs above, print the grammar block above and stop.

Storage layout

Briefs live in .agent-docs/ at the repo root (not project root, not subdirectory — repo root, found via git rev-parse --show-toplevel). One brief per file. Filename is the slug plus .md.

<repo-root>/
  .agent-docs/
    source-provenance-pipeline.md
    judge-pipeline.md
    auth-flow.md

Brief format

Every brief is structured exactly like this:

---
topic: <slug>
tracks:
  - <path or glob, relative to repo root>
  - <path or glob>
last_verified_sha: <full git SHA>
---

## Brief
One paragraph: what this is, why it exists. Plain prose, no bullets.

## Where it lives
File paths + entry points. Bulleted. Path first, role second.

## Flow
Numbered steps of the happy path. Short sentences.

## Invariants
Things that must hold. Why each matters. Bulleted with brief reasons.

## Gotchas
Non-obvious traps, past incidents, things a fresh agent would get wrong.

A skeleton template lives at templates/doc-template.md in this skill directory. Copy it as a starting point, then fill in.

Briefs are always written in English, even if the repo's primary language is something else. Agents work most precisely in English, identifiers are English, and the skill is meant to be portable across projects.

Preconditions (check before any command)

1. Inside a git repo. Run git rev-parse --show-toplevel. If it fails, abort: "agent-docs requires a git repository — staleness tracking depends on it."
2. Operate from the repo root for all path operations. Use the toplevel output as the working base.

Command: write <topic>

1. Validate the slug. Must match ^[a-z0-9]+(-[a-z0-9]+)*$. If not, suggest a normalized version and ask the user to confirm.
2. Check for existing brief at .agent-docs/<topic>.md. If it exists, ask the user:
   • overwrite — discard old content entirely, fresh draft
   • refresh — regenerate Brief / Where it lives / Flow / Invariants, but keep the existing ## Gotchas section verbatim (Gotchas often encode hard-won tacit knowledge that's not in the code)
   • cancel — abort
3. Ensure .agent-docs/ exists in the repo root. Create if missing.
4. Confirm scope. Ask the user in one line: "Scope of <topic> in one sentence?" — this sentence guides the research agent. Don't proceed without an answer.

5. Spawn an Explore agent with this exact prompt (substituting <topic> and <scope-sentence>):

   Find everything in this repo related to <topic>. User-provided scope: <scope-sentence>.

   Locate: entry points, services, entities, configs, migrations, tests, related agents/pipelines, frontend components if relevant. For each, report the file path relative to repo root and a one-sentence role description.

   Also extract:

   • Invariants: assertions, validators, @NotNull/@Valid-style annotations, comments hinting at "must", "always", "never", explicit guards.
   • Non-obvious patterns: caching layers, async boundaries, retry logic, rate limits, pause/resume hooks, sidecar processes.
   • Past-incident traces: comments containing "we got burned", "do not", "don't", "deprecated because", "workaround for", or referencing issue/ticket numbers.

   Format the response as: (a) one-paragraph plain-prose brief of what this subsystem is and why it exists; (b) bulleted file list with one-sentence roles; (c) bulleted invariants with why each matters; (d) bulleted gotchas (non-obvious traps).

   Under 600 words. Cite file paths; no excerpts longer than two lines.

   Use medium breadth by default; escalate to very thorough if the scope sentence suggests a large subsystem (multiple services, cross-cutting concerns).

6. Synthesize the brief from the Explore report into the five-section format. Tracked paths are derived from the Explore agent's file list — collapse adjacent files into directory globs where sensible (src/foo/Bar.java + src/foo/Baz.java → src/foo/; three migrations V21_* + V22_* → src/main/resources/db/migration/V2[12]*). Aim for 3–8 tracked entries — too few misses drift, too many makes staleness noisy.
7. Show the draft to the user and ask for confirm/edit. If they edit, accept and apply.
8. Capture the current git SHA via git rev-parse HEAD (full SHA, not abbreviated). Write the file with that SHA in last_verified_sha.
9. Do not commit. Just write the file. The user commits when they're ready. Report the absolute file path so they can open it.

Command: explain <topic>

1. Resolve the topic via:

   python3 "$HOME/.claude/skills/agent-docs/find.py" "<topic>" --dir "$(git rev-parse --show-toplevel)/.agent-docs"

   Interpret output:

   • One match (any type): proceed with that slug. If the resolved slug differs from the input, tell the user: "Resolved to <slug>."
   • Multiple matches: list them numbered, ask which.
   • No match (exit code 1): ask whether to /agent-docs write <topic> now.
2. Read the brief at .agent-docs/<resolved-slug>.md. Parse the YAML frontmatter for tracks and last_verified_sha.

3. Staleness check. Run:

   git diff --name-only <last_verified_sha>..HEAD -- <each tracked path/glob>

   If last_verified_sha is not in the repo (rebased away, shallow clone), git cat-file -e <sha> will fail — treat that as STALE_UNKNOWN.

   Possible states:

   • fresh: empty diff for all tracks
   • stale: non-empty diff; collect the list of changed files
   • stale_unknown: SHA not reachable

4. Explain. Synthesize from the brief, don't quote verbatim. Order the explanation:

   1. Brief (one paragraph)
   2. Flow (the happy path)
   3. Invariants (what must hold)
   4. Gotchas (what surprises)
   5. Where it lives (paths last — humans want concepts first)

   If state is stale, lead with the warning:

   ⚠️ This brief was verified at <short-sha>. Since then, the following tracked files have changed: <file list>. The explanation below may be drifted; consider /agent-docs write <topic> to refresh.

   Then, when explaining sections that touch the changed files, mark the uncertainty honestly: "the brief says X, but <file> has changed since — I haven't re-verified that part."

   If state is stale_unknown, note the SHA is gone and recommend a refresh, then explain normally with caveats.

Command: list

1. Glob .agent-docs/*.md. If empty, tell the user there are no briefs yet; suggest /agent-docs write <topic>.
2. For each brief, parse frontmatter and run the same staleness check as explain.

3. Print a compact table sorted stale first, then alphabetical:

   STATE      TOPIC                              SINCE_SHA   DRIFTED_FILES
   stale      source-provenance-pipeline         a36d96eb    3
   fresh      judge-pipeline                     50bd6fcf    0

   No prose around the table unless something is stale_unknown (then add a one-line note).

Command: check <topic>

1. Resolve via find.py like explain.
2. Run the staleness check.

3. Report only the result — one line, no explanation:

   • fresh: <topic> at <short-sha>
   • stale: <topic> — <N> tracked files changed since <short-sha>: <comma-list>
   • stale_unknown: <topic> — last_verified_sha not in repo

   Suitable as a pre-commit gut check.

Command: explore [--limit N]

Scans the repo and suggests subsystems/flows/decisions that would benefit from a brief. Closes the loop: explore → pick a candidate → write <slug>.

1. Parse args. Optional --limit N (default 10, max 25). Anything else after explore is ignored.

2. Collect baseline signals in parallel via Bash before spawning the agent — these are cheap and give the sub-agent something to anchor on:

   git -C "$(git rev-parse --show-toplevel)" log --since='90 days ago' --name-only --pretty=format: \
     | grep -v '^$' | sort | uniq -c | sort -rn | head -50

   That's the hot-zone list: files touched most often in the last 90 days. Include it in the sub-agent's prompt verbatim — it's a strong proxy for "where the action is."

3. Read the existing briefs list. Glob .agent-docs/*.md and collect existing slugs — these are the de-dupe set. If .agent-docs/ doesn't exist yet, the de-dupe set is empty (every suggestion is fair game).

4. Spawn an Explore agent with very thorough breadth and this exact prompt (substituting <limit>, <hot-zones>, <existing-slugs>):

   Scan this repo and identify subsystems, flows, or decisions that would benefit from an agent-docs brief. A good candidate has at least one of:

   1. Structural complexity — many collaborators, async/parallel execution, retry/cache/rate-limit layers, multi-stage pipelines, state machines.
   2. Cross-cutting concerns — auth, persistence boundaries, external API clients, message buses, sidecars, scheduling.
   3. Non-obvious decisions encoded in code — workarounds, deprecations-in-progress, custom replacements for stdlib/framework features, "we don't use library X because…" comments.
   4. Past-incident traces — comments containing "we got burned", "do not", "don't", "deprecated because", "workaround for", references to ticket numbers.
   5. Hot zones in recent git history — see the hot-zone list below. Files appearing repeatedly usually mark active or unstable areas worth documenting.

   Hot-zone list (top files by commit frequency, last 90 days):

   <hot-zones>

   Already-documented slugs (skip these and overlapping topics):

   <existing-slugs>

   For each candidate, output exactly this block in order:

   ### <number>. <slug>
   **Scope:** <one sentence — what the brief would cover>
   **Why:** <one sentence — what makes this worth documenting (cite the criterion 1–5 above)>
   **Tracks:** `<path or glob>`, `<path or glob>`, ...   (2–5 entries)
   **Risk if undocumented:** <one short clause — what breaks for a fresh agent without this brief>

   Return up to <limit> candidates, ranked most-critical-first. Mix criteria — don't return ten "hot zone" entries if there are also gnarly cross-cutting concerns worth surfacing. Skip trivially small subsystems (single file, no collaborators) unless they encode a non-obvious decision.

   Be honest about the signal: if the repo is small and there are fewer than <limit> worthwhile candidates, return fewer. Padding the list dilutes the value of the top entries.

   No prose around the list, just the numbered blocks.

5. Present the results to the user verbatim (the structured block is the deliverable — don't re-summarize it). Prepend a one-line header: Found N candidate(s) worth a brief. Append a one-line footer:

   Run /agent-docs write <slug> to draft any of these, or /agent-docs explore --limit <N> for more.

6. Do not auto-trigger write. The user decides which (if any) to document. This sub-command is read-only and side-effect-free.

Notes on explore

• If the hot-zone collection fails (shallow clone, no commits in 90d), skip it silently — the sub-agent still has the codebase itself.
• If <existing-slugs> is large (more than ~30), pass a truncated list with a (showing first 30 of N) marker; full overlap-checking against many briefs is the user's job.
• The agent uses Explore, not general-purpose — Explore is tuned for fast read-heavy traversal and won't try to edit anything.

Conventions

• English only for brief content. Identifiers and paths are English; agents read English best.
• Slugs: kebab-case, ASCII only.
• Tracks: paths relative to repo root. Globs allowed (src/foo/**, V21*). 3–8 entries per brief.
• last_verified_sha: full SHA, captured at write time only. Never edit manually.
• Don't auto-commit. Ever. The user commits.
• Don't write briefs outside .agent-docs/. No README.md-style sprawl.
• Don't be clever with the brief format. Keep the five sections, in order, even if one is short.

Sub-agent usage

The write command spawns an Explore agent. Do not do the research inline in the main context — that's the whole point. Decoupling exploration from synthesis is what keeps the brief useful and the main context small.

The Explore prompt in step 5 is opinionated; use it as written. Adjust only the topic name and scope sentence the user provided.

Failure modes

What this skill is NOT

• Not a general documentation generator. Don't trigger on "write documentation for X" — only on explicit /agent-docs ... invocations.
• Not a code-review tool. It describes; it doesn't judge.
• Not a replacement for inline code comments where the why is genuinely local.
• Not append-only. Briefs are rewritten when stale, not patched.