Claude Code Skill 的编写

从零基础到生产级系统掌握 Claude Code Skill 的编写。本文从最小可用技能开始逐步叠加知识、权限、模板、脚本、决策树最终构建一个资深级的复杂技能。一、核心概念基础1.1 什么是 SkillSkill 是一个上下文注入包。激活后Claude Code 会将指定文件夹中的指令、知识、权限配置注入对话上下文使模型在限定范围内表现出专业行为。1.2 最小技能结构my-skill/ └── SKILL.md # 唯一必需文件SKILL.md包含两部分YAML 前置元数据定义技能名称、描述、权限等。Markdown 正文写给 Claude 的系统指令。1.3 SKILL.md 示例入门---name:hellodescription:一个示例技能---# Hello 技能 当我提问时请先回答“你好我是由技能驱动的助手”。这就是一个可工作的技能。安装后每次激活时 Claude 都会加上这句问候。二、核心知识点逐层展开2.1 元数据字段必知必会name技能唯一标识用 kebab-case。description描述技能功能显示在/skills列表中。allowed-tools工具白名单强烈推荐。不设则继承当前会话全部权限。model锁定模型如claude-sonnet-4-20250514。files激活时预加载的文件列表很少用改用{{ include }}更灵活。2.2 工具权限安全核心allowed-tools语法工具名(限定)逗号分隔。读工具通常全开Read,Grep,Glob写工具必须限定路径Write(templates/*.ts),Edit(src/**)Bash 必须限定命令Bash(git:status, git:diff, npm:run:lint)权限是替换式激活时覆盖当前会话权限。2.3{{ include }}指令将技能目录下的文件内容注入到指令正文中减少SKILL.md体积方便管理。请遵守以下编码规范 {{ include knowledge/style-guide.md }}2.4 技能目录组织约定my-skill/ ├── SKILL.md ├── templates/ # 代码模板 ├── knowledge/ # 规范、知识 ├── scripts/ # 受控执行脚本 ├── examples/ # 示例输入输出 └── schemas/ # JSON Schema 等这不是强制的但随着复杂度增长合理的目录结构是技能可维护性的基础。三、案例一Git 辅助技能入门级目标生成 Conventional Commits并执行安全的 Git 操作。目录结构git-helper/ └── SKILL.mdSKILL.md---name:git-helperdescription:根据暂存变更生成规范的 Git 提交信息并执行安全提交。allowed-tools:Read,Bash(git:status,git:diff,git:add,git:commit)---# Git Helper ## 角色 你是一个严格遵守 Conventional Commits 的 Git 助手。 ## 流程 1. 执行 git status --porcelain 和 git diff --staged 获取暂存区变化。 2. 根据变更内容生成一条提交信息格式 - feat: 描述 新功能 - fix: 描述 修复 - refactor: 描述 重构 - test: 描述 测试 - docs: 描述 文档 3. 将生成的提交信息展示给用户确认再执行 git commit -m ...。 ## 禁止 - 不得执行 force push。 - 不得修改暂存区以外的文件。知识点总结权限锁定在git status/diff/add/commit绝对安全。指令结构化角色 流程 禁止项。简单清晰一个文件搞定。四、案例二代码审查技能进阶级目标结合 lint 工具、团队规范和模板输出分级审查报告。目录结构code-reviewer/ ├── SKILL.md ├── templates/ │ └── review-checklist.md └── scripts/ └── run_lint.shSKILL.md---name:code-reviewerdescription:基于团队规范与 Lint 结果的代码审查输出分级报告。allowed-tools:Read,Grep,Glob,Bash(git:diff,bash:./scripts/run_lint.sh)model:claude-sonnet-4-20250514---# 代码审查技能 ## 角色 你是一位前端审查员遵守团队规范。 ## 审查清单 以下是必须逐条核对的标准 {{ include templates/review-checklist.md }} ## 工作流 1. 获取暂存区 diffgit diff --staged 2. 运行 lintbash ./scripts/run_lint.sh 3. 结合 diff 和 lint 结果依据审查清单给出分级 - 错误必须修复 - 警告应该修复 - 建议可忽略 4. 输出表格报告 | 级别 | 类别 | 文件:行号 | 描述 | 修复建议 | |------|------|-----------|------|----------| | ... | ... | ... | ... | ... | ## 禁止 - 不得直接修改任何源文件。 - 不要建议推翻整个架构。templates/review-checklist.md- 类型安全所有函数必须注明参数和返回值类型。 - 命名规范变量 camelCase组件 PascalCase。 - 错误处理禁止空 catch。 - 副作用React 组件 render 内不能有数据请求。scripts/run_lint.sh#!/bin/bashnpx eslint--formatjson${:-.}||true知识点总结使用{{ include }}加载外部规范文件SKILL.md保持简洁。通过封装脚本run_lint.sh运行 lint获得确定性 JSON 输出Claude 解析结构化数据。权限包含脚本调用限制了直接 Bash 的风险。指定模型保证输出质量。五、案例三全栈重构智能体资深级目标构建一个对全栈 TypeScript 单体仓库进行安全、分阶段重构的复杂技能。涵盖前端React、后端Express、数据库TypeORM要求生成回滚、更新 API 契约、保证测试通过。5.1 技能架构设计此技能将遵循分层架构调度层SKILL.md作为中央调度器根据阶段动态加载工作流。知识层团队规范、设计模式、反模式、术语表。资源层代码模板、数据库迁移模板、API 契约 Schema。执行层受控脚本lint、测试、迁移安全检查。示例层历史成功重构案例用作少样本教学。5.2 完整目录结构fullstack-refactor/ ├── SKILL.md ├── .claude/ │ └── rules/ │ ├── security.md │ └── architecture.md ├── core/ │ ├── workflows/ │ │ ├── assess.md │ │ ├── plan.md │ │ ├── execute.md │ │ └── verify.md │ └── decision-trees/ │ └── db-strategy.md ├── knowledge/ │ ├── conventions/ │ │ ├── backend.md │ │ ├── frontend.md │ │ └── database.md │ ├── patterns/ │ │ ├── approved.md │ │ └── anti-patterns.md │ └── glossary.md ├── templates/ │ ├── migration/ │ │ └── typeorm.template.ts │ ├── component/ │ │ └── functional.template.tsx │ └── api/ │ └── controller.template.ts ├── schemas/ │ └── api-contract.schema.json ├── scripts/ │ ├── run_lint.sh │ ├── run_tests.sh │ └── check_migration_safety.py ├── examples/ │ └── rename-field/ │ ├── request.md │ └── result.md └── VERSION5.3 核心指令SKILL.md---name:fullstack-refactordescription:全栈重构智能体分阶段安全地重构 React、Node.js、TypeORM 项目。allowed-tools:Read,Write(apps/*,packages/*),Edit(apps/*,packages/*),Grep,Glob,Bash(git:status,git:diff,git:add,git:commit,npm:run:lint,npm:test,bash:scripts/run_lint.sh,bash:scripts/run_tests.sh,python:scripts/check_migration_safety.py)model:claude-opus-4-20250514---# 全栈重构智能体 ## 角色 你是资深全栈架构师精通 React、Node.js、TypeORM、PostgreSQL。 你的使命安全地执行用户提出的重构请求。 ## 全局约束 - 必须遵循 knowledge/conventions/ 下所有规范。 - 使用 knowledge/glossary.md 中的术语。 - 数据库变更必须经过 scripts/check_migration_safety.py 验证。 - API 变更需同步更新 schemas/api-contract.schema.json。 - 前端组件重构不得破坏现有测试。 ## 分阶段执行 严格按照以下阶段进行每阶段结束必须获得用户确认才能继续。 ### 阶段 1: 评估 {{ include core/workflows/assess.md }} ### 阶段 2: 规划 {{ include core/workflows/plan.md }} ### 阶段 3: 执行 {{ include core/workflows/execute.md }} ### 阶段 4: 验证 {{ include core/workflows/verify.md }} ## 决策支持 当涉及数据库变更时必须依据决策树 {{ include core/decision-trees/db-strategy.md }} ## 示例参考 理想的重构行为应参考 examples/rename-field/学习其回滚策略和前后端协调。 ## 禁止 - 绝不直接修改生产配置 (*.prod.*)。 - 绝不跳过安全检查。 - 绝不删除现有测试。5.4 工作流文件部分示例core/workflows/assess.md## 评估阶段 ### 行动 1. 运行 git status 和 git log --oneline -10 理解上下文。 2. 与用户沟通明确重构目标。 3. 使用 Grep/Glob 定位所有受影响模块。 4. 列出所有相关测试文件。 5. 若涉及数据库实体读取对应 Entity 文件。 ### 输出 生成影响分析报告 - 受影响模块 (前端/后端/数据库) - 风险等级 (高/中/低) - 建议策略 (渐进式/大爆炸) 等待用户确认进入规划阶段。core/decision-trees/db-strategy.md## 数据库变更策略决策树 - 添加可空列 → 直接添加 - 添加非空列 → 1) 先添加为可空 2) 回填数据 3) 添加 NOT NULL - 重命名列 → 保留旧列新增列复制数据标记旧列为 deprecated待前端适配后移除 - 删除列 → 先标记 deprecated至少一个大版本后删除5.5 知识层文件示例knowledge/conventions/backend.md### 错误处理 - 异步操作必须 try/catch抛出 AppError。 - 禁止 console.log使用 winston。 ### 数据库 - 使用 TypeORM QueryBuilder禁止拼接 SQL。knowledge/patterns/anti-patterns.md1. 在 React 组件内直接调 API → 使用自定义 hook。 2. 迁移文件中做复杂数据转换 → 移至服务层。5.6 模板示例templates/migration/typeorm.template.tsimport{MigrationInterface,QueryRunner}fromtypeorm;exportclassMigration{{Timestamp}}implementsMigrationInterface{nameMigration{{Timestamp}}publicasyncup(queryRunner:QueryRunner):Promisevoid{// UP: {{Description}}{{UpStatements}}}publicasyncdown(queryRunner:QueryRunner):Promisevoid{// DOWN: {{Description}}{{DownStatements}}}}指令中要求生成迁移时必须读取此模板替换占位符然后写入migrations/目录。5.7 脚本层scripts/check_migration_safety.py应输出 JSON{safe:true,issues:[]}在execute工作流中强制要求“生成迁移文件后立即运行python scripts/check_migration_safety.py 迁移文件路径分析 JSON 输出如果safe不为 true则中止并报告问题。”5.8 示例层examples/rename-field/request.md和result.md提供完整的对话转录展示成功重命名数据库列的全过程。Claude 会将其作为理想行为模式参考。5.9 动态加载与自省在SKILL.md中虽然没有条件include但可通过引导实现伪动态根据重构类型主动使用 Read 工具加载以下文件 - 若涉及后端加载 knowledge/conventions/backend.md - 若涉及前端加载 knowledge/conventions/frontend.md - 若涉及数据库加载 knowledge/conventions/database.mdClaude 会根据指令自行调用Read工具按需加载避免上下文浪费。5.10 验证和 CI 集成VERSION文件记录版本tests/目录可放验证脚本例如检查所有include路径是否存在YAML 格式是否正确权限是否过度开放。可集成到 GitHub Actions确保技能质量。六、资深级技能的设计原则原则体现分层解耦调度、知识、资源、执行分离声明式优先使用 Markdown 知识和模板避免脚本逻辑权限最小化Write/Edit 精确到目录Bash 限定命令阶段化协同评估→规划→执行→验证人机确认点知识外化团队规范和反模式独立维护可复用决策自动化决策树让模型自行推理不硬编码分支示例驱动历史成功案例作为少样本引导安全内建迁移安全检查脚本强制调用无例外模型锁定复杂推理锁定 Opus确保质量七、总结从单文件问候技能到带权限、模板的审查器再到全栈重构智能体复杂度逐步递增但底层逻辑不变技能 受限上下文 结构化知识 受控执行。掌握这一模式后任何工程领域的重复或规范敏感工作都可以封装为可靠、可共享的技能。