Claude Code Skill全生命周期：从零到发布实战

┌─────────────────────────────────────────────────┐
│  Layer 1: Discovery（发现层）                     │
│  仅加载 name + description                       │
│  决定是否激活此 Skill                             │
│  ~50 tokens / Skill                              │
├─────────────────────────────────────────────────┤
│  Layer 2: Activation（激活层）                    │
│  加载完整 SKILL.md 正文                           │
│  Claude 阅读详细指令和步骤                         │
│  ~500-2000 tokens / Skill                        │
├─────────────────────────────────────────────────┤
│  Layer 3: Execution（执行层）                     │
│  按需加载引用文件、脚本、模板                       │
│  只有真正用到时才读取                              │
│  按需加载，无固定上限                              │
└─────────────────────────────────────────────────┘

.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 # 危险迁移示例

# 进入项目根目录
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

---
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                            # 文件查找
---

你的 Skill 是否需要深度推理？
├── 是（代码审查、架构分析、安全审计）
│   └── model: opus
├── 否，但需要理解中等复杂度的上下文
│   └── model: sonnet        ← 大多数 Skill 的默认选择
└── 简单的格式化或模板生成
    └── model: haiku

---
name: db-migration-reviewer
description: >
  审查数据库迁移SQL脚本的DDL和DML语句，
  检测破坏性操作（DROP/DELETE无WHERE）、
  性能风险（全表扫描、大事务）和数据丢失隐患，
  输出结构化安全审查报告和修复建议。

model: sonnet
effort: high
isolation: true
allowed-tools:
  - Read
  - Grep
  - Bash
  - Glob
---

## 指令概述
（一句话说明这个 Skill 的目的）

## 触发条件
（明确说明何时应该激活此 Skill）

## 执行步骤
（按步骤列出具体操作，每步有明确的输入/输出）

## 约束与边界
（什么不该做，什么情况下应该中止）

## 输出格式
（期望的输出模板）

## 参考文件
（列出 Skill 目录下需要按需加载的文件）

## 指令概述

你是一名数据库安全审查专家。当用户提供或项目中存在数据库迁移脚本时，
你需要对这些脚本进行全面的安全审查，识别潜在的破坏性操作和性能风险。

## 触发条件

在以下情况下激活此 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、缺少回滚脚本

## 约束与边界
- 不要自动修改任何迁移文件
- 不要执行任何 SQL 语句
- 超过 1000 行只审查前 200 行

# 数据库迁移审查清单

## DDL 操作

- [ ] DROP 操作是否有数据备份方案？
- [ ] ALTER TABLE 是否影响正在使用的列？
- [ ] 新增列是否有默认值或允许 NULL？
- [ ] 索引创建是否使用 CONCURRENTLY（PostgreSQL）？
- [ ] 外键约束是否会导致锁表？

## DML 操作

- [ ] DELETE/UPDATE 是否都有 WHERE 条件？
- [ ] WHERE 条件是否使用了索引列？
- [ ] 大批量操作是否分批执行？
- [ ] 是否存在隐式类型转换？

## 事务与锁

- [ ] 单个事务中的 DDL 数量是否超过 3 个？
- [ ] 是否有可能导致长事务？
- [ ] 高峰期执行是否会影响线上服务？

## 回滚方案

- [ ] 是否提供了回滚脚本？
- [ ] 回滚脚本是否经过验证？

#!/bin/bash
# 提取两个 SQL 文件之间的 Schema 差异
# 用法: ./schema-diff.sh <before.sql> <after.sql>

set -euo pipefail

BEFORE="${1:?用法: $0 <before.sql> <after.sql>}"
AFTER="${2:?用法: $0 <before.sql> <after.sql>}"

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

chmod +x .claude/skills/db-migration-reviewer/scripts/schema-diff.sh

-- 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;

# 在项目根目录启动 Claude Code
claude

# 使用斜杠命令触发
> /db-migration-reviewer

# 或用自然语言触发
> 帮我审查一下 examples/dangerous-migration.sql 这个迁移文件

# 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 行"或"文件过大"

> /skill-creator run-evals db-migration-reviewer

# 在 Claude Code 中
> /skill-creator benchmark db-migration-reviewer --compare 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)

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

# 太宽泛
description: 审查 SQL 文件

# 改进后——限定触发范围
description: >
  审查数据库迁移SQL脚本的DDL和DML语句，
  检测破坏性操作、性能风险和数据丢失隐患，
  输出结构化安全审查报告。

# 太模糊
### Step 2: 分析 SQL 语句
检查迁移文件中的所有 SQL 语句。

# 改进后——枚举所有检查项
### Step 2: 分类分析

对每条 SQL 语句逐一检查以下 5 类风险：
1. DROP 操作 → 检查是否有备份方案
2. DELETE/UPDATE → 检查 WHERE 子句是否存在
3. ALTER TABLE → 检查影响范围
4. 大事务 → DDL 数量 > 3 标记为风险
5. 缺少索引 → 全表扫描风险

严格按以下模板输出，不要添加模板中未定义的章节。
如果某个章节没有内容，写"无"而非省略该章节。

git add .claude/skills/db-migration-reviewer/
git commit -m "feat: add db-migration-reviewer skill"

{
  "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 安装
> /plugin install your-name/db-migration-reviewer-plugin

# 或从 npm 安装
> /plugin install db-migration-reviewer-plugin@npm

# 初始化 npm 包
npm init -y
# 修改 package.json 中的 name、version 等字段

# 发布到 npm
npm publish

> /plugin install db-migration-reviewer-plugin@npm

## 执行步骤

### 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 自动完成。

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: 展示报告

# 创建测试项目
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

# 创建目录结构
mkdir -p .claude/skills/db-migration-reviewer/{templates,scripts,examples}

# 按第三、四、五步创建所有文件
# （此处省略文件创建过程，使用前面步骤的内容）

claude

请审查 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

# 在 Claude Code 中查看已注册的 Skills
> 列出所有可用的 Skills

# 查看 Skill 的 Discovery 层信息
> /db-migration-reviewer --info

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