Skills: 文档生成技能
最后更新：2026-08-31
好代码应该自解释，但好文档能让后来者少走弯路——Skill 让文档不再是被遗忘的角落。
1. 文档类型与 Skill
(1) 文档类型矩阵
| 文档类型 | 输入源 | 输出格式 | Skill 工具 |
|---|---|---|---|
| API 文档 | 路由/接口定义 | Markdown/HTML | Read, Grep, Write |
| README | 项目配置 | Markdown | Read, Glob, Write |
| 变更日志 | git log | Markdown | Bash, Read, Write |
| 代码注释 | 源代码 | 内联注释 | Read, Edit |
| 架构文档 | 项目结构 | Mermaid + Markdown | Glob, Read, Write |
(2) 文档质量标准
TEXT
📖 仅展示
好的文档应该：
├── 准确：与代码实际行为一致
├── 完整：覆盖所有公开接口
├── 简洁：不说废话，每句话都有信息量
├── 及时：代码变更时同步更新
└── 可访问：格式统一，易于搜索
2. API 文档生成
(1) 从代码提取 API
MARKDOWN
## API 文档生成流程
1. Glob 找到路由/控制器文件
2. Read 读取每个接口定义
3. 提取：路径、方法、参数、返回值、异常
4. 按模块组织输出文档
(2) 文档模板
MARKDOWN
## POST /api/users
### 描述
创建新用户
### 请求参数
| 参数 | 类型 | 必填 | 说明 |
|:-----|:-----|:-----|:-----|
| name | string | 是 | 用户名 |
| email | string | 是 | 邮箱地址 |
### 返回值
| 字段 | 类型 | 说明 |
|:-----|:-----|:-----|
| id | integer | 用户 ID |
| name | string | 用户名 |
### 异常
| 状态码 | 说明 |
|:-------|:-----|
| 400 | 参数校验失败 |
| 409 | 邮箱已存在 |
3. README 生成
(1) 自动检测项目信息
MARKDOWN
## README 信息收集
1. Glob: 检测项目文件（package.json/go.mod/pyproject.toml）
2. Read: 读取配置获取技术栈、依赖、脚本
3. Grep: 搜索入口文件、环境变量、配置项
4. Bash: git log --oneline -10 获取最近变更
(2) README 模板
MARKDOWN
# 项目名
> 一句话描述
## 快速开始
### 环境要求
- Node.js >= 18
- PostgreSQL >= 14
### 安装
```bash
npm install
cp .env.example .env
npm run dev
项目结构
...
开发指南
...
部署
...
---
## 4. 变更日志生成
### (1) 从 Git 提取变更
```bash
# 获取版本间变更
git log v1.1.0..v1.2.0 --oneline
git log v1.1.0..v1.2.0 --format="%s" --no-merges
(2) 分类整理
MARKDOWN
## v1.2.0 (2026-08-15)
### ✨ 新功能
- 添加用户导出功能 (#42)
- 支持暗色模式 (#45)
### 🐛 修复
- 修复登录超时问题 (#38)
- 修复数据排序错误 (#41)
### 💔 破坏性变更
- API /users 返回格式变更，name 字段改为 username
5. 文档 Skill 实战
▶ 示例：全项目文档生成
Alice 创建了一键生成项目文档的 Skill：
YAML
---
name: doc-generator
description: "一键生成项目完整文档"
triggers:
- keyword: "生成文档|gen-docs"
tools:
- Read
- Grep
- Glob
- Write
- Bash
---
Bob 说："文档最大的敌人是过时——Skill 从代码实时提取信息，保证文档和代码永远同步。"
❓ 常见问题
Q 自动生成的文档需要人工审核吗？
A 必须审核。AI 能提取结构信息，但业务含义、使用场景等需要人工补充和确认。
Q 文档放在哪里？
A API 文档放
docs/api/，README 放项目根目录，变更日志放 CHANGELOG.md，架构文档放 docs/architecture/。Q 如何保持文档与代码同步？
A 在 CI 中加入文档检查步骤，代码变更时 Skill 自动更新对应文档，PR 审查时检查文档是否同步。
📖 小节
- 五类文档：API、README、变更日志、代码注释、架构文档
- API 文档：从代码提取接口定义，按模板输出
- README：自动检测项目信息，填充标准模板
- 变更日志：从 Git 提取提交记录，分类整理
- 核心原则：文档与代码同步，AI 提取结构 + 人工补充语义
📝 作业
- 基础题（难度⭐）：创建一个 README 生成 Skill，自动检测项目技术栈并输出标准模板。
- 进阶题（难度⭐⭐）：创建一个 API 文档生成 Skill，从 FastAPI/Express 路由文件提取接口信息。
- 挑战题（难度⭐⭐⭐）：创建一个全项目文档生成 Skill，输出 README + API 文档 + 架构图 + 变更日志四件套。
