Skills: Documentation Generation Skills
Last updated: 2026-08-31
Good code should be self-documenting, but good documentation saves newcomers from detours — Skills ensure documentation is never the forgotten corner.
1. Documentation Types & Skills
(1) Documentation Type Matrix
| Doc Type | Input Source | Output Format | Skill Tools |
|---|---|---|---|
| API Docs | Routes/interface definitions | Markdown/HTML | Read, Grep, Write |
| README | Project config | Markdown | Read, Glob, Write |
| Changelog | git log | Markdown | Bash, Read, Write |
| Code Comments | Source code | Inline comments | Read, Edit |
| Architecture Docs | Project structure | Mermaid + Markdown | Glob, Read, Write |
(2) Documentation Quality Standards
TEXT
📖 Display only
Good documentation should be:
├── Accurate: Consistent with actual code behavior
├── Complete: Cover all public interfaces
├── Concise: No fluff, every sentence carries information
├── Timely: Updated when code changes
└── Accessible: Uniform format, easy to search
2. API Documentation Generation
(1) Extract APIs from Code
MARKDOWN
## API Doc Generation Flow
1. Glob to find route/controller files
2. Read each interface definition
3. Extract: path, method, parameters, return values, exceptions
4. Organize output by module
(2) Documentation Template
MARKDOWN
## POST /api/users
### Description
Create a new user
### Request Parameters
| Parameter | Type | Required | Description |
|:----------|:-----|:---------|:------------|
| name | string | Yes | Username |
| email | string | Yes | Email address |
### Return Values
| Field | Type | Description |
|:------|:-----|:------------|
| id | integer | User ID |
| name | string | Username |
### Exceptions
| Status Code | Description |
|:------------|:------------|
| 400 | Parameter validation failed |
| 409 | Email already exists |
3. README Generation
(1) Auto-Detect Project Information
MARKDOWN
## README Information Collection
1. Glob: Detect project files (package.json/go.mod/pyproject.toml)
2. Read: Read config to get tech stack, dependencies, scripts
3. Grep: Search for entry files, environment variables, config items
4. Bash: git log --oneline -10 to get recent changes
(2) README Template
MARKDOWN
# Project Name
> One-sentence description
## Quick Start
### Requirements
- Node.js >= 18
- PostgreSQL >= 14
### Install
```bash
npm install
cp .env.example .env
npm run dev
Project Structure
...
Development Guide
...
Deployment
...
---
## 4. Changelog Generation
### (1) Extract Changes from Git
```bash
# Get changes between versions
git log v1.1.0..v1.2.0 --oneline
git log v1.1.0..v1.2.0 --format="%s" --no-merges
(2) Categorize and Organize
MARKDOWN
## v1.2.0 (2026-08-15)
### ✨ New Features
- Add user export functionality (#42)
- Support dark mode (#45)
### 🐛 Fixes
- Fix login timeout issue (#38)
- Fix data sorting error (#41)
### 💔 Breaking Changes
- API /users return format changed, name field renamed to username
5. Documentation Skill Practice
▶ Example: Full Project Documentation Generation
Alice created a one-click project documentation generation Skill:
YAML
---
name: doc-generator
description: "One-click complete project documentation generation"
triggers:
- keyword: "gen-docs"
tools:
- Read
- Grep
- Glob
- Write
- Bash
---
Bob said: "The biggest enemy of documentation is becoming outdated — Skills extract information from code in real-time, ensuring docs and code are always in sync."
❓ FAQ
Q Do auto-generated docs need manual review?
A Absolutely. AI can extract structural information, but business meaning and usage scenarios need human supplementation and confirmation.
Q Where should documentation go?
A API docs in
docs/api/, README in project root, changelog in CHANGELOG.md, architecture docs in docs/architecture/.Q How to keep documentation in sync with code?
A Add documentation check steps in CI; Skills auto-update relevant docs on code changes; check doc sync during PR review.
📖 Summary
- Five doc types: API, README, changelog, code comments, architecture docs
- API docs: Extract interface definitions from code, output by template
- README: Auto-detect project info, fill standard template
- Changelog: Extract commit records from Git, categorize and organize
- Core principle: Documentation synced with code; AI extracts structure + human supplements semantics
📝 Exercises
- Basic (⭐): Create a README generation Skill that auto-detects project tech stack and outputs a standard template.
- Intermediate (⭐⭐): Create an API documentation generation Skill that extracts interface info from FastAPI/Express route files.
- Advanced (⭐⭐⭐): Create a full project documentation generation Skill outputting README + API docs + architecture diagram + changelog as a complete set.
