agentsclimarketplace
Sign in

Documentation audit

Skill tansuasici/claude-code-kit/.claude/skills/documentation-audit

Audit documentation quality — inline comments, API docs, README completeness, and doc-code sync. Use when assessing whether docs are good and complete. To catch docs that have gone stale versus the code use /doc-gardening instead.From its SKILL.md

Install
npx -y skills add tansuasici/claude-code-kit --skill documentation-audit

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

  • 2 stars2 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

5.4 KB, as published. Nobody here has run it

Documentation Audit

Core Rule

Audit doc-code sync and reader experience. Recommend rewrites only when current docs mislead — small fixes beat broad refactors.

When to Use

Invoke with /documentation-audit when:

  • Assessing documentation quality for a project
  • Preparing a project for open-source release
  • Onboarding new team members and finding documentation gaps
  • After major feature additions to ensure docs are updated
  • Before a due diligence or code quality review

Default Behavior

When the user asks to audit, scan, review, or "give me a report" for documentation, produce the full documentation-audit report automatically using the Process and Output Format sections below. Do not require the user to specify fields.

Only modify files when the user explicitly requests implement / fix / apply / refactor. By default, this skill is report-only.

Process

Phase 1: Inventory (first-pass leads)

This pass produces candidates, not findings. Treat counts as leads for deeper inspection in later phases. Do not report Phase 1 raw output as the final result.

Catalog existing documentation:

  1. README — Does it exist? Is it useful?
  2. API docs — Inline docs, generated docs, API reference
  3. Architecture docs — High-level design, system diagrams
  4. Inline comments — Code-level documentation
  5. Examples — Usage examples, tutorials, quickstart guides
  6. Changelog — Version history, migration guides

Phase 2: README Assessment

Evaluate the project README:

Essential Sections

  • Project name and one-line description
  • What the project does (not how it's built)
  • Quick start / installation instructions
  • Basic usage example
  • Prerequisites and requirements

Good-to-Have Sections

  • Configuration options
  • API overview or link to full docs
  • Contributing guidelines
  • License
  • Status badges (build, coverage, version)

Quality Checks

  • Are instructions copy-pasteable? (no placeholder values without explanation)
  • Are versions/requirements current?
  • Does the quick start actually work?

Phase 3: Inline Documentation

Audit code-level documentation:

Public API Documentation

  • Are public functions/methods documented? (parameters, return values, exceptions)
  • Are complex algorithms explained? (not what the code does, but why)
  • Are non-obvious design decisions documented?
  • Are edge cases and limitations noted?

Comment Quality

  • Useful comments: explain WHY, not WHAT (the code says what)
  • Outdated comments: comments that don't match the current code
  • Redundant comments: comments that repeat what the code already says
  • TODO/FIXME/HACK: are these tracked? Do they reference issues?
  • Commented-out code: should be removed, not commented

Anti-patterns

  • Functions with complex behavior but no documentation
  • Public APIs without parameter descriptions
  • Error codes/messages without explanation
  • Magic numbers without explanation
  • Regex patterns without explanation

Phase 4: API Documentation

If the project exposes an API (REST, GraphQL, library):

  • Are all endpoints/functions documented?
  • Are request/response schemas documented?
  • Are error responses documented?
  • Are authentication requirements documented?
  • Are rate limits and pagination documented?
  • Is there an OpenAPI/Swagger spec (REST) or schema file (GraphQL)?
  • Are examples provided for common use cases?

Phase 5: Documentation-Code Sync

Check that docs match reality:

  • Do documented APIs still exist? (no references to removed endpoints)
  • Do documented config options match the actual config schema?
  • Do code examples in docs actually compile/run?
  • Are version references current?
  • Do links in docs point to valid targets?

Output Format

# Documentation Audit Report

## Documentation Inventory
| Type | Exists | Quality | Notes |
|------|--------|---------|-------|
| README | ✅/❌ | Good/Fair/Poor | ... |
| API Docs | ✅/❌ | Good/Fair/Poor | ... |
| Inline Docs | ✅/❌ | Good/Fair/Poor | ... |
| Architecture | ✅/❌ | Good/Fair/Poor | ... |
| Examples | ✅/❌ | Good/Fair/Poor | ... |
| Changelog | ✅/❌ | Good/Fair/Poor | ... |

## Critical Gaps
1. [Undocumented public API / missing README section / outdated docs]

## Outdated Documentation
| Location | Issue | Current State |
|----------|-------|---------------|
| README line 45 | References removed config option | Option removed in v2.0 |

## Comment Quality Issues
| File | Line | Issue |
|------|------|-------|
| api/handler.ts | 23 | Comment contradicts code behavior |

## Recommendations
### Must Fix
1. ...

### Should Fix
1. ...

### Nice to Have
1. ...

## Documentation Score
[Overall: Poor / Fair / Good / Excellent]
[Key metric: % of public APIs documented]

Notes

  • Good documentation explains WHY, not WHAT — the code already says what
  • Don't recommend documenting everything — focus on public APIs, complex logic, and non-obvious decisions
  • Over-documentation is as bad as under-documentation — redundant comments become noise
  • Consider the audience: library docs need more than internal app docs

Keep looking

Skills are one crate of 627,801. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.