Skill 技能系统完全指南（六）：实战 Skill——文档生成

title: Skill 技能系统完全指南（六）实战 Skill：文档生成——API 文档、技术手册与 Changelog
date: 2026-07-10
category: AI 开发工具
tags: [Claude Code, Skill, 文档生成, API 文档, Changelog, 技术手册]

Skill 技能系统完全指南（六）：实战 Skill——文档生成

代码可以自动生成，文档却总是最后时刻才赶出来。本篇教你用 Skill 自动化 API 文档、技术手册、Changelog 的生成，让文档不再拖后腿。

前言

软件开发中，文档的重要性不言而喻：

• API 文档——前后端联调的契约
• 技术手册——部署运维的指南
• Changelog——版本更新的记录

但现实中，文档往往是最后一个被写的东西，而且很快过时。用 Skill 来解决这个问题：让文档生成成为开发流程的一部分，代码改了，文档自动更新。

一、API 文档生成 Skill

1.1 设计思路

API 文档最常见的格式是 Swagger/OpenAPI。但这个 Skill 的目标更进一步——不只是生成注解，而是生成人类可读的文档。

--- name: api-doc-gen description: 从代码注解或 Controller 类自动生成 API 文档（Markdown / OpenAPI / 语雀） trigger: API 文档, api doc, swagger, openapi, 接口文档 tools: [Bash, Grep, Read, Write] --- # API 文档生成 Skill ## 角色定义 你是一个 API 文档专家，擅长从代码自动生成清晰、完整的接口文档。 ## 支持的数据源 | 来源 | 说明 | 优先级 | |------|------|--------| | Swagger 注解 | @ApiOperation, @ApiParam 等 | 高 | | Controller 方法签名 | 方法名、参数类型、返回值 | 中 | | OpenAPI YAML | 已有的 openapi.yaml 文件 | 高 | | 数据库表结构 | 实体类上的 @TableName 和 @TableField | 低 | ## 生成流程 ### 步骤 1: 扫描 Controller ```bash # 查找所有 Controller 类 grep -rl "@RestController\|@Controller" src/main/java/

步骤 2: 提取接口信息

对每个 Controller 类：

1. 读取类级别的@RequestMapping作为基础路径
2. 读取每个方法上的@GetMapping/@PostMapping等
3. 提取方法参数上的@RequestParam/@PathVariable/@RequestBody
4. 读取返回类型，提取字段说明

步骤 3: 生成 Markdown 文档

按模块分组，生成如下格式的文档：

## 用户管理 ### 获取用户列表 - **URL**: `GET /api/users` - **描述**: 分页获取用户列表，支持按用户名、状态筛选 - **请求参数**: | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | pageNum | Integer | 是 | 页码，从 1 开始 | | pageSize | Integer | 是 | 每页条数，最大 100 | | username | String | 否 | 用户名模糊搜索 | | status | String | 否 | 状态：active / inactive | - **响应示例**: ```json { "code": 200, "message": "success", "data": { "list": [ { "id": 1, "username": "admin", "email": "admin@example.com", "role": "admin", "status": "active" } ], "total": 42 } }

• 错误码:
  | 码 | 说明 |
  |----|------|
  | 401 | 未登录 |
  | 403 | 无权限 |
  | 500 | 服务器内部错误

### 步骤 4: 生成 OpenAPI 规范 同时生成 `docs/openapi.yaml`： ```yaml openapi: 3.0.3 info: title: 金坛管理系统 API version: 1.0.0 description: 基于 Spring Boot + Dubbo 的金坛采气管理系统接口文档 paths: /api/users: get: summary: 获取用户列表 parameters: - name: pageNum in: query required: true schema: type: integer default: 1 - name: pageSize in: query required: true schema: type: integer default: 20 responses: '200': description: 成功 content: application/json: schema: $ref: '#/components/schemas/PageResultUser'

输出

1. docs/api/目录下按模块生成的 Markdown 文档
2. docs/openapi.yaml开放 API 规范文件
3. 更新摘要：本次生成了多少个接口，涉及几个模块

## 二、技术手册生成 Skill ### 2.1 设计思路 技术手册包括：部署手册、运维手册、故障排查手册、用户操作手册。这个 Skill 从代码和项目配置中提取信息，自动生成手册框架。 ```markdown --- name: tech-doc-gen description: 生成技术文档：部署手册、运维手册、用户操作手册、故障排查指南 trigger: 技术文档, 部署手册, 运维手册, 操作手册, 故障排查 --- # 技术文档生成 Skill ## 角色定义 你是一个技术文档专家，擅长将项目信息转化为清晰的技术文档。 ## 支持的文档类型 ### 1. 部署手册 从项目配置文件提取信息，生成部署指南： ```markdown # 部署手册 ## 环境要求 | 组件 | 版本 | 说明 | |------|------|------| | Node.js | >= 18.0 | 前端构建 | | JDK | 1.8 | 后端运行 | | Maven | >= 3.6 | 后端构建 | | MySQL | >= 5.7 | 数据库 | | Redis | >= 6.0 | 缓存 | ## 数据库初始化 ```sql -- 执行顺序： -- 1. schema.sql（建表） -- 2. data.sql（初始数据）

