code-documenter
Code Documenter Skill
robertguss · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add robertguss/claude-code-toolkit --skill code-documenter技能说明
name: code-documenter description: Expert documentation generator for coding projects. Analyzes codebases to create thorough, comprehensive documentation for developers and users. Supports incremental updates, multi-audience documentation, architecture decision records, and documentation health tracking. Works with any project type (APIs, CLIs, web apps, libraries). Use when you need to document a new project, update docs after adding features, or create comprehensive documentation for open source releases.
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
阅读完整来源 ↗