Docs Generate

---
model: opus
created: 2025-12-16
modified: 2026-02-05
reviewed: 2025-12-16
allowed-tools: Task, TodoWrite
argument-hint: [--api] [--readme] [--changelog]
description: Update project documentation from code annotations
name: docs-generate
---

## Context

- Project files: !`find . -maxdepth 1 \( -name 'pyproject.toml' -o -name 'package.json' -o -name 'Cargo.toml' -o -name 'go.mod' \) 2>/dev/null`
- Existing docs: !`find . -maxdepth 1 \( -name 'README.md' -o -type d -name 'docs' \) 2>/dev/null`
- Source files: !`find . -type f \( -name "*.py" -o -name "*.ts" -o -name "*.js" \) 2>/dev/null`
- Python with docstrings: !`grep -r "\"\"\"" --include="*.py" -l 2>/dev/null`

## Parameters

- `--api`: Generate API reference documentation
- `--readme`: Update README.md based on code analysis
- `--changelog`: Update CHANGELOG.md from git history

## Your task

**Delegate this task to the `documentation` agent.**

Use the Task tool with `subagent_type: documentation` to generate or update project documentation. Pass all the context gathered above and the parsed parameters to the agent.

The documentation agent should:

1. **Analyze codebase**:
   - Extract docstrings and type annotations
   - Identify public API surface
   - Map module structure and dependencies
   - Find usage examples in tests

2. **Generate requested documentation**:

   If `--api`:
   - Create API reference from docstrings
   - Document function signatures and types
   - Include usage examples
   - Generate module hierarchy

   If `--readme`:
   - Update project description
   - Document installation steps
   - Add usage examples
   - Update feature list
   - Ensure badges are current

   If `--changelog`:
   - Parse conventional commits
   - Group by version/release
   - Categorize by type (feat, fix, docs, etc.)
   - Include breaking changes prominently

   If no flags: Generate all documentation

3. **Follow documentation standards**:
   - Clear, concise language
   - Consistent formatting
   - Working code examples
   - Accurate cross-references

4. **Output summary**:
   - Files created/updated
   - Documentation coverage metrics
   - Suggested improvements

Provide the agent with:
- All context from the section above
- The parsed parameters
- Detected documentation framework (if any)

The agent has expertise in:
- Multi-language documentation extraction
- API reference generation
- README best practices
- Changelog automation from commits
- GitHub Pages integration

## Agent Teams (Optional)

For large projects, spawn teammates for parallel documentation generation:

| Teammate | Focus | Value |
|----------|-------|-------|
| API docs teammate | Extract and generate API reference | Parallel with README generation |
| README teammate | Update project README and guides | Parallel with API docs |
| Changelog teammate | Generate changelog from git history | Independent of other doc tasks |

This is optional — the skill works with a single agent for most projects.