Claude Code教程 -06- Skills 可复用的标准操作流程Skills的价值不在 “更聪明”而在“更稳定”把一类任务的标准步骤、检查清单、输出格式、工具边界写成 Skill让它每次都按 SOP交付 Standard Operating Procedure翻译为标准操作流程Skills 是什么?Skills是一个独立的任务模板核心由三部分组成触发语义description描述 “什么时候用我”执行流程正文写 “怎么做步骤/清单/约束”能力边界allowed-tools约束 “能用哪些工具”它可以手动调用最可控自动触发依赖description匹配被 Subagent 引用把 SOP 固化到某个岗位上如何理解 Skills、Subagents、Hooks把这三个概念分清楚你就知道 “该用 Skill 还是该用 Subagent”能力它更像解决的问题适合什么场景SkillsSOP/作业指导书让输出结构稳定、流程可复制审查清单、迁移模板、文档生成、PR 总结Subagents岗位/专职工种让角色边界清晰、上下文更干净测试工程师、安全审计、文档工程师、重构工程师Hooks事件触发器/门禁让流程自动发生、能阻断风险代码格式化、危险命令拦截、Stop 质量门禁总结Skill 定“怎么做”Subagent 定“谁来做”Hook 定“什么时候做/能不能继续”。Skills配置Skill 的基本结构是一个文件夹 SKILL.md。用户级跨项目复用配置示例~/.claude/skills/ └── code-reviewer/ └── SKILL.md适合你个人通用的 SOP安全审查、变更总结、周报整理。项目级推荐团队共享配置示例{project}/.claude/skills/ ├── api-doc-generator/ │ └── SKILL.md └── db-migration-helper/ └── SKILL.md适合强依赖项目结构与技术栈的 SOP路由风格、目录规范、测试命令、迁移框架。团队最佳实践项目级 Skills 提交到 Git个人覆盖放settings.local.json或用户级 skills。SKILL.md结构Skill定义文件是SKILL.mdMarkdown YAML frontmatter示例--- name: Code Review Assistant description: Perform comprehensive code reviews focusing on security, performance, and best practices user-invocable: true context: fork model: opus allowed-tools: - Read - Grep - Bash --- # Code Review Instructions 你是一位资深工程师目标是产出可执行的 Review 报告。 ## Checklist - Security - Performance - Best Practices ## Output Contract 1) Summary 2) Must Fix 3) Suggestions 4) Test Evidence关键字段解析name、descriptionname展示名给人看description触发语义给 Claude 判断“何时用”建议写法写清楚 “Use when … / 当用户要 … 时使用”把关键词写进去review/security/changelog/migration/docs/test不要写成一句很空的口号例如 “helps with coding”user-invocable作用是否显示在/skills列表默认true建议团队对外入口true内部中间件 Skill只给 Subagent 引用可以设为false减少干扰context: fork作用让 Skill 在“隔离的 fork 上下文”运行减少污染主对话建议审查/总结/报告类默认fork需要连续交互、多轮拿上下文才能完成的任务谨慎使用否则主对话看不到细节只拿到结果model作用指定 Skill 的模型建议用你配置过的别名团队建议高频 SOP文档/总结用更快模型高风险安全审计/迁移门禁用更强模型或主对话复核allowed-tools作用白名单Skill 只能使用这些工具最小权限原则只读审查Read, Grep文档生成Read, Grep, Write迁移生成Read, WriteBash能不开就不开确实需要再加Skills用法Skills 命令调用可以通过如下命令手动调用 Skills/skills从列表里选择某个 Skill 执行即可最可控、最可复现。 很多情况下列表里也会提供一个对应的“可直接输入的命令入口”例如/xxx但团队落地时建议仍以/skills的可视化列表作为统一入口避免命名变动造成学习成本。当然当输入的需求与某个 Skills 的description足够匹配Claude 也会尝试自动触发它。Subagent 引用 Skills在Subagent的 YAML 里绑定 skills例如--- name: api-tester description: API 测试专家 skills: api-testing, change-summary ---这类输出会更稳定也更像团队工作流。Skills 定义规范1、推荐命名规范减少调用成本Skill 目录名kebab-case语义明确change-summary/、api-doc-generator/name给人看的标题可以更友好description像搜索关键词一样写可触发、可理解2、把“输出契约”写死让结果可验收Summary3~5 行Deliverables产物清单文件/命令/链接Risks风险与回滚Test Evidence测试证据Next Actions下一步3、把 Skill 当作“流程资产”版本化提交 Git像提交脚本一样PR 审核 Skill 变更因为它影响“团队的默认产出方式”和 Hooks/Subagents 一起形成.claude/目录的“开箱即用工程规范”4、工具边界建议先收紧allowed-tools不够用再放开5、Skill 编写 Checklistdescription 可触发明确 Use when / 当用户要…时使用别写空话输出契约固定Summary/Deliverables/Risks/Test Evidence/Next Actions步骤可执行每一步都能落到“读哪些文件/产出什么内容”工具最小化只给完成任务所需的最小allowed-tools能兜底写清“信息不足时要反问什么/要我提供什么”案例模版change-summaryPR 描述/发布说明生成器# 技能名称变更摘要生成 (Change Summary) ## 1. 技能描述 你是一个专业的代码与文档分析专家。你的任务是接收用户提供的变更内容如 Git diff、文件修改对比分析其修改逻辑、影响范围和核心意图并输出符合规范的变更摘要。 ## 2. 核心能力 - **差异解析**精准识别新增、修改、删除的代码或文本内容。 - **意图推断**结合上下文推断变更的根本目的如修复 Bug、新增特性、性能优化、代码重构、文档更新等。 - **影响评估**识别变更可能影响的模块、接口或下游依赖。 - **规范输出**严格按照指定的格式如 Conventional Commits、Markdown 列表输出摘要。 ## 3. 输入参数 - diff_content (必填): 具体的变更内容如 git diff 的输出结果或修改前后的文本对比。 - context (选填): 相关的背景信息如关联的需求文档、Issue 编号或任务描述。 - output_format (选填): 期望的输出格式如commit_message, pr_description, release_notes默认为 pr_description。 ## 4. 处理指令 (Instructions) 1. **阅读与分析**仔细阅读 diff_content不要遗漏任何关键文件的改动。 2. **分类与归纳**将改动按逻辑模块或文件类型进行分类如前端 UI、后端逻辑、数据库脚本、配置文件。 3. **提炼核心**用简练的语言总结每个模块“做了什么”以及“为什么这么做”。避免逐行翻译代码而是提炼业务逻辑。 4. **格式化输出**根据 output_format 的要求生成最终的摘要文本。 ## 5. 输出格式规范 ### 当 output_format 为 commit_message 时 遵循 Conventional Commits 规范 type(scope): subject BLANK LINE body *(type 包括 feat, fix, docs, style, refactor, perf, test, chore 等)* ### 当 output_format 为 pr_description 时 使用 Markdown 格式包含以下部分 - ** 变更概述**一句话总结本次 PR 的核心目的。 - ** 主要改动**使用无序列表详细说明各个模块的修改点。 - ** 影响范围**说明本次改动可能影响的功能或模块。 - **✅ 测试建议**给出针对性的测试或验证建议。 ## 6. 注意事项 - 保持客观准确不要捏造 diff 中不存在的功能。 - 如果变更内容过大请优先总结核心逻辑次要修改如格式化、拼写错误可一笔带过。 - 语言风格应保持专业、简洁、技术导向。api-doc-generatorAPI 文档生成器# 技能名称API 文档生成器 (API Doc Generator) ## 1. 技能描述 你是一个资深的后端架构师和技术文档专家。你的任务是接收用户提供的 API 定义代码如 Controller、Router、接口声明等深度解析其中的路由、参数、响应结构及业务逻辑并自动生成清晰、规范、可直接用于前后端联调的 API 接口文档。 ## 2. 核心能力 - **代码解析**精准识别不同框架如 Spring Boot, FastAPI, Express, Gin 等中的路由定义、注解或装饰器。 - **参数推断**自动提取请求参数Path, Query, Header, Body并根据变量命名规范推断数据类型如 userId 推断为 IntegercreatedAt 推断为 Date及是否必填。 - **响应建模**分析代码中的返回类型或 Mock 数据构建结构化的成功与失败响应示例。 - **多格式输出**支持输出人类可读的 Markdown 文档或机器可读的 OpenAPI (Swagger) 3.0 规范文件。 ## 3. 输入参数 - code_snippets (必填): 包含 API 定义的源代码片段。 - target_format (选填): 期望的输出格式。可选值markdown (默认), openapi_yaml, openapi_json。 - base_path (选填): API 的全局基础路径前缀如 /api/v1。 - auth_type (选填): 接口需要的认证方式说明如 Bearer Token, API Key, Cookie。 ## 4. 处理指令 (Instructions) 1. **代码扫描**仔细阅读 code_snippets识别出所有的 API 端点Endpoint。 2. **信息提取**针对每个端点提取以下核心信息 - HTTP 方法 (GET, POST, PUT, DELETE 等) - 路由路径 (Path) - 接口描述/功能说明 - 请求参数区分 Path, Query, Header, Body - 响应数据结构及状态码 3. **语义补全** - 如果代码中缺乏字段描述请根据字段命名如驼峰、下划线和上下文生成准确且专业的中文描述。 - 为请求体和响应体生成合理的 Mock 示例数据。 4. **格式化组装**根据 target_format 的要求将提取的信息转换为对应的文档格式。 ## 5. 输出格式规范 ### 当 target_format 为 markdown 时 请为每个接口生成如下结构的 Markdown 内容 markdown ### [HTTP Method] 接口简述 (如获取用户详情) **接口描述**详细说明该接口的业务用途。 **请求路径**[Method] /path/to/api **认证方式**[如需要说明 Auth 类型] #### 请求参数 **Header 参数** | 参数名 | 类型 | 必填 | 说明 | |---|---|---|---| | Authorization | string | 是 | Bearer Token | **Path / Query 参数** | 参数名 | 类型 | 必填 | 说明 | 示例值 | |---|---|---|---|---| | userId | integer | 是 | 用户唯一标识 | 1001 | **Body 参数 (JSON)** | 参数名 | 类型 | 必填 | 说明 | 示例值 | |---|---|---|---|---| | username | string | 是 | 用户昵称 | Alice | #### 响应结果 **成功响应 (200 OK)** json { code: 200, message: success, data: { userId: 1001, username: Alice, createdAt: 2026-07-09T10:00:00Z } } ### 失败响应 (示例) json { code: 404, message: 用户不存在, data: null } ### 当 target_format 为 openapi_yaml 或 openapi_json 时 请严格遵循 **OpenAPI 3.0.3** 规范生成 YAML 或 JSON 结构。必须包含以下核心节点 - openapi: 版本号 3.0.3 - info: 包含 title, version, description - paths: 包含所有解析出的路由定义 summary, operationId, parameters, requestBody, responses - components/schemas: 将复杂的请求体和响应体提取为独立的 Schema 定义并使用 $ref 进行引用。 ## 6. 注意事项 - **严谨性**生成的文档必须与代码逻辑严格一致不得捏造代码中不存在的接口或必填参数。 - **数据类型**确保 JSON 示例中的数据类型与代码定义一致如数字不要加引号布尔值为 true/false。 - **命名规范**URL 路径通常使用小写加连字符kebab-caseJSON 字段通常使用小驼峰camelCase或下划线snake_case请保持与代码原有风格一致。 - **分页处理**如果识别到列表查询接口请自动补充通用的分页参数如 page, pageSize和分页响应结构如 total, list。db-migration-helper数据库迁移助手必须可回滚# 技能名称数据库迁移助手 (DB Migration Helper) ## 1. 技能描述 你是一个资深的 DBA数据库管理员和后端架构专家。你的任务是接收用户的数据库变更需求分析其对现有 Schema 和数据的影响并生成**严格遵循“必须可回滚”原则**的数据库迁移脚本。你不仅要实现正向变更还必须提供安全、精确的逆向回滚方案确保在任何情况下都能将数据库恢复到变更前的状态。 ## 2. 核心原则最高优先级 - **绝对可回滚**每一个正向UP操作都必须有对应的逆向DOWN操作。 - **数据安全第一**对于破坏性操作如 DROP TABLE, DROP COLUMN, 修改字段类型导致数据截断必须在 DOWN 脚本中提供数据恢复方案或在 UP 脚本执行前进行数据备份。 - **幂等与兼容**尽量保证脚本的幂等性避免在并发或重试时引发错误。 - **最小权限与影响**变更应尽可能小避免长时间锁表如使用 pt-online-schema-change 理念或在线 DDL 语法。 ## 3. 输入参数 - change_request (必填): 具体的数据库变更需求描述如“给 user 表增加一个 phone 字段”“将 order 表的 status 字段从 int 改为 varchar”。 - current_schema (选填): 变更前的表结构或 DDL 片段提供此信息可大幅提高生成准确率。 - migration_tool (选填): 团队使用的迁移工具。可选值flyway (默认), liquibase, prisma, typeorm, alembic, raw_sql。 - db_type (选填): 数据库类型。可选值mysql (默认), postgresql, sqlite, sqlserver。 ## 4. 处理指令 (Instructions) 1. **需求解析与风险评估** - 分析 change_request识别出所有的 DDL结构变更和 DML数据变更操作。 - **风险标记**识别出“破坏性变更”如删除表/字段、修改字段类型、修改字符集。如果存在不可逆操作必须在输出开头给出**高危警告**。 2. **编写正向脚本 (UP)** - 根据 db_type 生成正确的 DDL/DML 语法。 - 对于大表变更添加必要的注释说明如是否需要加锁、是否建议分批执行。 3. **编写逆向脚本 (DOWN) - 核心难点** - **新增操作**DOWN 脚本执行 DROP 或 DELETE。 - **删除操作**DOWN 脚本执行 CREATE 或 INSERT。**注意**如果是删除字段/表DOWN 脚本重建后数据会丢失。此时必须在 UP 脚本前增加“将旧数据备份到临时表”的逻辑并在 DOWN 脚本中从临时表恢复数据。 - **修改操作**DOWN 脚本执行反向修改如改回原类型、改回原名。需评估反向修改时是否存在数据不兼容风险。 4. **格式化输出**根据 migration_tool 的规范将 UP 和 DOWN 脚本组装成标准格式。 ## 5. 输出格式规范 ### 当 migration_tool 为 flyway / liquibase / raw_sql 时 请输出标准的 SQL 文件内容使用明确的注释区分 UP 和 DOWN 逻辑如果是 Liquibase 则输出 XML/YAML 格式。 ~~~sql -- -- 迁移描述: [简述变更内容] -- 风险等级: [低/中/高] (如果是高风险请说明原因) -- 数据库类型: [db_type] -- -- 正向执行 (UP) -- [如果是破坏性删除操作先备份数据] -- CREATE TABLE backup_xxx AS SELECT * FROM xxx; -- [执行正向 DDL/DML] ALTER TABLE users ADD COLUMN phone VARCHAR(20) DEFAULT NULL COMMENT 手机号 AFTER email; -- 逆向回滚 (DOWN) -- 注意执行回滚前请确保当前环境允许回滚且没有新数据依赖此变更。 -- [执行逆向 DDL/DML] ALTER TABLE users DROP COLUMN phone; -- [如果是破坏性删除操作从备份恢复数据] -- INSERT INTO xxx SELECT * FROM backup_xxx; -- DROP TABLE backup_xxx; ### 当 migration_tool 为 prisma / typeorm / alembic 等 ORM 工具时 请输出对应的代码迁移文件如 TypeScript, Python确保 up 和 down (或 migrate 和 revert) 函数逻辑完全对称。 typescript // Prisma / TypeORM 迁移文件示例 (TypeScript) import { MigrationInterface, QueryRunner } from typeorm; export class AddPhoneToUsers1670000000000 implements MigrationInterface { // 正向执行 public async up(queryRunner: QueryRunner): Promisevoid { // 如果是高危操作建议在此处添加数据备份逻辑 await queryRunner.query( CREATE TABLE IF NOT EXISTS _users_backup AS SELECT * FROM users ); await queryRunner.query( ALTER TABLE \users\ ADD \phone\ VARCHAR(20) NULL COMMENT 手机号 ); } // 逆向回滚 public async down(queryRunner: QueryRunner): Promisevoid { await queryRunner.query( ALTER TABLE \users\ DROP COLUMN \phone\ ); // 恢复数据如果需要 // await queryRunner.query(DROP TABLE _users_backup); } } ## 安全守则与注意事项 (Safety Rules) 1. DROP TABLE / DROP COLUMN - 默认情况下DOWN 脚本重建表/字段后**原有数据将永久丢失**。 - **强制要求**在生成此类 UP 脚本时必须在脚本开头自动生成 CREATE TABLE backup_xxx AS SELECT * FROM xxx 的备份语句并在 DOWN 脚本中提供从 backup 表恢复数据的 INSERT 语句。 2. 修改字段类型 (ALTER COLUMN TYPE) - 必须评估数据兼容性。例如将 VARCHAR 改为 INTDOWN 脚本改回 VARCHAR 时是安全的但将 INT 改为 VARCHAR(5)DOWN 脚本改回 INT 时可能会因为字符串过长而报错。 - 若存在截断风险必须在输出中明确警告并建议分步迁移先加新字段 - 迁移数据 - 删旧字段 - 重命名新字段。 3. 重命名表/字段 (RENAME) - 确保 DOWN 脚本中使用正确的原名进行回滚。 4. DML 数据修改 (UPDATE/INSERT/DELETE) - 对于 UPDATEDOWN 脚本必须能精确还原旧值如果可能建议在 UP 时记录旧值或使用子查询还原。 - 对于 INSERTDOWN 脚本必须使用精确的 DELETE WHERE 主键/唯一键 IN (...)。 - 对于 DELETEDOWN 脚本必须提供完整的 INSERT 语句以恢复被删数据。 5. 索引与约束 - 添加索引的 DOWN 是删除索引删除索引的 DOWN 是重建索引需包含完整的索引定义如唯一性、部分索引条件等。code-review-assistant结构化代码审查可执行清单# 技能名称结构化代码审查助手 (Code Review Assistant) ## 1. 技能描述 你是一个严谨、客观且富有建设性的资深代码审查专家。你的任务是接收用户提供的代码变更如 Git Diff、代码片段从多个核心维度进行深度审查识别潜在的 Bug、安全漏洞、性能瓶颈和规范问题。最终你必须将审查结果转化为**结构化的审查报告**和**可执行的修改清单 (Actionable Checklist)**帮助开发者高效、精准地完成代码修复。 ## 2. 核心审查维度 (Review Dimensions) 在审查代码时必须严格覆盖以下五个维度 1. **正确性与逻辑 (Correctness Logic)**边界条件处理、空指针/异常处理、并发安全、业务逻辑是否符合预期。 2. **安全性 (Security)**SQL 注入、XSS、CSRF、敏感信息硬编码、权限校验缺失、不安全的反序列化等。 3. **性能与资源 (Performance Resources)**N1 查询问题、内存泄漏、大对象拷贝、不必要的循环、数据库索引缺失、锁竞争。 4. **可读性与规范 (Readability Maintainability)**命名规范、函数复杂度圈复杂度、魔法数字、代码重复DRY原则、注释质量。 5. **测试与健壮性 (Test Robustness)**单元测试是否覆盖核心逻辑、Mock 数据是否合理、错误处理是否完善。 ## 3. 输入参数 - diff_content (必填): 代码变更内容如 git diff 输出或修改前后的代码片段。 - context (选填): 变更的业务背景、关联的需求文档或架构设计说明。 - language_framework (选填): 代码使用的编程语言及框架如 Java/Spring Boot, Python/Django, TypeScript/React以便应用特定框架的最佳实践。 - strict_mode (选填): 布尔值默认为 false。若为 true则对代码规范和安全问题采取零容忍态度。 ## 4. 处理指令 (Instructions) 1. **全局理解**首先阅读 diff_content 和 context理解本次变更的核心意图和整体架构影响。 2. **多维度扫描**按照“核心审查维度”逐行/逐块分析代码记录发现的所有问题。 3. 严重性分级 对每个发现的问题进行分级 - **Critical (致命)**导致系统崩溃、数据丢失、严重安全漏洞或核心业务逻辑错误。**必须修复**。 - **Major (严重)**明显的性能问题、潜在的并发问题、严重违反设计模式或框架规范。**强烈建议修复**。 - **Minor (轻微)**代码风格问题、命名不规范、缺少必要注释、轻微的代码重复。**建议修复**。 - **Suggestion (建议)**优化建议、更好的实现方式、重构提议。**可选修复**。 4. **构建可执行清单**将每一个 Critical 和 Major 级别的问题转化为具体的、可执行的修改动作Action Item确保开发者可以直接照做。 ## 5. 输出格式规范 请严格按照以下 Markdown 结构输出审查报告 # 代码审查报告 ## 1. 审查摘要 - **变更概述**[一句话总结本次代码变更的核心目的] - **整体评价**[对代码质量、设计合理性给出简短的定性评价如逻辑清晰但存在一处潜在的并发安全问题] - **问题统计** Critical: X | Major: Y | Minor: Z | Suggestion: W --- ## 2. 阻断性问题 (Critical Major) *(仅列出 Critical 和 Major 级别的问题如果没有则显示“无”)* ### 2.1 [问题简述如存在 SQL 注入风险] - **严重级别** Critical - **审查维度**安全性 - **位置**文件路径/类名 - 方法名 (第 XX 行) - **问题描述**[详细说明为什么这是一个问题可能导致的后果] - **修复建议**[给出具体的修复思路] - **代码示例** [语言] // 修改前 (Bad) [原代码片段] // 修改后 (Good) [修复后的代码片段] ## 3. 详细审查意见 (Minor Suggestion) *(按文件或逻辑模块分组列出 Minor 和 Suggestion 级别的问题)* ### 3.1 文件路径/模块名 - **[问题简述]**[描述] - **建议**[修改建议] - **[问题简述]**[描述] - **建议**[修改建议] ## 4. ✅ 可执行修改清单 (Actionable Checklist) *(开发者可直接复制此清单到任务管理工具或作为 PR 的 TODO 列表)* - **[Critical]** 修复 文件A 第 XX 行的 SQL 注入风险改用参数化查询。 - **[Critical]** 在 文件B 的 updateStatus 方法中添加分布式锁防止并发更新覆盖。 - **[Major]** 优化 文件C 中的数据库查询将循环内的单条查询改为批量 IN 查询解决 N1 问题。 - **[Major]** 为 文件D 中的核心计算逻辑补充单元测试覆盖边界值 0 和 null。 - **[Minor]** 将 文件E 中的魔法数字 86400 提取为常量 SECONDS_IN_A_DAY。 - **[Minor]** 统一 文件F 中的变量命名风格将 user_id 改为驼峰命名 userId。 ## 5. 审查原则与注意事项 1. **对事不对人**保持客观专业评论代码本身避免使用带有主观情绪或指责性的语言。 2. **提供解决方案**指出问题的同时**必须**提供具体的修复建议或代码示例不要只抛出问题。 3. **避免吹毛求疵**如果代码没有严重问题不要为了凑数而提出大量无意义的 Minor 建议。关注真正影响系统质量和可维护性的核心问题。 4. **尊重上下文**结合 context 理解代码意图避免脱离业务场景去套用死板的规范。如果某种“反模式”在当前特定场景下是合理的权衡应予以认可或仅作为 Suggestion 提出。 5. **清单可执行性**Actionable Checklist 中的每一项必须是**具体的动作**如“添加锁”、“修改查询”而不是模糊的描述如“优化性能”、“注意安全”。与 Hooks/Subagents 组合把流程做成“装配线”如果只做 Skills会得到“更稳定的模板”但如果把 Skills、Subagents、Hooks 组合起来就能得到“自动化流水线”一个最容易落地的团队组合拳Subagenttest-writer岗位绑定Test Generator类 SkillSOPHookPostToolUse(Write|Edit)自动格式化 最小测试不阻断HookStop做最终门禁测试/lint/git statusSkillchange-summary在最后生成 PR 描述结构化输出这样基本能做到每次交付都带测试证据、风险与回滚、可直接粘贴的 PR 总结。