Code Documenter Skill
An intelligent documentation system that analyzes codebases and generates thorough, comprehensive documentation tailored to your project type and audience needs.
Core Philosophy
Documentation serves readers, not authors. Every decision about structure, depth, and content is evaluated from the reader's perspective:
- Will this help them understand?
- Will this help them succeed?
- Will this answer their questions?
- Does this earn its place?
Comprehensive without overwhelm. Thorough coverage of what matters, ruthless cutting of what doesn't. The goal is complete, accurate, useful documentation—not exhaustive documentation of every line of code.
Documentation as code artifact. Docs should be versioned, tested, and maintained with the same rigor as code. They're not afterthoughts; they're essential.
When to Use This Skill
Primary use cases:
- After completing significant new work (epic, major feature, new app)
- When shipping an open source project
- When documentation has fallen out of sync with code
- When onboarding requires better documentation
- When setting up a new project properly
Not for:
- In-progress features (wait until stable)
- Code comments or docstrings (this generates external docs)
- API reference generation from code (use language-specific tools for that)
Session Flow
Mode Selection
The skill operates in two modes:
| Mode | When to Use | Behavior | | ---------------------- | ----------------------------------------------- | ------------------------------------------------- | | Quick Mode | Incremental updates after new features | Autonomous, fast, focused on what changed | | Comprehensive Mode | New projects, major overhauls, first-time setup | Collaborative, thorough, quality gates throughout |
The skill will ask: "Quick update or comprehensive documentation?"
Phase 1: Multi-Agent Project Analysis
The skill deploys specialized analysis agents to understand your project:
Analysis Phase:
├─ Agent 1: Project Structure
│ └─ Scanning file tree, identifying project type, tech stack
├─ Agent 2: Code Surface Analysis
│ └─ Finding APIs, components, commands, exports
├─ Agent 3: Dependency Analysis
│ └─ Reviewing packages, frameworks, key dependencies
├─ Agent 4: Git History Analysis
│ └─ Analyzing commits since last doc update
├─ Agent 5: Existing Documentation Review
│ └─ Reading current docs, assessing state
└─ Synthesis: Generating documentation plan...Quick Mode: Focused analysis on what changed since last update Comprehensive Mode: Full analysis of entire project
Each agent reports findings in structured format. You see everything happening.
Phase 2: Documentation State Assessment
The skill compares code state vs. documentation state:
If manifest exists (.doc-state.json):
- Loads documentation state from last run
- Compares current code vs. last documented state
- Identifies what's changed (added/modified/removed)
- Shows you the documentation debt
If no manifest:
- First time documenting this project
- Will create fresh manifest after completion
Key metrics shown:
- Health Score: Current documentation health (0-100)
- Coverage: What % of public surface is documented
- Freshness: How current are docs vs. code
- Debt: What needs attention (prioritized)
Phase 3: Audience & Scope Discovery
The skill asks:
- "Who needs these docs?"
- Developers only
- Users only
- Both developers and users
- "What depth of documentation?"
- Standard: Right-sized coverage (4,000-7,000 words)
- Deep: Comprehensive with internals (8,000-12,000 words)
Quick Mode: Uses stored preferences from manifest Comprehensive Mode: Asks explicitly, shows examples
Phase 4: Documentation Boundaries
The skill proposes what should be documented:
Based on my analysis of your Express + PostgreSQL API:
PUBLIC SURFACE (Always Document)
├─ 12 API endpoints in /routes
├─ Database schema (3 tables)
├─ 14 environment variables
└─ Authentication flow
INTERNAL IMPLEMENTATION (Recommended for Deep)
├─ 6 middleware functions
├─ Error handling patterns
└─ Database migration strategy
INFRASTRUCTURE (Essential for all levels)
├─ Docker setup
├─ CI/CD pipeline
└─ Deployment process
EXCLUDED (Recommend skip)
├─ Test files (obvious from names)
├─ Build scripts (standard tooling)
└─ Internal helpers (<10 lines each)
Adjust these boundaries? [approve/modify]You approve or adjust before documentation generation begins.
Phase 5: Documentation Plan Presentation
The skill presents a complete plan:
DOCUMENTATION PLAN
Structure:
└─ /docs
├─ developers/
│ ├─ api.md (API endpoint reference)
│ ├─ architecture.md (System design + diagrams)
│ ├─ contributing.md (How to contribute)
│ ├─ deployment.md (Deploy & operate)
│ ├─ troubleshooting.md (Common issues)
│ ├─ examples/ (12 runnable examples)
│ └─ adr/ (4 architecture decisions)
├─ users/
│ ├─ getting-started.md (Quick start guide)
│ ├─ features.md (Feature overview)
│ ├─ troubleshooting.md (User-facing issues)
│ └─ examples/ (5 user examples)
├─ CHANGELOG.md (Documentation change log)
└─ documentation-map.md (Navigation guide)
Files to update:
- README.md (complete rewrite, progressive disclosure)
- docs/developers/api.md (2 new endpoints, 1 modified)
- docs/CHANGELOG.md (new entry)
Files to create:
- docs/adr/004-caching-strategy.md (new decision)
- docs/developers/examples/pagination.js (new example)
Files to remove:
- docs/developers/legacy-auth.md (endpoint removed)
Estimated scope: ~5,200 words total
Target health score: 92/100
Proceed? [yes/adjust scope/abort]Comprehensive Mode: Review and approve before generation Quick Mode: Brief preview, option to review or proceed
Phase 6: Documentation Generation
Comprehensive Mode (with Quality Gates)
The skill works through documentation in phases, pausing for review:
Gate 1: Core Documentation (README + Getting Started)
- Generates README with progressive disclosure
- Creates getting started guides
- Quality Check: Does this hook and onboard effectively?
- You review and approve or request changes
Gate 2: Reference Documentation (API/Commands/Components)
- Generates reference documentation
- Creates working examples
- Quality Check: Is everything covered? Examples clear?
- You review and approve or request changes
Gate 3: Architecture & Decisions
- Documents architecture with Mermaid diagrams
- Creates ADRs for key decisions
- Quality Check: Does this explain the WHY?
- You review and approve or request changes
Gate 4: Supporting Documentation
- Generates troubleshooting guides
- Creates contributing guidelines
- Documentation map for navigation
- Quality Check: Complete and helpful?
- You review and approve or request changes
Gate 5: Polish & Verification
- Generates test scripts for examples
- Creates link validation script
- Runs accessibility check
- Final health score calculation
- Final review
Quick Mode (Autonomous)
The skill executes the plan efficiently:
- Updates only changed sections
- Preserves manual edits in unchanged areas
- Generates new content as needed
- Updates manifest and changelog
- Reports final results
Phase 7: Session Completion
The skill produces:
Files Created/Updated:
- All documentation files as planned
.doc-state.json(updated manifest)docs/CHANGELOG.md(new entry)- Test and validation scripts
Documentation Health Report:
DOCUMENTATION HEALTH REPORT
Overall Health Score: 92/100 (↑ from 78)
Component Scores:
├─ Coverage Health: 95/100 (↑ from 82)
│ └─ 97% of public surface documented
├─ Freshness Health: 98/100 (↑ from 65)