后端部署

# 1. 编译打包cdasset-server mvn clean package-DskipTests# 2. 配置 application.yml# 修改数据库连接、Redis 地址等# 3. 启动服务java-jartarget/asset-server.jar--spring.profiles.active=prod

前端部署

cdfrontendpnpmbuild# 将 dist/ 目录下的文件复制到 Nginx 根目录cp-rdist/* /usr/share/nginx/html/

Nginx 配置

# 见 nginx.conf 文件

验证部署

# 检查后端curlhttp://localhost:8080/actuator/health# 检查前端curlhttp://localhost:5173

### 2. 运维手册 从 `docker-compose.yml`、`Kubernetes manifest`、监控配置中提取信息： ```markdown # 运维手册 ## 服务拓扑

用户 → Nginx(5173) → Vue 静态资源
→ Nginx(80) → 反向代理 → Spring Boot(8080)
→ Spring Boot → MySQL(13306)
→ Spring Boot → Redis(6379)

## 日常操作 | 操作 | 命令 | |------|------| | 查看服务状态 | `docker-compose ps` | | 重启服务 | `docker-compose restart` | | 查看日志 | `docker-compose logs -f asset-server` | | 扩容 | `docker-compose up -d --scale asset-server=3` | ## 监控告警 - CPU > 80% 持续 5 分钟 → 告警 - 内存 > 4GB → 告警 - 数据库连接池使用率 > 80% → 告警

3. 故障排查手册

从日志模式、常见错误码中提取：

# 故障排查手册 ## 常见问题 ### Q1: 后端启动失败，报错 "Connection refused: 192.168.31.196:13306" **原因**：数据库服务未启动或连接地址错误 **解决**： 1. 检查 MySQL 服务：`systemctl status mysql` 2. 检查 application.yml 中的数据库地址 3. 检查防火墙规则 ### Q2: 前端构建报错 "Cannot find module xxx" **原因**：依赖未安装或版本不匹配 **解决**： 1. 删除 node_modules：`rm -rf node_modules` 2. 清除 pnpm 缓存：`pnpm store prune` 3. 重新安装：`pnpm install` ### Q3: API 返回 401 未登录 **原因**：Token 过期或未携带 **解决**： 1. 检查 localStorage 中的 token 2. 检查请求拦截器是否正确附加 Authorization header 3. 联系后端重置 Token

## 三、Changelog 生成 Skill ### 3.1 设计思路 每次版本发布都要写 Changelog，但这个 Skill 可以从 Git 提交记录中自动生成。 ```markdown --- name: changelog-gen description: 从 Git 提交记录自动生成 Changelog（按feat/fix/refactor分类） trigger: Changelog, 更新日志, 版本记录, release notes --- # Changelog 生成 Skill ## 角色定义 你是一个版本发布管理专家，擅长从 Git 提交记录生成清晰的版本更新日志。 ## 生成规则 遵循 [Keep a Changelog](https://keepachangelog.com/) 规范： | 前缀 | 分类 | Emoji | 说明 | |------|------|-------|------| | feat | 新功能 | ✨ | 新增功能 | | fix | 修复 | 🐛 | Bug 修复 | | perf | 性能优化 | ⚡ | 性能改进 | | refactor | 重构 | ♻️ | 代码重构 | | docs | 文档 | 📝 | 文档变更 | | style | 样式 | 💄 | 代码格式 | | test | 测试 | 🧪 | 测试相关 | | chore | 构建 | 🔧 | 构建/工具变更 | ## 执行流程 ### 步骤 1: 获取提交记录 ```bash # 获取两个版本之间的提交 git log v1.0.0..HEAD --pretty=format:"%h %s (%an)" --no-merges

步骤 2: 分类整理

## [1.1.0] - 2026-07-10 ### ✨ 新功能 - **用户管理** (a1b2c3d) — 添加用户批量导入功能 - **报表模块** (e5f6g7h) — 新增日报、周报、月报三个页面 ### 🐛 修复 - **登录超时** (i8j9k0l) — 修复 Token 过期后无法自动刷新 - **查询为空** (m1n2o3p) — 修复日期范围为空时查询报错 ### ⚡ 性能优化 - **列表加载** (q4r5s6t) — 用户列表分页查询响应时间从 2s 降至 300ms ### ♻️ 重构 - **HTTP 封装** (u7v8w9x) — 统一错误处理逻辑，抽取到 http.ts ### 📝 文档 - **部署手册** (y0z1a2b) — 更新部署文档，补充 Nginx 配置说明 ### 🔧 构建 - **依赖升级** (c3d4e5f) — Vue 3.4 → 3.5, Element Plus 2.13 → 2.14

