docs-audit
Skill0 starsChanged 7 months agoMITView on GitHub
Audit project documentation for agent effectiveness. Identifies docs that are stale, contradictory, duplicated, ghost-referenced, or simply unnecessary — because coding agents read code, not inventories. Produces a concrete reduction plan. Use when asked to "audit docs", "clean up documentation", "are these docs useful", or "optimize docs for agents".
17 other projects use a version of this.
Adopted by
Most recently taken up by
- fullstackhouse/skillstheir own version, first seen Nov 15, 2026
- willdady/platypustheir own version, first seen Nov 15, 2026
- tstraub89/canon-aitheir own version, first seen Nov 8, 2026
- home-screens/home-screenstheir own version, first seen Nov 8, 2026
- colonyops/hivetheir own version, first seen Nov 7, 2026
- lifekit-hq/devclawtheir own version, first seen Oct 21, 2026
Used with
Projects with it also use docs-planner, docs-reviewer and 5 more.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
strands-agentsSkilldocs-planner
Find the gaps in the Box documentation and produce a prioritized backlog for docs/user/ and docs/design/. Use when planning documentation work, after a feature or a binary ships without a page, for a periodic health check of the docs, or when asked "what docs need writing", "plan the docs work", "prioritize the docs backlog", or "what should we document next".
Also in 3 projects that use this
strands-agentsSkilldocs-reviewer
Review Box drafts in docs/user/ or docs/design/, and wording-only rewrites in docs/dev/. Use after docs-writer, before a docs pull request, or for a requested doc review. Check style and preservation of meaning, then give a Ship it, Tighten, or Rethink verdict. Read-only.
Also in 3 projects that use this
VercelSkilldocs-diagrams
Draw diagrams for the Next.js docs in the style of the ones already published there: the light/dark PNGs an mdx references with `<Image srcLight="/docs/light/<name>.png" srcDark="/docs/dark/<name>.png">`. Use when a guide or API reference needs a new diagram or an existing one needs a change. Hand-written SVG from a primitives library, rendered by headless Chrome at 2x. No AI image generation.
Also in 3 projects that use this
GoogleSkilldocs-writer
Also in 3 projects that use this
MicrosoftSkillwriting-for-agents
Writing documents for agents. Use when creating or editing skills, or modifying AGENTS.md or CLAUDE.md.
Also in 3 projects that use this
GoogleSkilldomain-modeling
Build and sharpen a project's domain model. Use when the user wants to pin down domain terminology or a ubiquitous language, record an architectural decision, or when another skill needs to maintain the domain model.
Also in 3 projects that use this
Other versions17 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 17
- mastra-ai/mastra★ 30ksame name
- strands-agents/sdk-python★ 9.2ksame name
- strands-agents/harness-sdk★ 8.9ksame name
- hiroppy/tmux-agent-sidebar★ 568same name
- strands-agents/box★ 547same name
- me2resh/apexyard★ 542same name
- Seekers2001/docs-governance★ 320same name
- qshanx/docs-governance★ 253same name
- willdady/platypus★ 130same name
- home-screens/home-screens★ 104same name
7 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository8 other files it gives its agents.
- autopilot-executeSkill
- close-planSkill
- deep-modules-auditSkill
- execute-phaseSkill
- lint-fixSkill
- living-design-systemSkill
- phased-planSkill
- responsive-auditSkill
The file
We split this skill into the rules it gives an agent
4 rules. 0 are common, 4 are distinctive, and 0 are very specific to this project.
0
Common
Most of the 14 edited versions we read keep these.
4
Distinctive
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 42
The test: If an agent would learn the same thing faster by reading the source file than by reading the doc, the doc is waste.
- Distinctive: line 87
Look for the same topic covered in multiple files.
- Distinctive: line 106
If yes, mark for deletion.
- Distinctive: line 147
Do NOT execute without explicit approval.
“Common” is measured: kept by at least 6 in 10 of the 14 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Docs Audit
Audit project documentation from the perspective of a coding agent who has read, grep, find, and ls.
The Core Insight
Documentation written for humans in IDEs serves a different purpose than documentation for AI agents with tool calls. Agents can scan a file tree in milliseconds, read any source file on demand, and grep across the entire codebase. Most project documentation was written before agents existed — it assumes the reader can't do these things.
The result is documentation debt: files that cost maintenance effort (they drift, they contradict, they require co-editing) but provide no value to the agent who is the primary consumer.
What Agents Actually Need from Docs
Agents need docs for things they cannot derive from code:
| Need | Example | Why code isn't enough |
| Rules to follow | "Use <Text variant>, never raw Tailwind text classes" | Convention — compiler doesn't enforce it |
| Reasons behind choices | "Why Convex not Supabase" | Intent is invisible in implementation |
| Traps to avoid | "React Compiler breaks obj!.prop in ternaries" | You only discover these by hitting them |
| What NOT to build | "Offline support is deferred to v1.1" | Absence is invisible in code |
| Business context | "Built for contractors standing in a yard, phone in one hand" | Shapes every product decision |
What Agents Do NOT Need from Docs
Agents waste tool calls on docs that describe things they can observe directly:
| Anti-pattern | Why it's waste | What to do |
| File structure listings | Agent runs find and ls — faster, always accurate | Delete |
| Component inventories | Agent reads the registry file or scans the directory | Delete |
| Implementation details | "AnimatedNumber uses TextInput because..." — agent reads the source | Delete, or move to a code comment if truly non-obvious |
| Color/token tables | Agent reads global.css or the theme file | Delete |
| Function counts, line counts, test counts | Agent counts them — and the doc is wrong within a week | Delete |
| Hook/utility descriptions | "useAuthQuery skips when unauthenticated" — agent reads the 20-line hook | Delete |
The test: If an agent would learn the same thing faster by reading the source file than by reading the doc, the doc is waste.
The Four Lenses
| Lens | Question | Signal |
| Stale | Does this doc describe something that no longer matches the code? | Colors, counts, file paths, feature lists that drifted |
| Contradictory | Do two docs say different things about the same topic? | Two architecture files, nav structure in 3 places |
| Duplicate | Is the same information maintained in two places? | Every duplicate is a future contradiction |
| Ghost | Does a doc reference files, features, or values that don't exist? | Phantom file paths, deleted components, old names |
Beyond these four, apply the deeper question: Does this doc exist for the agent or for the human? Human-facing docs (deployment checklists, business strategy, marketing plans) are fine — just don't optimize them for agent consumption. Agent-facing docs should contain only what the agent can't derive from code.
Process
Step 1 — Inventory
Find all documentation files. Categorize by audience:
find . -name "*.md" -not -path "*/node_modules/*" -not -path "*/.git/*" | sortFor each file, determine: Is this primarily for the agent (conventions, architecture, gotchas) or for the human (deployment guides, business strategy, checklists)?
Step 2 — Cross-Reference Against Code
For every factual claim in agent-facing docs, verify against the actual code:
- File paths mentioned → do they exist?
- Counts (tests, components, functions) → are they accurate?
- Color values, config values → do they match source?
- Feature descriptions → does the code reflect this?
- Navigation structure, tab counts → does the layout match?
# Example: check if referenced files exist
grep -oP '`[^`]+\.(ts|tsx)`' ARCHITECTURE.md | sort -u | while read f; do
path="${f//\`/}"
ls "$path" 2>/dev/null || echo "GHOST: $path"
doneStep 3 — Detect Duplicates and Contradictions
Look for the same topic covered in multiple files. Common patterns:
- Two "architecture" files (root vs docs/)
- Design conventions in both a governance doc and a conventions doc
- Auth described in architecture, deployment, and TODO docs
- Component lists in architecture, design system, and conventions
For each duplicate, check: have they drifted? They almost always have.
Step 4 — Apply the "Can I derive this?" Test
For each section in agent-facing docs, ask: Would I learn this faster by reading the code?
- File structure listings →
findis faster and always accurate - Component tables with descriptions →
ls src/components/+ read any file - Hook inventories →
ls src/hooks/+ read the 20-line file - Animation implementation details → read the source file
- Color values → read the CSS/theme file
If yes, mark for deletion.
Step 5 — Produce the Report
Structure the audit:
🔴 Stale — Doc says X, code says Y
List each mismatch with the doc, what it claims, and what the code actually shows.
🟡 Contradictory — Two docs disagree
List each contradiction with both sources.
🔵 Duplicate — Same info, two places
List each duplication with the maintenance burden it creates.
👻 Ghost — References to things that don't exist
List phantom file paths, deleted components, wrong counts.
🗑️ Unnecessary — Agent can derive this from code
List sections or entire files that describe things the agent can observe directly.
🟢 Sound — Genuinely useful, keep
List docs that contain rules, decisions, gotchas, or context that can't be derived from code.
Summary
| Category | Count | Action |
| Stale | N | Fix or delete |
| Contradictory | N | Resolve to one source |
| Duplicate | N | Merge into one authority |
| Ghost | N | Fix references or delete |
| Unnecessary | N | Delete |
| Sound | N | Keep |
Step 6 — Wait for Go
Present the report and ask:
Do you want me to execute these changes? I'll do them in order: fix stale → resolve contradictions → merge duplicates → remove ghosts → delete unnecessary. Typecheck after each batch.
Do NOT execute without explicit approval.
Execution Protocol
When approved:
- Fix stale docs first — update values to match code
- Resolve contradictions — pick the authoritative source, update it, delete or redirect the other
- Merge duplicates — move unique content to the surviving file, delete the duplicate, fix cross-references
- Remove ghosts — fix or delete phantom references
- Delete unnecessary sections/files — for sections within a file, surgically remove; for entire files, delete and fix all cross-references
- Typecheck after each batch — docs changes shouldn't break builds, but cross-reference fixes in code comments might
- Verify no broken cross-references remain:
grep -rn "deleted-file" --include="*.md" . | grep -v node_modules
Principles
Docs are for what you can't see in the code
A doc that restates what the code does is a liability, not an asset. It will drift, and then it's worse than no doc — it's a lie.
Every doc file is a maintenance commitment
Each file you maintain is a file that can go stale, contradict another file, or mislead the agent. Fewer files = fewer lies. The goal is not comprehensive documentation — it's accurate documentation.
Convention docs are the highest-value docs
Rules that the compiler doesn't enforce ("use cn() not template literals", "shells can't import from Convex") are the docs agents need most. These prevent mistakes that pass typecheck but violate project intent.
Gotcha docs are the second-highest-value docs
Non-obvious traps ("React Compiler breaks obj!.prop", "collapsable={false} required on Android for measureInWindow()") save hours. These are the things you'd only learn by hitting them. Keep every one.
Decision docs prevent re-litigation
"Why Convex not Supabase" prevents the agent from proposing a migration. "Tab count is 5" prevents the agent from suggesting a redesign. Decisions with rationale are permanent value.
Human-facing docs are fine — just don't co-maintain them for agents
Deployment guides, business strategy, marketing plans, featuring playbooks — these serve the human. Don't delete them. But also don't try to keep them in sync with the code. They're reference material, not agent instructions.
When in doubt, delete
A deleted doc can be reconstructed from code. A stale doc actively misleads. Err on the side of deletion.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

