Docs

Generate Documentation

$ARGUMENTS

Generate or update documentation.

Usage

/docs [type] [target]

What This Command Does

1. Analyzes code structure
2. Extracts documentation info
3. Generates documentation files
4. Updates existing docs

Documentation Types

| Type | Description | |------|-------------| | readme | Generate/update README | | api | API documentation | | architecture-note | Architecture note | | changelog | Generate changelog | | comments | Add code comments | | kb | Knowledge base entry (enforces KB structure) |

KB Document Rules (MANDATORY)

When creating or updating documents in the kb/ directory, follow the documentation-standards knowledge skill (auto-loaded). Key rules:

• 7 required frontmatter fields: title, category, service, tags, created, last_updated, description
• 6 valid categories: reference, howto, procedures, troubleshooting, best-practices, planning
• Category must match directory (e.g., category: howto → kb/howto/)
• English only. No exceptions.
• validate.sh rejects docs without valid frontmatter.

Full spec: see app/skills/documentation-standards/SKILL.md.

Templates

README Generation

# [Project Name]

[Auto-generated description]

## Installation
[Detected from package manager]

## Usage
[Extracted from code/examples]

## API
[Extracted from code]

## License
[Detected]

Architecture Note Template

# Architecture Note: [TITLE]

## Status
Proposed

## Context
[What is the issue?]

## Decision
[What was decided?]

## Consequences
[What are the results?]

## Date
[Today's date]

Output Format

## Documentation Report

### Generated
- [file 1]
- [file 2]

### Updated
- [file 3]: [what changed]

### Skipped
- [file 4]: [reason]

### Next Steps
- [ ] Review generated docs
- [ ] Add missing details
- [ ] Commit changes

Common Rationalizations

| Excuse | Why It's Wrong | |--------|----------------| | "The code is self-documenting" | Code shows how, not why — decisions, constraints, and context need prose | | "Nobody reads docs anyway" | People don't read bad docs — good docs are the first thing consulted | | "I'll document it when it's stable" | Unstable code needs docs most — document intent so others can contribute | | "Comments get stale" | That's an argument for maintaining docs, not skipping them | | "The tests are the documentation" | Tests verify behavior but don't explain architecture, trade-offs, or setup |

Configuration

Documentation settings in:

• .claude/settings.json
• Project's doc config

REVIEW BEFORE COMMIT

Generated documentation should be reviewed. AI may miss context or make assumptions.

Documentation Inventory

Run the bundled script to audit documentation coverage and find gaps:

python3 ${CLAUDE_SKILL_DIR}/scripts/doc-inventory.py .

Parallel Documentation (large codebases)

If the inventory script reports doc_coverage_percent < 50 and the project has multiple modules, use Agent Teams for parallel documentation:

Create an agent team for documentation:
- Teammate 1 (documenter): "Document the [module-1] directory. Generate docstrings for all public functions." Use Sonnet.
- Teammate 2 (documenter): "Document the [module-2] directory. Generate docstrings for all public functions." Use Sonnet.
- Teammate 3 (documenter): "Generate README sections: installation, usage, API reference." Use Opus.
Teammates should NOT overlap — each owns their assigned scope.

Related Skills

• Documenting an architecture decision? → /council for multi-perspective analysis first
• Need to explore the codebase? → /explore to understand structure before documenting
• Writing a PRD? → /write-a-prd for structured product requirements
• Auditing existing docs? → /analyze for coverage gaps

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: softspark
• Source: softspark/ai-toolkit
• License: MIT
• Homepage: https://softspark.eu

Install and usage instructions live in the source repository linked above.