步骤 3: 输出

生成CHANGELOG.md文件，并输出本次版本的摘要统计。

可选参数

用户可以指定：

• --since v1.0.0：从指定版本开始
• --until v1.1.0：到指定版本结束
• --scope 用户管理：只生成指定模块的变更
• --format markdown/github：输出格式

## 四、README 生成 Skill ### 4.1 设计思路 README 是项目的门面，但这个 Skill 可以从项目结构中自动生成基础版本。 ```markdown --- name: readme-gen description: 从项目结构和配置文件自动生成 README.md trigger: README, 项目说明, 项目介绍, readme --- # README 生成 Skill ## 角色定义 你是一个项目文档专家，擅长编写清晰的项目 README。 ## 生成逻辑 从以下源提取信息： | 源 | 提取内容 | |----|---------| | package.json | 项目名称、版本、描述、脚本命令 | | pom.xml | 后端技术栈、依赖版本 | | CLAUDE.md | 项目概述、目录结构 | | .env | 环境变量说明 | | docker-compose.yml | 部署方式说明 | ## 输出格式 ```markdown # 金坛管理系统 > 基于 Spring Boot + Dubbo 的采气/注气业务数据管理和方案编制系统 ## 技术栈 ### 前端 - Vue 3 + TypeScript + Vite - Element Plus - Pinia + Vue Router - Axios + ECharts ### 后端 - Spring Boot 2.x - Apache Dubbo 2.7.8 - MyBatis-Plus + Druid - Nacos 配置中心 ## 快速开始 ```bash # 前端 cd frontend pnpm install pnpm dev # 后端 cd asset-server mvn spring-boot:run

项目结构

…

环境变量

…

部署

…

五、文档同步 Skill

5.1 设计思路

代码改了，文档没跟——这是最常见的文档问题。这个 Skill 检测代码变更，标记需要同步更新的文档。

--- name: doc-sync description: 检测代码变更与文档的差异，标记需要同步更新的文档 trigger: 文档同步, doc sync, 文档更新, 文档检查 --- # 文档同步检查 Skill ## 角色定义 你是一个文档一致性检查专家。 ## 执行流程 ### 步骤 1: 获取变更的文件列表 ```bash git diff --name-only origin/main...HEAD

步骤 2: 判断哪些文档需要同步更新

步骤 3: 输出需要同步的文档清单

📋 文档同步检查报告 ━━━━━━━━━━━━━━━━━━━━━ 检测到以下代码变更需要同步更新文档： | 代码变更 | 受影响文档 | 紧急程度 | |---------|-----------|---------| | UserCtrl新增批量导入 | docs/api/用户管理.md | 🔴 高 | | GasProduction加daily_target字段 | docs/api/生产数据.md | 🔴 高 | | 新增报表页面 | docs/manual/用户操作手册.md | 🟡 中 | | 新增REDIS_HOST环境变量 | README.md | 🟡 中 | 建议优先更新 🔴 标记的文档。

## 六、这一章的核心心得 1. **API 文档应该是自动的**——从 Controller 注解生成，保证与代码同步 2. **技术手册分层**——部署、运维、故障排查各成体系 3. **Changelog 从 Git 提交生成**——遵循 Keep a Changelog 规范，按 feat/fix/refactor 分类 4. **README 可以从项目结构自动生成**——至少有个基础版本，再手动补充 5. **文档同步检查是防遗忘机制**——代码改了，自动标记哪些文档需要同步 6. **文档也是产品**——好的文档让使用者少问 100 个问题 ## 七、下一步 我们已经写了 4 个实战 Skill——DevOps 部署、代码质量、文档生成。这些 Skill 现在都存在于单个项目中。但如果一个团队有 10 个项目，每个项目都要重新写一遍同样的 Skill 吗？ 当然不。下一篇我们将学习 **Skill 的分享与复用**——如何构建团队共享的 Skill 库，甚至贡献给开源社区。 --- *系列目录：* 1. ~~初识 Skill 系统——什么是 Skill？为什么需要 Skill？~~ 2. ~~自定义 Skill 开发——从 0 到 1 编写自己的 Skill~~ 3. ~~Skill 编排与组合——多个 Skill 串联工作，打造自动化流程~~ 4. ~~实战 Skill：DevOps 部署——编写 Docker/Nginx/CI-CD 相关的部署 Skill~~ 5. ~~实战 Skill：代码质量——编写 Code Review / Lint / 测试覆盖率 Skill~~ 6. ~~实战 Skill：文档生成——编写 API 文档 / 技术手册 / Changelog 生成 Skill~~ ← 本篇 7. Skill 分享与复用——团队共享 Skill 库、开源 Skill 生态、版本管理（待写） 8. Skill 进阶技巧——条件触发、多语言支持、与 Agent/Workflow 的配合（待写）