agentleFS
khairoldkhairold/claude-skills/skills/docs-audit/SKILL.md

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

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-agentsSkill

    docs-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-agentsSkill

    docs-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

  • VercelSkill

    docs-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

  • GoogleSkill

    docs-writer

    Also in 3 projects that use this

  • MicrosoftSkill

    writing-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

  • GoogleSkill

    domain-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

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
  1. Distinctive:

    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.

    line 42
  2. Distinctive:

    Look for the same topic covered in multiple files.

    line 87
  3. Distinctive:

    If yes, mark for deletion.

    line 106
  4. Distinctive:

    Do NOT execute without explicit approval.

    line 147

“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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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:

NeedExampleWhy 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-patternWhy it's wasteWhat to do
File structure listingsAgent runs find and ls — faster, always accurateDelete
Component inventoriesAgent reads the registry file or scans the directoryDelete
Implementation details"AnimatedNumber uses TextInput because..." — agent reads the sourceDelete, or move to a code comment if truly non-obvious
Color/token tablesAgent reads global.css or the theme fileDelete
Function counts, line counts, test countsAgent counts them — and the doc is wrong within a weekDelete
Hook/utility descriptions"useAuthQuery skips when unauthenticated" — agent reads the 20-line hookDelete

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

LensQuestionSignal
StaleDoes this doc describe something that no longer matches the code?Colors, counts, file paths, feature lists that drifted
ContradictoryDo two docs say different things about the same topic?Two architecture files, nav structure in 3 places
DuplicateIs the same information maintained in two places?Every duplicate is a future contradiction
GhostDoes 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/*" | sort

For 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"
done

Step 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 → find is 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

CategoryCountAction
StaleNFix or delete
ContradictoryNResolve to one source
DuplicateNMerge into one authority
GhostNFix references or delete
UnnecessaryNDelete
SoundNKeep

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:

  1. Fix stale docs first — update values to match code
  2. Resolve contradictions — pick the authoritative source, update it, delete or redirect the other
  3. Merge duplicates — move unique content to the surviving file, delete the duplicate, fix cross-references
  4. Remove ghosts — fix or delete phantom references
  5. Delete unnecessary sections/files — for sections within a file, surgically remove; for entire files, delete and fix all cross-references
  6. Typecheck after each batch — docs changes shouldn't break builds, but cross-reference fixes in code comments might
  7. 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.