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.
agent-docs is a Claude Code skill that writes self-staleness-aware briefs for any feature in your repo. Briefs are written by agents, for agents, read by you.
/agent-docs explore # what should I document?
/agent-docs write source-provenance-pipeline
/agent-docs explain source-provenance-pipeline
/agent-docs list
/agent-docs check source-provenance-pipeline
Each brief tracks the file paths it describes and the git SHA at which it was verified. Next time you ask Claude to explain that feature, the skill diffs the current HEAD against that SHA, warns if the underlying code has drifted, and tells you honestly which parts of the explanation are no longer trustworthy.
Agentic engineering ships more code than any human can keep up with. Traditional documentation can't survive that pace, it goes stale before the next sprint. But agents have grep and we have agents. So instead of documentation written for humans who won't read it, we write briefs for agents who will, and let them explain to us on demand.
The bet:
- Briefs, not documentation. Five fixed sections (Brief, Where it lives, Flow, Invariants, Gotchas). Skim in twenty seconds, agent-readable.
- Staleness is detectable, not avoidable. Every brief records the SHA and paths it was verified against. Drift is surfaced, not hidden.
- Sub-agent research, main-context synthesis. Writing a brief spawns an
Exploreagent. Your main context stays small.
git clone https://github.com/KyleKreuter/agent-docs.git ~/.claude/skills/agent-docs
chmod +x ~/.claude/skills/agent-docs/find.py
ln -sfn ~/.claude/skills/agent-docs/commands ~/.claude/commands/agent-docsThat's it. Restart Claude Code (or /reload) and the skill is available.
Requirements: git, python3 (stdlib only, no extra packages).
The third line symlinks the bundled slash-command wrappers so each sub-command shows up in Claude Code's /-autocomplete with its own description and argument hint:
/agent-docs:explore Scan repo and suggest topics worth a brief
/agent-docs:write <topic-slug> Generate or refresh an agent-docs brief
/agent-docs:explain <topic-slug-or-partial> Read brief, check staleness, explain
/agent-docs:list List all briefs with staleness state
/agent-docs:check <topic-slug-or-partial> One-line staleness check
If you skip the symlink, the skill still works — you just lose the autocomplete hints and have to invoke it via free-form prompts like /agent-docs write ….
Scans the repo, identifies subsystems that would benefit from a brief, and returns a ranked candidate list. Uses recent git activity (90-day hot-zones) as one signal, plus structural complexity, cross-cutting concerns, non-obvious decisions, and past-incident traces. Already-documented topics are filtered out automatically. Read-only — won't write anything; you pick what to draft with /agent-docs write.
- Skill confirms scope in one sentence
- Spawns an
Exploreagent to research the topic - Synthesizes findings into the five-section format
- Shows you the draft for confirmation
- Writes
.agent-docs/<topic>.mdwith the currentHEADSHA aslast_verified_sha
- Fuzzy-resolves the topic via a small Python helper (exact → substring → Levenshtein)
- Reads the brief, parses
tracksandlast_verified_shafrom frontmatter - Runs
git diff --name-only <sha>..HEAD -- <tracks>to detect drift - Explains the feature, honestly flagging which sections may be stale if drift exists
Compact table of every brief with fresh / stale / stale_unknown state. Sorted stale-first.
One-line staleness verdict. Good as a pre-commit gut check.
---
topic: source-provenance-pipeline
tracks:
- src/main/java/io/faktum/backend/provenance/
- src/main/resources/db/migration/V21*
last_verified_sha: a36d96eb1c4f...
---
## Brief
One paragraph: what this is, why it exists.
## Where it lives
- src/.../ProvenanceService.java — entry point, enqueues claims
- src/.../ProvenanceResearcher.java — per-publisher agent
- ...
## Flow
1. Triggered after publishCheckCompleted.
2. For each unique publisher in the fact-check's sources …
3. ...
## Invariants
- One row per source_id in `source_provenance` — UNIQUE constraint enforces it.
- ...
## Gotchas
- Don't bypass WebSearchCacheService here — domain-restricted queries skip the cache by design, but provenance queries are general and should hit it.
- ...Five sections, in this order, always. The format is opinionated on purpose: predictable layout means an agent always knows where to look, and a human can skim it in twenty seconds.
| Decision | Choice |
|---|---|
| Storage | .agent-docs/ at the repo root |
| Scope per file | One topic = one file. Topic is whatever you want it to be — feature, subsystem, workflow, decision. |
| Language | English, always. Identifiers are English, agents work most precisely in English. |
| Staleness | tracks + last_verified_sha frontmatter. Diff at read time. |
| Fuzzy match | Python stdlib difflib. Exact → substring → Levenshtein-like. |
| Hooks | None (v1). Strictly user-invoked. |
| Auto-commit | Never. The user commits when they're ready. |
The skill spawns a sub-agent for research, not for synthesis. The five-section format is small enough that the main context can write it cleanly from the research summary.
| Traditional docs | agent-docs |
|
|---|---|---|
| Reader | Humans | Agents (and humans) |
| Update model | Manual, decays silently | Detected via git SHA + tracked paths |
| Granularity | Files / classes | Topics (your choice) |
| Storage | docs/ (sprawling) |
.agent-docs/ (flat) |
| Format | Free-form, varies | Five fixed sections |
| Generation | Human writes | Sub-agent researches, main agent synthesizes |
| Staleness | Hope | Verified |
- Not a general-purpose documentation generator. It triggers only on explicit
/agent-docs ...commands. - Not a code-review tool. It describes; it doesn't judge.
- Not a replacement for inline comments where the why is genuinely local.
- Not append-only. Briefs are rewritten when stale, not patched.
MIT. See LICENSE.
Built for Claude Code. Issues and PRs welcome.