# Claude Code Skills开发实战：从零构建并发布自定义Skill **适用人群**：已熟悉Claude Code基本操作的开发者，希望将重复性工作流封装为可复用的Skill **学习目标**：掌握SKILL.md完整规范，独立设计、开发、测试和发布一个Claude Code Skill --- ## 一、Skills是什么：重新理解这个系统 Skills不是简单的提示词模板。它是一套完整的**指令封装与分发标准**——将领域知识、工作流步骤、上下文模板和辅助资源打包成一个文件夹，让Claude Code在恰当的时机自动或手动加载。  > *图表 1* 一个Skill由三部分组成： | 组件 | 作用 | 是否必须 | |------|------|---------| | SKILL.md | 核心指令文件（YAML frontmatter + Markdown正文） | 必须 | | 辅助资源文件 | 模板、参考文档、脚本等 | 可选 | | 目录结构 | 提供命名空间和文件组织 | 必须 | --- ## 二、前置条件 在开始之前，确保你已具备： 1. **Claude Code CLI** 已安装并可用（`claude --version` ≥ 1.0） 2. 一个可用的项目目录（用于测试Skill） 3. 基本了解Markdown和YAML语法 4. 理解Claude Code的`CLAUDE.md`机制（项目级指令文件） **目录约定**： ```bash # 个人级Skill（全局可用） ~/.claude/skills/my-skill/SKILL.md # 项目级Skill（仅当前项目可用） your-project/.claude/skills/my-skill/SKILL.md ``` --- ## 三、SKILL.md完整规范深度解析 ### 3.1 文件结构 每个SKILL.md由两个区域组成，用`---`分隔： ```markdown --- [YAML Frontmatter - 元数据配置区] --- [Markdown Body - 指令内容区] ``` ### 3.2 YAML Frontmatter字段全解 Frontmatter是Skill的"身份证"，决定了Claude Code如何发现、匹配和呈现你的Skill。 ```yaml --- name: my-skill-name # 必填：Skill唯一标识，用kebab-case description: 一句话描述Skill功能 # 必填：用于Skill列表展示和关键词匹配 triggers: # 可选：触发条件，控制自动激活 - 关键词1 - 关键词2 user_invocable: true # 可选：是否支持 /skillname 手动调用，默认true disabled: false # 可选：是否禁用，默认false --- ``` **各字段详解**： **`name`（必填）** - 使用kebab-case命名（如`code-review-helper`） - 在同一目录下必须唯一 - 也是斜杠命令的名称（`/code-review-helper`） **`description`（必填）** - 限一句话，清晰描述Skill的功能 - **这是自动激活的关键**——Claude Code通过description中的关键词匹配来决定是否激活Skill - 写法建议：动词开头 + 场景 + 输出，例如"审查Git暂存代码中的安全漏洞和性能问题，输出结构化报告" **`triggers`（可选）** - 显式声明触发关键词列表 - Claude Code会结合description和triggers进行双重匹配 - 越具体越好，避免模糊词汇 **`user_invocable`（可选，默认true）** - 设为`true`时，用户可以通过`/skillname`手动调用 - 设为`false`时，Skill只能被自动激活，不显示在斜杠命令列表中 - 适用于后台辅助型Skill（如自动代码风格检查） **`disabled`（可选，默认false）** - 临时禁用Skill而不删除文件 - 调试时很有用 ### 3.3 Markdown Body指令编写原则 正文区域是Skill的核心——Claude Code会将其作为指令注入到上下文中。编写时遵循以下原则： 1. **结构化而非散文式**：使用标题、列表、表格，避免长段落 2. **检查清单优于描述**：用明确的步骤列表替代模糊的"请考虑..." 3. **提供具体示例**：每条规则附带输入/输出样例 4. **限定范围**：明确说明Skill的边界——什么做、什么不做 5. **控制长度**：正文控制在2000-4000 tokens以内，过长会稀释注意力 **推荐的正文结构模板**： ```markdown # Skill名称 ## 触发条件 明确列出什么情况下应该使用此Skill。 ## 输入规范 描述Skill期望接收什么输入（文件路径、文本内容、参数等）。 ## 执行步骤 1. 第一步：具体操作 2. 第二步：具体操作 3. ... ## 输出格式 描述Skill应该生成什么样的输出。 ## 约束与边界 - 本Skill不处理XXX - 当遇到XXX时，提示用户而非自行决定 ## 示例 提供至少一个完整的输入→输出示例。 ``` --- ## 四、从零构建实战Skill：API文档生成器 接下来，我们将构建一个完整的Skill——`api-doc-generator`，它能分析代码中的API路由，自动生成RESTful API文档。 ### 4.1 创建Skill目录 ```bash # 在你的测试项目中创建Skill目录 mkdir -p .claude/skills/api-doc-generator cd .claude/skills/api-doc-generator ``` ### 4.2 编写SKILL.md ```markdown --- name: api-doc-generator description: 分析项目中的API路由定义，生成标准RESTful API文档。当用户提到"生成API文档"、"API文档"、"接口文档"、"写API文档"时触发。 triggers: - API文档 - 接口文档 - 生成文档 - api documentation - openapi - swagger user_invocable: true --- # API文档生成器 ## 何时使用 当用户要求为项目生成API文档、接口文档，或提到OpenAPI/Swagger规范时，激活此Skill。 ## 输入 - 项目路径（默认为当前工作目录） - 目标框架（自动检测或由用户指定） - 输出格式：Markdown（默认）或OpenAPI 3.0 YAML ## 执行步骤 ### 第一步：识别框架 读取项目的package.json、requirements.txt、go.mod或其他依赖文件，判断后端框架： | 框架 | 特征文件 | 路由定义模式 | |------|---------|------------| | Express.js | package.json含"express" | app.get/post/put/delete | | FastAPI | requirements.txt含"fastapi" | @app.get/post装饰器 | | Spring Boot | pom.xml/build.gradle | @GetMapping/@PostMapping | | Django REST | settings.py含"rest_framework" | urlpatterns列表 | | Gin | go.mod含"gin-gonic" | r.GET/POST/PUT/DELETE | | Flask | requirements.txt含"flask" | @app.route装饰器 | ### 第二步：扫描路由文件 使用Grep工具搜索路由定义模式，定位所有包含API端点的文件。 ### 第三步：提取端点信息 对每个API端点，提取以下信息： - HTTP方法（GET/POST/PUT/DELETE/PATCH） - 路径（如`/api/v1/users/:id`） - 请求参数（query、path、body） - 请求体Schema（如果存在） - 响应格式 - 认证要求（如果可推断） - 描述/注释 ### 第四步：生成文档 按以下格式输出Markdown文档： ```markdown # API文档 ## 概述 - 基础URL：`（推断或使用占位符）` - 认证方式：`（Bearer Token / API Key / None）` - 版本：`（从package.json或配置推断）` ## 端点列表 ### [方法] 路径 **描述**：端点功能说明 **请求参数**： | 参数名 | 位置 | 类型 | 必填 | 描述 | |--------|------|------|------|------| **请求体**： （JSON Schema或示例） **响应**： | 状态码 | 描述 | Schema | |--------|------|--------| **示例**： （curl命令示例） ``` ### 第五步：质量检查 - 确保每个端点都有描述 - 检查是否有遗漏的路由文件 - 验证HTTP方法与路径的一致性 ## 输出 在项目根目录创建 `docs/api.md` 文件。 ## 约束 - 不修改任何源代码文件 - 无法确定的信息用 `[待确认]` 标记 - 如果项目不是Web后端项目，告知用户并停止 - 生成文档后，提供端点统计摘要 ## 示例 **输入**：用户在一个Express.js项目中输入 `/api-doc-generator` **输出**：扫描routes/目录，提取所有路由定义，生成包含完整端点信息的`docs/api.md`，并在对话中显示摘要： > 已生成API文档，包含： > - 12个端点 > - GET: 5个, POST: 3个, PUT: 2个, DELETE: 2个 > - 涉及3个资源：users, products, orders > - 文件位置：docs/api.md > - 3个字段标记为[待确认]，需要手动补充 ``` ### 4.3 添加辅助资源文件 Skill不仅限于SKILL.md，你可以在同一目录下放置辅助文件，Claude Code会在需要时自动加载它们。 创建一个文档模板文件： ```bash # 在 .claude/skills/api-doc-generator/ 目录下 cat > openapi-template.yaml << 'TEMPLATE' # OpenAPI 3.0 模板 - 用于生成标准化API文档 openapi: "3.0.3" info: title: "[项目名称]" version: "1.0.0" description: "[项目描述]" servers: - url: "http://localhost:3000" description: "开发环境" paths: # Claude将在此处填充端点 components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT TEMPLATE ``` 再创建一个框架检测提示文件： ```bash cat > framework-hints.md << 'HINTS' # 框架特定提取规则 ## Express.js - 路由文件通常在 `routes/` 或 `src/routes/` 目录 - 中间件 `app.use('/path', router)` 中的路径是前缀 - 参数用 `:paramName` 表示 ## FastAPI - 路由定义在Python文件中用装饰器标注 - `@router.get("/items/{item_id}")` 中的路径参数用花括号 - Pydantic模型定义了请求/响应Schema ## Spring Boot - `@RestController` 类中的方法即端点 - `@RequestMapping` 在类级别设置前缀 - 方法级注解 `@GetMapping`、`@PostMapping` 等 HINTS ``` 最终目录结构： ``` .claude/skills/api-doc-generator/ ├── SKILL.md # 核心指令文件 ├── openapi-template.yaml # OpenAPI模板 └── framework-hints.md # 框架检测辅助文件 ``` --- ## 五、Skill激活机制详解 理解激活机制是写出好用Skill的关键。Claude Code有两条激活路径：  > *图表 2* ### 5.1 自动激活 Claude Code分析用户消息，与Skill的`description`和`triggers`进行关键词匹配。匹配成功时，Skill指令被自动注入上下文。 **提高自动激活命中率的技巧**： 1. **description中包含用户可能使用的自然表达** - 好：`"分析项目中的API路由定义，生成标准RESTful API文档"` - 差：`"API doc gen tool"` 2. **triggers列表覆盖同义词和多语言** ```yaml triggers: - API文档 - 接口文档 - api documentation - openapi - swagger - 生成文档 ``` 3. **避免过于宽泛的触发词** - "文档"、"代码"、"修复"这类词太通用，可能导致误触发 - 优先使用具体的专业术语 ### 5.2 手动激活 用户在对话中输入`/skill-name`即可直接调用。`user_invocable: true`的Skill会出现在`/`命令的自动补全列表中。 ### 5.3 调试激活问题 如果Skill没有按预期激活： 1. **检查name拼写**：斜杠命令中的名称必须与frontmatter中的name完全匹配 2. **检查description措辞**：尝试用用户实际会说的自然语言 3. **验证文件位置**：确保SKILL.md在正确的`.claude/skills/`目录下 4. **确认disabled字段**：确保不是`disabled: true` 5. **测试手动激活**：先用`/skill-name`手动调用，确认Skill本身能工作 --- ## 六、测试Skill ### 6.1 手动测试流程 ```bash # 1. 进入你的测试项目 cd /path/to/your/test-project # 2. 确认Skill已就位 ls -la .claude/skills/api-doc-generator/ # 3. 启动Claude Code claude # 4. 测试手动激活 > /api-doc-generator # 5. 测试自动激活（新会话中） > 帮我生成这个项目的API文档 ``` ### 6.2 验证清单 | 检查项 | 预期结果 | 通过？ | |--------|---------|--------| | 手动调用`/api-doc-generator` | Skill被加载，按步骤执行 | | | 自动触发"生成API文档" | Skill被自动匹配并激活 | | | 自动触发"写接口文档" | 同上 | | | 输出文件`docs/api.md`生成 | 文件包含正确的端点信息 | | | 非Web项目提示 | 告知用户不适用而非继续执行 | | | 辅助资源加载 | Claude参考了template和hints文件 | | ### 6.3 常见问题排查 **问题1：Skill未被自动激活** ``` 原因：description和triggers中的关键词与用户消息匹配度不足 解决：扩展triggers列表，在description中加入更多自然语言表达 ``` **问题2：Skill被加载但执行不完整** ``` 原因：指令正文过长或结构不清晰，Claude遗漏了部分步骤 解决：精简正文，使用编号列表，每个步骤控制在3-5行以内 ``` **问题3：辅助资源文件未被使用** ``` 原因：SKILL.md正文中没有引用这些文件的指令 解决：在正文中明确提及辅助文件，如"参考openapi-template.yaml模板格式" ``` --- ## 七、Skill设计模式与最佳实践 ### 7.1 五大设计模式 根据Anthropic官方指南和社区实践，总结出五种核心Skill设计模式： **模式一：检查清单模式（Checklist）** 适用于需要按固定步骤审查或验证的场景。 ```markdown ## 执行步骤 逐一检查以下每一项： - [ ] 1. 检查输入验证是否完备 - [ ] 2. 检查错误处理是否覆盖所有边界情况 - [ ] 3. 检查是否有SQL注入风险 - [ ] 4. 检查日志是否包含敏感信息 - [ ] 5. 检查认证授权是否正确 ``` **模式二：生成器模式（Generator）** 适用于从输入生成结构化输出的场景（如我们的API文档生成器）。 ```markdown ## 执行步骤 1. 收集输入：扫描[目标文件/目录] 2. 解析：从输入中提取[关键信息] 3. 转换：按[模板格式]组织信息 4. 输出：写入[目标文件] 5. 校验：检查输出的完整性和一致性 ``` **模式三：管道模式（Pipeline）** 适用于多阶段处理，每阶段的输出是下一阶段的输入。 ```markdown ## 执行阶段 ### 阶段1：预处理 - 读取原始输入文件 - 标准化格式 - 输出：normalized.json ### 阶段2：分析 - 基于 normalized.json 进行深度分析 - 提取关键指标 - 输出：analysis-result.md ### 阶段3：报告 - 基于 analysis-result.md 生成最终报告 - 包含图表和摘要 - 输出：final-report.md ``` **模式四：守卫模式（Guard）** 适用于约束Claude行为、防止错误的场景。 ```markdown ## 强制规则 在执行任何代码修改之前，必须通过以下检查： 1. **备份检查**：确认目标文件已备份 2. **影响范围检查**：列出所有受影响的文件 3. **回滚方案**：提供git回滚命令 4. **测试验证**：修改后必须运行完整测试套件 如果任何一项检查失败，停止执行并向用户报告。 ``` **模式五：专家角色模式（Expert Persona）** 适用于需要领域专业知识的场景。 ```markdown ## 角色 你是一位拥有15年经验的高级安全工程师，专注于Web应用安全。 ## 知识领域 - OWASP Top 10 - 常见漏洞模式（XSS、CSRF、SQL注入、SSRF） - 安全编码最佳实践 - 威胁建模方法论 ## 审查标准 对每个发现的漏洞，按CVSS 3.1评分，分为： - Critical (9.0-10.0) - High (7.0-8.9) - Medium (4.0-6.9) - Low (0.1-3.9) ``` ### 7.2 Token效率优化 Skill正文会被注入到上下文中，消耗tokens。以下是优化建议： | 策略 | 效果 | 示例 | |------|------|------| | 辅助文件外置 | 减少SKILL.md体积 | 模板和示例放在同目录文件中 | | 使用表格代替散文 | 信息密度更高 | 步骤表格化 | | 删除冗余说明 | 避免重复 | 不要在多处重复同一规则 | | 精确触发词 | 减少无关激活 | 用"SQL注入扫描"替代"安全检查" | --- ## 八、进阶技巧 ### 8.1 嵌套Skill组织 对于复杂功能，可以将多个Skill组织为层级结构： ``` .claude/skills/ ├── security/ │ ├── sql-injection-scanner/SKILL.md │ ├── xss-scanner/SKILL.md │ └── dependency-audit/SKILL.md ├── docs/ │ ├── api-doc-generator/SKILL.md │ └── changelog-generator/SKILL.md └── quality/ ├── code-review/SKILL.md └── test-generator/SKILL.md ``` 子文件夹名称不影响Skill的`name`字段，但有助于人类管理。 ### 8.2 动态上下文注入 在SKILL.md中引用Shell命令输出，实现动态上下文： ```markdown ## 当前环境信息 运行以下命令获取项目状态： - `git branch --show-current`：当前分支 - `git diff --stat`：未提交的变更 - `cat package.json | grep version`：项目版本 在执行Skill之前，先获取这些信息作为上下文。 ``` ### 8.3 与CLAUDE.md协同 在项目的`CLAUDE.md`中引用Skill，建立协同关系： ```markdown # 项目指南 ## 安全审查 每次修改认证相关代码时，自动使用 sql-injection-scanner 和 xss-scanner Skill。 ## 文档更新 每次添加新API端点后，使用 api-doc-generator 更新文档。 ``` ### 8.4 条件式Skill加载 利用`disabled`字段和描述语言实现条件激活： ```yaml --- name: production-deploy-guard description: 在部署到生产环境之前执行安全检查清单。仅在用户提到"部署"或"deploy"到"生产"或"production"时激活。 triggers: - 部署到生产 - 生产环境部署 - deploy production - production deploy --- ``` --- ## 九、发布与分享 ### 9.1 发布到GitHub 最简单的分享方式是将Skill作为GitHub仓库发布： ```bash # 1. 创建独立仓库 mkdir api-doc-generator-skill && cd api-doc-generator-skill # 2. 复制Skill文件 cp -r /path/to/.claude/skills/api-doc-generator/* . # 3. 添加README cat > README.md << 'EOF' # API文档生成器 - Claude Code Skill ## 安装 ```bash # 克隆到Claude Code skills目录 git clone https://github.com/yourname/api-doc-generator-skill.git \ ~/.claude/skills/api-doc-generator ``` ## 使用 在Claude Code中输入 `/api-doc-generator` 或说"帮我生成API文档" EOF # 4. 推送 git init && git add . && git commit -m "Initial skill release" git remote add origin https://github.com/yourname/api-doc-generator-skill.git git push -u origin main ``` ### 9.2 贡献到Anthropic官方Skills仓库 Anthropic维护了官方Skills仓库 [anthropics/skills](https://github.com/anthropics/skills)，你可以通过PR贡献： 1. Fork [anthropics/skills](https://github.com/anthropics/skills) 2. 在合适的位置创建你的Skill文件夹 3. 确保SKILL.md格式符合官方规范 4. 添加清晰的README 5. 提交Pull Request ### 9.3 通过Skills市场分发 截至2026年，社区已出现多个Skill分发平台： | 平台 | 地址 | 特点 | |------|------|------| | Anthropic官方仓库 | github.com/anthropics/skills | 官方认证，质量最高 | | SkillsMP | skillsmp.com | 120万+ Skill索引 | | Agensi | agensi.io | 支持ZIP下载和MCP安装 | | MCPMarket | mcpmarket.com | 按类别浏览，含评分 | --- ## 十、完整工作流总结  > *图表 3* **开发流程关键节点**： 1. **需求分析**：明确Skill要解决什么问题、触发场景是什么 2. **模式选择**：从五大设计模式中选择最合适的作为骨架 3. **编写SKILL.md**：frontmatter精准描述，正文结构化指令 4. **测试验证**：手动激活 + 自动激活双重验证 5. **迭代优化**：根据实际使用效果调整触发词和指令 6. **发布分享**：GitHub仓库、官方仓库PR、或社区平台 --- ## 延伸阅读 - [Anthropic官方Skills仓库](https://github.com/anthropics/skills) - 官方维护的Skill集合和规范 - [The Complete Guide to Building Skills for Claude](https://resources.anthropic.com/hubfs/The-Complete-Guide-to-Building-Skill-for-Claude.pdf) - Anthropic发布的33页官方Skill开发指南 - [Claude Code官方文档 - Skills](https://code.claude.com/docs/en/skills) - Skills功能的官方参考文档 - [Claude Code Skills激活系统](https://ytrofr.github.io/claude-code-guide/docs/skill-activation-system.html) - 激活机制的深入技术分析 - [Skill设计模式详解](https://cc.bruniaux.com/guide/skill-design-patterns/) - 社区整理的Skill架构模式 - [Inside Claude Code Skills](https://mikhail.io/2025/10/claude-code-skills/) - Skill内部机制的逆向分析 --- ## 训练营适用性评估 | 维度 | 评估 | |------|------| | **适合训练营类型** | AI工具深度使用训练营、开发者效率训练营、Claude Code认证培训 | | **预计教学时长** | 2-3小时（含动手实操） | | **难度等级** | 中级（需Claude Code基础） | | **实操比重** | 60%实操 + 40%讲解 | | **前置知识** | Claude Code基本操作、Markdown语法、YAML基础 | | **建议班级规模** | 15-20人（便于逐一指导Skill调试） | | **课后作业** | 每位学员独立开发一个解决自身工作痛点的Skill并演示 | > [!tip] 51学通信知识星球 > **星主：爱卫生**（微信：gprshome201101）——公众号「51学通信」创办者，19 年通信行业运维与讲师经验，著有《GPRS网络信令实例详解》《EPC原理与实践》《5G核心网原理与实践》三本纸质书（各大电商平台有售）。 > **星球定位**：深耕 5G 核心网、IMS、NFV/AI、云原生等 ICT 领域，主打运维岗位与信令分析。 > **当前规模**：5200 篇主题 / 990 个回答，198 元/年。 > **加入福利**：加入星球后请加爱卫生微信，拉您进知识星球年度陪伴与答疑群——不限量回复您的各种问题，另有群内分享。 > **AI 加持**：51学通信知识星球已作为 skill 接入 WorkBuddy，使用 deepseek-4-flash 在海量星球帖子中精准找贴、找视频、找 FAQ 和案例，做总结、找文档和 PPT 等场景全覆盖。