# Claude Code Skill全生命周期：从零到发布实战 ## 概述 本教程面向希望系统掌握 Claude Code Skill 开发全流程的开发者。你将学习 SKILL.md 的精确格式规范、Frontmatter 的每个字段含义、渐进式披露（Progressive Disclosure）架构设计、Evals 驱动的测试方法，以及通过 Plugin Marketplace 发布 Skill 的完整路径。教程以一个「数据库迁移安全审查 Skill」为实战案例，覆盖从构思、编写、测试到分发的完整生命周期。 **适用人群**：已安装 Claude Code 并有基本使用经验的开发者；团队技术负责人；希望标准化 AI 辅助工作流的工程师。 **前置条件**： - Claude Code CLI 已安装（`npm install -g @anthropic-ai/claude-code`） - Node.js 18+ 环境 - 基本熟悉 Markdown 和 YAML 语法 - 一个可运行的 Git 项目（用于实践） --- ## 第一步：理解 Skill 的本质——不是提示词，是能力包 很多开发者第一次接触 Skill 时，会把它当作「高级版 system prompt」。这个认知只对了一半。Skill 的核心设计理念是 **渐进式披露（Progressive Disclosure）**——当数百个 Skill 同时存在时，Claude 不可能把所有内容全部塞进上下文窗口。 ### 三层加载架构 ``` ┌─────────────────────────────────────────────────┐ │ Layer 1: Discovery（发现层） │ │ 仅加载 name + description │ │ 决定是否激活此 Skill │ │ ~50 tokens / Skill │ ├─────────────────────────────────────────────────┤ │ Layer 2: Activation（激活层） │ │ 加载完整 SKILL.md 正文 │ │ Claude 阅读详细指令和步骤 │ │ ~500-2000 tokens / Skill │ ├─────────────────────────────────────────────────┤ │ Layer 3: Execution（执行层） │ │ 按需加载引用文件、脚本、模板 │ │ 只有真正用到时才读取 │ │ 按需加载，无固定上限 │ └─────────────────────────────────────────────────┘ ``` 这意味着你的 Skill 写得好不好，首先取决于 **发现层能不能让 Claude 准确判断何时该用这个 Skill**。如果 description 写得模糊，Skill 要么永远不会被触发，要么在不该触发时误触发。 ### Skill 与传统 Commands 的区别 | 维度 | `.claude/commands/` | `.claude/skills/` | |------|---------------------|-------------------| | 触发方式 | 用户手动 `/command` | Claude 自动发现或用户 `/skill` | | 上下文占用 | 每次加载完整内容 | 渐进式，按需加载 | | 资源支持 | 仅 Markdown 文件 | 脚本、模板、引用文件 | | 适用场景 | 简单一次性指令 | 复杂可复用工作流 | | 工具控制 | 无 | `allowed-tools` 前端控制 | | 隔离执行 | 无 | `isolation` 子 Agent 模式 | **关键决策点**：如果你的指令超过 30 行，或者需要引用外部文件/脚本，请使用 Skill 而非 Command。 --- ## 第二步：Skill 的目录结构——一个完整的文件系统 一个生产级 Skill 不仅是 `SKILL.md`，而是一个完整的目录结构： ``` .claude/skills/db-migration-reviewer/ ├── SKILL.md # 核心指令文件（必需） ├── templates/ │ ├── review-checklist.md # 审查清单模板 │ └── risk-report.md # 风险报告模板 ├── scripts/ │ └── schema-diff.sh # Schema 差异提取脚本 └── examples/ ├── safe-migration.sql # 安全迁移示例 └── dangerous-migration.sql # 危险迁移示例 ``` ### 创建目录结构 ```bash # 进入项目根目录 cd your-project # 创建 Skill 目录结构 mkdir -p .claude/skills/db-migration-reviewer/{templates,scripts,examples} # 验证目录结构 tree .claude/skills/db-migration-reviewer/ ``` **预期输出**： ``` .claude/skills/db-migration-reviewer/ ├── examples ├── scripts └── templates ``` > **常见问题**：目录名必须使用 kebab-case（小写字母 + 连字符），不能用驼峰或下划线。`db-migration-reviewer` 正确，`dbMigrationReviewer` 或 `db_migration_reviewer` 会导致发现失败。 --- ## 第三步：编写 SKILL.md——Frontmatter 精确规范 SKILL.md 由两个部分组成：**YAML Frontmatter**（元数据声明）和 **Markdown Body**（执行指令）。我们先处理 Frontmatter。 ### Frontmatter 完整字段参考 ```yaml --- name: db-migration-reviewer # 必需，kebab-case，唯一标识符 description: > # 必需，50-200字符，决定 Discovery 层匹配 审查数据库迁移脚本的DDL/DML语句， 检测破坏性操作、性能风险和数据丢失隐患， 生成结构化安全审查报告。 model: sonnet # 可选：sonnet | opus | haiku # 指定执行此 Skill 时的模型偏好 effort: high # 可选：low | medium | high # 控制推理深度，high 适合复杂分析任务 isolation: false # 可选：true | false # true = 在子 Agent 隔离上下文中执行 disable-context: [] # 可选：要排除的上下文类型 # - claude-md # 例：不加载 CLAUDE.md # - git-history # 例：不读取 git 历史 allowed-tools: # 可可选：声明此 Skill 需要的工具权限 - Read # 读取文件 - Grep # 搜索内容 - Bash # 执行命令（用于运行脚本） - Glob # 文件查找 --- ``` ### 字段选值策略 **model 字段的选择逻辑**： ``` 你的 Skill 是否需要深度推理？ ├── 是（代码审查、架构分析、安全审计） │ └── model: opus ├── 否，但需要理解中等复杂度的上下文 │ └── model: sonnet ← 大多数 Skill 的默认选择 └── 简单的格式化或模板生成 └── model: haiku ``` **effort 字段的选择逻辑**： | effort | 适用场景 | Token 开销 | 延迟 | |--------|---------|-----------|------| | `low` | 格式转换、简单问答 | ~1x | 快 | | `medium` | 代码生成、文档编写 | ~2x | 中等 | | `high` | 安全审计、架构分析 | ~4x | 慢 | **isolation 字段**：当 Skill 执行过程中会产生大量中间上下文（如读取大文件、生成长报告），设置为 `true` 可以将这些临时上下文隔离在子 Agent 中，避免污染主对话窗口。 ### 我们的实战 Frontmatter ```yaml --- name: db-migration-reviewer description: > 审查数据库迁移SQL脚本的DDL和DML语句， 检测破坏性操作（DROP/DELETE无WHERE）、 性能风险（全表扫描、大事务）和数据丢失隐患， 输出结构化安全审查报告和修复建议。 model: sonnet effort: high isolation: true allowed-tools: - Read - Grep - Bash - Glob --- ``` > **常见问题**：`description` 是最关键的字段。Claude 在 Discovery 层根据 description 判断是否激活此 Skill。写得太笼统（如"审查SQL"）会导致误触发；写得太具体（如"审查 PostgreSQL 14.2 的 ALTER TABLE 语句"）会导致漏触发。推荐模式：**做什么 + 对什么对象 + 输出什么结果**。 --- ## 第四步：编写 SKILL.md Body——指令工程的艺术 Frontmatter 之后的 Markdown 正文是 Activation 层加载的内容。这部分决定了 Claude 执行 Skill 时的行为质量。 ### Body 的推荐结构 ```markdown ## 指令概述 （一句话说明这个 Skill 的目的） ## 触发条件 （明确说明何时应该激活此 Skill） ## 执行步骤 （按步骤列出具体操作，每步有明确的输入/输出） ## 约束与边界 （什么不该做，什么情况下应该中止） ## 输出格式 （期望的输出模板） ## 参考文件 （列出 Skill 目录下需要按需加载的文件） ``` ### 完整的 SKILL.md Body 接在 Frontmatter 之后，写入以下内容： ```markdown ## 指令概述 你是一名数据库安全审查专家。当用户提供或项目中存在数据库迁移脚本时， 你需要对这些脚本进行全面的安全审查，识别潜在的破坏性操作和性能风险。 ## 触发条件 在以下情况下激活此 Skill： - 用户要求审查 SQL 迁移文件 - 项目中出现新的 migration 文件（如 `migrations/*.sql`、`db/migrate/*.sql`） - 用户使用 `/db-migration-reviewer` 命令 - 用户提到"迁移审查"、"SQL review"、"migration check" ## 执行步骤 ### Step 1: 定位迁移文件 使用 Glob 工具查找项目中的迁移文件： - 搜索模式：`**/*migration*/**/*.sql` - 同时搜索：`**/db/migrate/**/*.sql` - 如果用户指定了具体文件，直接读取该文件 ### Step 2: 分类分析 对每个迁移文件中的 SQL 语句进行分类： **DDL 操作审查**（高风险）： - `DROP TABLE` / `DROP COLUMN` → 确认是否有数据备份 - `ALTER TABLE ... DROP` → 检查列是否还被引用 - `TRUNCATE` → 确认是否在事务中 - `RENAME` → 检查应用代码是否同步更新 **DML 操作审查**（中风险）： - `DELETE` 无 `WHERE` → 标记为 ⛔ 危险 - `UPDATE` 无 `WHERE` → 标记为 ⚠️ 警告 - 大批量 `INSERT` → 检查是否分批执行 **性能风险审查**： - 全表扫描可能性（缺少索引的 JOIN/WHERE） - 大事务（多个 DDL 在单个事务中） - 锁表风险（DDL 操作期间的表锁） ### Step 3: 生成审查报告 读取模板文件 `templates/risk-report.md`，按模板格式生成报告。 报告中每个问题必须包含： - 风险等级：⛔ 严重 / ⚠️ 警告 / 💡 建议 - 具体位置：文件名 + 行号 - 问题描述：清晰说明风险 - 修复建议：可执行的替代方案 ### Step 4: 提供修复建议 对每个发现的问题，提供具体的修复 SQL： - 将 `DROP TABLE` 改为安全的重命名方案 - 为无 WHERE 的 DELETE/UPDATE 添加条件 - 为大事务提供分批执行方案 ## 约束与边界 - 不要自动修改任何迁移文件，只提供审查报告 - 不要执行任何 SQL 语句 - 如果迁移文件超过 1000 行，只审查前 200 行并警告用户 - 如果无法确定某条语句是否安全，标记为"需人工确认" - 不要假设数据库类型，根据 SQL 方言特征判断 ## 输出格式 使用以下结构输出审查报告： --- ### 迁移审查报告 **文件**: {文件路径} **审查时间**: {当前日期} **总体风险**: {低/中/高/严重} #### 发现的问题 | # | 风险等级 | 位置 | 问题描述 | 修复建议 | |---|---------|------|---------|---------| | 1 | ⛔ 严重 | L23 | DELETE 无 WHERE 子句 | 添加 WHERE created_at < '2024-01-01' | #### 统计摘要 - DDL 语句: X 条（高风险: X） - DML 语句: X 条（中风险: X） - 性能建议: X 条 #### 建议的安全执行顺序 1. {按依赖关系和安全级别排序的执行顺序} --- ## 参考文件 - `templates/risk-report.md` — 完整的风险报告模板 - `templates/review-checklist.md` — 审查清单 - `examples/safe-migration.sql` — 安全迁移示例 - `examples/dangerous-migration.sql` — 危险迁移示例 - `scripts/schema-diff.sh` — Schema 差异提取工具 ``` ### 指令编写的五个黄金法则 **法则一：动作动词开头** ``` ❌ 这个步骤是关于读取文件的 ✅ 读取项目中的所有 SQL 迁移文件 ❌ 你应该考虑检查 DELETE 语句 ✅ 检查每条 DELETE 语句是否包含 WHERE 子句 ``` **法则二：给判断标准，不给模糊空间** ``` ❌ 检查迁移是否安全 ✅ 检查以下 5 项：DROP 无备份、DELETE 无 WHERE、ALTER 影响列引用、 大事务超过 50 行 DDL、缺少回滚脚本 ``` **法则三：明确边界——什么不该做** ```markdown ## 约束与边界 - 不要自动修改任何迁移文件 - 不要执行任何 SQL 语句 - 超过 1000 行只审查前 200 行 ``` 没有边界的 Skill 会过度执行，可能产生破坏性后果。 **法则四：输出模板化** 提供一个具体的输出格式模板，而不是说"生成一份报告"。模板让 Claude 的输出稳定可预测，也便于下游工具解析。 **法则五：引用文件延迟加载** 不要把所有内容塞进 SKILL.md。模板、示例、脚本都放在子目录，在正文中用 `读取文件 X` 的方式引用。这就是渐进式披露的执行层——只有真正需要时才加载。 --- ## 第五步：创建辅助资源文件 ### 审查清单模板 创建 `.claude/skills/db-migration-reviewer/templates/review-checklist.md`： ```markdown # 数据库迁移审查清单 ## DDL 操作 - [ ] DROP 操作是否有数据备份方案？ - [ ] ALTER TABLE 是否影响正在使用的列？ - [ ] 新增列是否有默认值或允许 NULL？ - [ ] 索引创建是否使用 CONCURRENTLY（PostgreSQL）？ - [ ] 外键约束是否会导致锁表？ ## DML 操作 - [ ] DELETE/UPDATE 是否都有 WHERE 条件？ - [ ] WHERE 条件是否使用了索引列？ - [ ] 大批量操作是否分批执行？ - [ ] 是否存在隐式类型转换？ ## 事务与锁 - [ ] 单个事务中的 DDL 数量是否超过 3 个？ - [ ] 是否有可能导致长事务？ - [ ] 高峰期执行是否会影响线上服务？ ## 回滚方案 - [ ] 是否提供了回滚脚本？ - [ ] 回滚脚本是否经过验证？ ``` ### Schema 差异提取脚本 创建 `.claude/skills/db-migration-reviewer/scripts/schema-diff.sh`： ```bash #!/bin/bash # 提取两个 SQL 文件之间的 Schema 差异 # 用法: ./schema-diff.sh set -euo pipefail BEFORE="${1:?用法: $0 }" AFTER="${2:?用法: $0 }" echo "=== Schema 差异分析 ===" echo "基准文件: $BEFORE" echo "目标文件: $AFTER" echo "" # 提取表名差异 echo "--- 表级变更 ---" diff <(grep -iE 'CREATE TABLE|DROP TABLE' "$BEFORE" | sort) \ <(grep -iE 'CREATE TABLE|DROP TABLE' "$AFTER" | sort) || true echo "" echo "--- 列级变更 ---" diff <(grep -iE 'ADD COLUMN|DROP COLUMN|ALTER COLUMN' "$BEFORE" | sort) \ <(grep -iE 'ADD COLUMN|DROP COLUMN|ALTER COLUMN' "$AFTER" | sort) || true echo "" echo "--- 索引变更 ---" diff <(grep -iE 'CREATE INDEX|DROP INDEX' "$BEFORE" | sort) \ <(grep -iE 'CREATE INDEX|DROP INDEX' "$AFTER" | sort) || true ``` ```bash chmod +x .claude/skills/db-migration-reviewer/scripts/schema-diff.sh ``` ### 示例文件 创建 `.claude/skills/db-migration-reviewer/examples/dangerous-migration.sql`： ```sql -- V202__dangerous_cleanup.sql -- ⚠️ 这是一个包含多种风险的迁移示例 -- 风险1: DROP TABLE 没有备份 DROP TABLE user_sessions; -- 风险2: DELETE 没有 WHERE DELETE FROM logs; -- 风险3: 大批量 UPDATE 没有 LIMIT UPDATE orders SET status = 'archived'; -- 风险4: ALTER TABLE 可能导致锁表 ALTER TABLE users DROP COLUMN phone_number; -- 风险5: 多个 DDL 在同一事务 BEGIN; ALTER TABLE products ADD COLUMN search_vector tsvector; CREATE INDEX idx_products_search ON products USING gin(search_vector); ALTER TABLE products ALTER COLUMN search_vector SET NOT NULL; COMMIT; ``` --- ## 第六步：测试 Skill——三种验证方法 ### 方法一：手动触发验证 ```bash # 在项目根目录启动 Claude Code claude # 使用斜杠命令触发 > /db-migration-reviewer # 或用自然语言触发 > 帮我审查一下 examples/dangerous-migration.sql 这个迁移文件 ``` **预期行为**：Claude 应该加载 Skill，读取 dangerous-migration.sql，按审查清单逐条分析，生成包含 5 个风险项的结构化报告。 **验证清单**： - [ ] Claude 是否正确识别了所有 5 个风险点？ - [ ] 报告格式是否符合模板要求？ - [ ] 每个 risk 是否都有修复建议？ - [ ] Claude 是否没有自动修改 SQL 文件？ ### 方法二：Evals 基准测试 使用 Skill Creator 内置的 Evals 系统进行自动化测试。创建 eval 文件 `.claude/skills/db-migration-reviewer/evals.md`： ```markdown # Evals: db-migration-reviewer ## Test Case 1: 检测 DELETE 无 WHERE **Input**: 包含 `DELETE FROM logs;` 的 SQL 文件 **Expected**: 报告中标记为 ⛔ 严重，位置指向正确行号 **Pass criteria**: 输出包含"DELETE"和"无 WHERE"关键字 ## Test Case 2: 检测大事务风险 **Input**: BEGIN/COMMIT 块中包含 3+ 条 DDL **Expected**: 报告中标记为 ⚠️ 警告，说明锁表风险 **Pass criteria**: 输出包含"事务"和"DDL"关键字 ## Test Case 3: 安全迁移应通过审查 **Input**: 仅包含 `ALTER TABLE ADD COLUMN ... DEFAULT 0` 的文件 **Expected**: 总体风险为"低"，无 ⛔ 严重项 **Pass criteria**: 输出包含"低"且不包含"⛔" ## Test Case 4: 边界约束测试 **Input**: 超过 1000 行的 SQL 文件 **Expected**: 只审查前 200 行，并警告用户文件过大 **Pass criteria**: 输出包含"200 行"或"文件过大" ``` 在 Claude Code 中运行 evals： ```bash > /skill-creator run-evals db-migration-reviewer ``` ### 方法三：对比测试（A/B Benchmark） 如果你修改了 Skill 的指令，可以用对比测试验证改进效果： ```bash # 在 Claude Code 中 > /skill-creator benchmark db-migration-reviewer --compare main ``` 这会对比当前版本和 `main` 分支版本的表现差异，输出量化指标： ``` Benchmark Results: Precision: 0.92 (+0.05 vs main) Recall: 0.88 (+0.03 vs main) Latency: 4.2s (-1.1s vs main) Token usage: 1.8k (-200 vs main) ``` > **常见问题**：Evals 的 Pass criteria 不要写得太宽松。`输出包含"DELETE"` 太模糊，应该写 `输出中 ⛔ 严重列表包含指向 DELETE 语句所在行号的风险项`。 --- ## 第七步：迭代优化——Evals 驱动的改进循环 ```mermaid flowchart LR A[编写 Skill 初版] --> B[编写 Evals 测试用例] B --> C[运行 Evals] C --> D{通过率 > 90%?} D -->|否| E[分析失败用例] E --> F[修改 SKILL.md 指令] F --> C D -->|是| G[运行 A/B Benchmark] G --> H{优于旧版本?} H -->|否| I[回滚并调整策略] I --> F H -->|是| J[合并并发布] J --> K[收集用户反馈] K --> B ``` ### 典型的迭代场景 **场景一：误触发（False Positive）** 如果 Claude 在你不期望的时候自动激活了 Skill，问题出在 `description`： ```yaml # 太宽泛 description: 审查 SQL 文件 # 改进后——限定触发范围 description: > 审查数据库迁移SQL脚本的DDL和DML语句， 检测破坏性操作、性能风险和数据丢失隐患， 输出结构化安全审查报告。 ``` **场景二：漏检（False Negative）** 如果 Claude 遗漏了某些风险项，问题出在 Body 的步骤描述不够具体： ```markdown # 太模糊 ### Step 2: 分析 SQL 语句 检查迁移文件中的所有 SQL 语句。 # 改进后——枚举所有检查项 ### Step 2: 分类分析 对每条 SQL 语句逐一检查以下 5 类风险： 1. DROP 操作 → 检查是否有备份方案 2. DELETE/UPDATE → 检查 WHERE 子句是否存在 3. ALTER TABLE → 检查影响范围 4. 大事务 → DDL 数量 > 3 标记为风险 5. 缺少索引 → 全表扫描风险 ``` **场景三：输出不稳定** 如果每次执行的输出格式不一致，问题出在缺少输出模板约束。解决方案：在 Body 中提供完整的 Markdown 模板（如第四步所示），并添加明确指令： ```markdown 严格按以下模板输出，不要添加模板中未定义的章节。 如果某个章节没有内容，写"无"而非省略该章节。 ``` --- ## 第八步：发布与分发——三种路径 ### 路径一：本地项目内嵌（最简单） 直接将 `.claude/skills/` 目录提交到 Git 仓库。团队成员 clone 后即可使用。 ```bash git add .claude/skills/db-migration-reviewer/ git commit -m "feat: add db-migration-reviewer skill" ``` **适用场景**：团队内部 Skill，与项目强绑定。 ### 路径二：Plugin Marketplace（推荐） 将 Skill 打包为 Plugin，通过 Marketplace 分发。需要创建 `marketplace.json`： ```json { "name": "db-migration-reviewer", "version": "1.0.0", "description": "数据库迁移SQL安全审查工具", "author": "your-name", "skills": [ { "name": "db-migration-reviewer", "path": "skills/db-migration-reviewer" } ], "repository": "https://github.com/your-name/db-migration-reviewer-plugin" } ``` 目录结构调整为： ``` db-migration-reviewer-plugin/ ├── marketplace.json ├── skills/ │ └── db-migration-reviewer/ │ ├── SKILL.md │ ├── templates/ │ ├── scripts/ │ └── examples/ ├── README.md └── LICENSE ``` 发布到 GitHub 后，其他用户可以安装： ```bash # 从 GitHub 安装 > /plugin install your-name/db-migration-reviewer-plugin # 或从 npm 安装 > /plugin install db-migration-reviewer-plugin@npm ``` ### 路径三：npm 包分发 ```bash # 初始化 npm 包 npm init -y # 修改 package.json 中的 name、version 等字段 # 发布到 npm npm publish ``` 安装方式： ```bash > /plugin install db-migration-reviewer-plugin@npm ``` **适用场景**：公开 Skill，希望覆盖最广的用户群。 --- ## 第九步：高级技巧——Skill 组合与子 Agent 隔离 ### 组合多个 Skill 当一个工作流需要多个 Skill 协作时，在 SKILL.md 中引用其他 Skill： ```markdown ## 执行步骤 ### Step 1: Schema 差异分析 如果项目中有两个版本的 Schema 文件，先使用 `schema-diff` 脚本提取差异。 如果需要深度分析，可以调用 `api-security-reviewer` Skill 审查 Schema 变更对 API 的影响。 ### Step 2: 迁移审查 按照本 Skill 的审查流程执行。 ### Step 3: CI/CD 集成 如果项目使用 GitHub Actions，建议将审查结果输出为 PR Comment。 可以配合 `pr-commenter` Skill 自动完成。 ``` ### 子 Agent 隔离模式 当 `isolation: true` 时，Skill 在子 Agent 中执行。这意味着： ```mermaid sequenceDiagram participant User as 用户 participant Main as 主 Agent participant Sub as 子 Agent(Skill) participant FS as 文件系统 User->>Main: 审查迁移文件 Main->>Main: Discovery层: 匹配 db-migration-reviewer Main->>Sub: 启动隔离子Agent Note over Sub: 加载完整 SKILL.md Sub->>FS: 读取迁移文件 Sub->>FS: 读取审查模板 Sub->>Sub: 执行分析逻辑 Sub->>Main: 返回审查报告 Note over Main: 主上下文保持干净 Main->>User: 展示报告 ``` 子 Agent 的优势： - **上下文隔离**：大量中间数据（如读取的 SQL 内容）不会污染主对话 - **工具权限隔离**：`allowed-tools` 限制了子 Agent 的能力范围 - **并行执行**：多个 Skill 可以并行运行在不同的子 Agent 中 --- ## 实战案例：端到端演练 下面是一个完整的端到端演练，从创建到验证。 ### 准备测试环境 ```bash # 创建测试项目 mkdir migration-demo && cd migration-demo git init # 创建一个危险的迁移文件 mkdir -p db/migrations cat > db/migrations/V202__cleanup.sql << 'EOF' -- 清理旧数据 DROP TABLE user_sessions; DELETE FROM logs; UPDATE orders SET status = 'archived'; ALTER TABLE users DROP COLUMN phone_number; BEGIN; ALTER TABLE products ADD COLUMN search_vector tsvector; CREATE INDEX idx_products_search ON products USING gin(search_vector); ALTER TABLE products ALTER COLUMN search_vector SET NOT NULL; COMMIT; EOF ``` ### 创建 Skill ```bash # 创建目录结构 mkdir -p .claude/skills/db-migration-reviewer/{templates,scripts,examples} # 按第三、四、五步创建所有文件 # （此处省略文件创建过程，使用前面步骤的内容） ``` ### 运行 Skill ```bash claude ``` 在 Claude Code 中输入： ``` 请审查 db/migrations/V202__cleanup.sql 这个迁移文件 ``` ### 预期输出 ``` ### 迁移审查报告 **文件**: db/migrations/V202__cleanup.sql **审查时间**: 2026-05-26 **总体风险**: 严重 #### 发现的问题 | # | 风险等级 | 位置 | 问题描述 | 修复建议 | |---|---------|------|---------|---------| | 1 | ⛔ 严重 | L3 | DROP TABLE user_sessions 无备份方案 | 先重命名为 _deprecated_user_sessions，确认无影响后再删除 | | 2 | ⛔ 严重 | L5 | DELETE FROM logs 无 WHERE 子句 | 添加 WHERE created_at < '2025-01-01' 限制删除范围 | | 3 | ⚠️ 警告 | L7 | UPDATE orders 无 WHERE 子句 | 添加 WHERE 条件，并考虑分批执行 | | 4 | ⛔ 严重 | L9 | DROP COLUMN phone_number 可能被应用引用 | 先检查代码引用，使用安全删除流程 | | 5 | ⚠️ 警告 | L11-15 | 事务中包含 3 条 DDL，存在锁表风险 | 拆分为独立迁移，索引使用 CONCURRENTLY | #### 统计摘要 - DDL 语句: 6 条（高风险: 3） - DML 语句: 2 条（高风险: 2） - 性能建议: 2 条 #### 建议的安全执行顺序 1. V202a: 重命名 user_sessions 表（可逆） 2. V202b: 分批清理 logs 表（带 WHERE 条件） 3. V202c: 分批归档 orders（带 WHERE + LIMIT） 4. V202d: 安全删除 phone_number 列（先确认无引用） 5. V202e: 拆分事务，分别添加列、创建索引、设置 NOT NULL ``` --- ## 调试与排错指南 | 症状 | 可能原因 | 解决方案 | |------|---------|---------| | Skill 从不触发 | description 不匹配用户意图 | 用自然语言测试，调整 description | | Skill 过度触发 | description 太宽泛 | 添加限定词，缩小适用范围 | | 输出格式不稳定 | 缺少输出模板 | 添加完整的 Markdown 模板 | | 遗漏检查项 | 步骤描述不够具体 | 用枚举替代模糊描述 | | 上下文溢出 | Skill 在主 Agent 中执行 | 设置 `isolation: true` | | 工具权限被拒绝 | `allowed-tools` 未声明需要的工具 | 添加所需工具到列表 | | 引用文件找不到 | 路径相对于 SKILL.md 而非项目根 | 使用相对于 Skill 目录的路径 | ### 查看 Skill 加载状态 ```bash # 在 Claude Code 中查看已注册的 Skills > 列出所有可用的 Skills # 查看 Skill 的 Discovery 层信息 > /db-migration-reviewer --info ``` --- ## 完整工作流总结 ```mermaid flowchart TB subgraph 设计阶段 A[明确 Skill 目标] --> B[定义触发条件] B --> C[规划输出格式] end subgraph 开发阶段 D[创建目录结构] --> E[编写 SKILL.md Frontmatter] E --> F[编写 Body 指令] F --> G[创建辅助资源] end subgraph 测试阶段 H[手动触发测试] --> I[编写 Evals 用例] I --> J[运行自动化测试] J --> K{通过率达标?} K -->|否| L[分析失败原因] L --> F K -->|是| M[A/B 对比测试] end subgraph 发布阶段 M --> N{发布方式?} N -->|项目内嵌| O[提交到 Git] N -->|Plugin| P[打包 Marketplace] N -->|npm| Q[发布 npm 包] end C --> D G --> H ``` --- ## 延伸阅读 - [Anthropic 官方 Skills 仓库](https://github.com/anthropics/skills) — 17 个官方示例 Skill 的完整源码，涵盖设计、文档、开发等场景 - [The Complete Guide to Building Skills for Claude (PDF)](https://resources.anthropic.com/hubfs/The-Complete-Guide-to-Building-Skill-for-Claude.pdf) — Anthropic 官方发布的 Skill 构建完整指南 - [Skill authoring best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) — Claude API 文档中的 Skill 编写最佳实践 - [Claude Code Skills Progressive Disclosure](https://marcelcastrobr.github.io/posts/2026-01-29-Skills-Context-Engineering.html) — 渐进式披露架构的深度技术分析 - [Improving skill-creator: Test, measure, and refine Agent Skills](https://claude.com/blog/improving-skill-creator-test-measure-and-refine-agent-skills) — Anthropic 官方的 Evals 驱动 Skill 改进方法论 - [Claude Code Skills Complete Guide](https://duet.so/guides/claude-code-skills-complete-guide) — 社区维护的 2026 年最新 Skills 综合指南 --- ## 训练营适用性评估 | 训练营类型 | 适配度 | 预计教学时长 | 说明 | |-----------|--------|-------------|------| | AI 工具入门营 | ★★★☆☆ | 3 小时 | 可简化为前六步，跳过 Evals 和发布 | | Claude Code 专精营 | ★★★★★ | 6 小时 | 完整覆盖全流程，含实战演练 | | DevOps 自动化营 | ★★★★☆ | 4 小时 | 侧重 CI/CD 集成和批量审查场景 | | 企业 AI 落地营 | ★★★★☆ | 5 小时 | 侧重 Plugin 分发和团队标准化 | | Prompt Engineering 营 | ★★★★☆ | 4 小时 | 侧重指令工程和 Evals 优化 | **教学建议**：将教程分为三个模块——设计+开发（2h）、测试+优化（2h）、发布+高级（2h），每个模块后安排 30 分钟的动手练习。 --- ## 参考来源 1. [Extend Claude with skills - Claude Code Docs](https://code.claude.com/docs/en/skills) — Anthropic 官方 Claude Code Skills 文档，定义了 Skill 的发现、激活、执行三层架构 2. [GitHub - anthropics/skills](https://github.com/anthropics/skills) — Anthropic 官方开源 Skills 仓库，包含 17 个可直接使用的示例 Skill 3. [The Complete Guide to Building Skills for Claude (PDF)](https://resources.anthropic.com/hubfs/The-Complete-Guide-to-Building-Skill-for-Claude.pdf?hsLang=en) — Anthropic 发布的完整 Skill 构建指南，涵盖从规划到发布的全流程 4. [Skill authoring best practices - Claude API Docs](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) — 官方 Skill 编写最佳实践，包含指令工程的具体建议 5. [How to Build Your Own Claude Code Skill - freeCodeCamp](https://www.freecodecamp.org/news/how-to-build-your-own-claude-code-skill) — freeCodeCamp 的 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 等场景全覆盖。