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

title: Skill 技能系统完全指南六实战 Skill文档生成——API 文档、技术手册与 Changelogdate: 2026-07-10category: AI 开发工具tags: [Claude Code, Skill, 文档生成, API 文档, Changelog, 技术手册]Skill 技能系统完全指南六实战 Skill——文档生成代码可以自动生成文档却总是最后时刻才赶出来。本篇教你用 Skill 自动化 API 文档、技术手册、Changelog 的生成让文档不再拖后腿。前言软件开发中文档的重要性不言而喻API 文档——前后端联调的契约技术手册——部署运维的指南Changelog——版本更新的记录但现实中文档往往是最后一个被写的东西而且很快过时。用 Skill 来解决这个问题让文档生成成为开发流程的一部分代码改了文档自动更新。一、API 文档生成 Skill1.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 类读取类级别的RequestMapping作为基础路径读取每个方法上的GetMapping/PostMapping等提取方法参数上的RequestParam/PathVariable/RequestBody读取返回类型提取字段说明步骤 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: adminexample.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输出docs/api/目录下按模块生成的 Markdown 文档docs/openapi.yaml开放 API 规范文件更新摘要本次生成了多少个接口涉及几个模块## 二、技术手册生成 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.activeprod前端部署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-server3 | ## 监控告警 - 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_modulesrm -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 --prettyformat:%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项目结构…环境变量…部署…五、文档同步 Skill5.1 设计思路代码改了文档没跟——这是最常见的文档问题。这个 Skill 检测代码变更标记需要同步更新的文档。--- name: doc-sync description: 检测代码变更与文档的差异标记需要同步更新的文档 trigger: 文档同步, doc sync, 文档更新, 文档检查 --- # 文档同步检查 Skill ## 角色定义 你是一个文档一致性检查专家。 ## 执行流程 ### 步骤 1: 获取变更的文件列表 bash git diff --name-only origin/main...HEAD步骤 2: 判断哪些文档需要同步更新变更的文件需要同步的文档Controller 新增/修改API 文档Entity 字段变更数据库文档、API 文档新增页面组件用户操作手册配置文件变更部署手册新增/修改环境变量README 环境变量说明步骤 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. ~~实战 SkillDevOps 部署——编写 Docker/Nginx/CI-CD 相关的部署 Skill~~ 5. ~~实战 Skill代码质量——编写 Code Review / Lint / 测试覆盖率 Skill~~ 6. ~~实战 Skill文档生成——编写 API 文档 / 技术手册 / Changelog 生成 Skill~~ ← 本篇 7. Skill 分享与复用——团队共享 Skill 库、开源 Skill 生态、版本管理待写 8. Skill 进阶技巧——条件触发、多语言支持、与 Agent/Workflow 的配合待写