Claude Code Skill设计模式：原子化到编排器实战

graph TD
    A[Skill设计核心问题] --> B[粒度：原子化]
    A --> C[组合：编排器]
    A --> D[边界：契约接口]
    B --> B1[单一职责]
    B --> B2[自包含指令]
    C --> C1[顺序链]
    C --> C2[并行扇出]
    C --> C3[条件分支]
    D --> D1[输入输出契约]
    D --> D2[错误恢复]

mkdir -p .claude/skills/code-formatter

---
name: code-formatter
description: 使用Prettier和ESLint自动格式化指定文件或目录
trigger: 当用户要求格式化代码、修复lint问题、统一代码风格时激活
tools:
  - Bash
  - Read
  - Edit
effort: 3
---

# 代码格式化Skill

## 执行流程

1. 确认目标路径（文件或目录）
2. 检测项目中的格式化配置：
   - `.prettierrc*` 或 `prettier.config.*`
   - `.eslintrc*` 或 `eslint.config.*`
3. 若无配置文件，使用以下默认规则：
   ```json
   {
     "semi": true,
     "singleQuote": true,
     "trailingComma": "es5",
     "printWidth": 100
   }
   ```
4. 执行格式化：
   ```bash
   npx prettier --write "<目标路径>"
   ```
5. 执行lint修复（如ESLint可用）：
   ```bash
   npx eslint --fix "<目标路径>"
   ```
6. 输出格式化报告：修改了哪些文件，修复了哪些问题

## 边界约束

- 只处理格式化，不做代码逻辑修改
- 不安装新的npm包，仅使用项目已有依赖或npx
- 如果格式化导致语法错误，立即回滚并报告

## 输出格式

mkdir -p .claude/skills/code-review-orchestrator

---
name: code-review-orchestrator
description: 编排完整的代码审查流程，串联格式检查、安全扫描、逻辑审查三个阶段
trigger: 当用户提交代码审查请求、创建PR、或要求review代码变更时激活
tools:
  - Task
  - Read
  - Bash
  - Grep
  - Glob
subagents:
  - code-formatter
  - security-scanner
  - logic-reviewer
effort: 5
---

# 代码审查编排器

你是一个代码审查流程的编排器。你不直接执行审查任务，而是协调子Skill完成工作。

## 编排流程

### 阶段一：格式检查
- 委托 `code-formatter` Skill检查目标代码的格式合规性
- 收集格式问题报告
- 如果存在严重格式问题，询问用户是否先修复再继续

### 阶段二：安全扫描
- 委托 `security-scanner` Skill扫描以下风险：
  - SQL注入、XSS、命令注入（OWASP Top 10）
  - 硬编码密钥、凭证泄露
  - 不安全的依赖版本
- 收集安全报告，标记风险等级

### 阶段三：逻辑审查
- 委托 `logic-reviewer` Skill审查：
  - 代码逻辑正确性
  - 边界条件处理
  - 错误处理完整性
  - 性能隐患
- 收集逻辑审查报告

## 输出汇总

将三个阶段的结果汇总为结构化报告：

```markdown
# 代码审查报告

## 📋 概览
- 审查文件：X个
- 发现问题：Y个（严重：A，警告：B，建议：C）

## 🔧 格式问题（阶段一）
[格式化报告摘要]

## 🔒 安全问题（阶段二）
[安全扫描摘要，按风险等级排列]

## 🧠 逻辑问题（阶段三）
[逻辑审查摘要，按严重程度排列]

## ✅ 推荐操作
[按优先级排列的修复建议]

### 3.3 编排器架构流程图

```mermaid
sequenceDiagram
    participant U as 用户
    participant O as 编排器Skill
    participant F as 格式检查
    participant S as 安全扫描
    participant L as 逻辑审查

    U->>O: 请求代码审查
    O->>F: 阶段一：格式检查
    F-->>O: 格式报告
    O->>S: 阶段二：安全扫描
    S-->>O: 安全报告
    O->>L: 阶段三：逻辑审查
    L-->>O: 逻辑报告
    O-->>U: 汇总审查报告

mkdir -p .claude/skills/smart-deploy

---
name: smart-deploy
description: 根据项目类型和目标环境智能选择部署策略
trigger: 当用户要求部署应用、发布到生产/预发环境时激活
tools:
  - Bash
  - Read
  - Glob
  - Grep
effort: 5
---

# 智能部署Skill

## 第一步：识别项目类型

检查项目根目录文件，判断技术栈：

| 检测文件 | 项目类型 | 部署目标候选 |
|----------|----------|-------------|
| `next.config.*` | Next.js | Vercel / Docker |
| `Dockerfile` | 容器化 | AWS ECS / GCP Cloud Run |
| `serverless.yml` | Serverless | AWS Lambda |
| `fly.toml` | Fly.io | Fly.io |
| `vercel.json` | Vercel | Vercel |

## 第二步：确认部署环境

根据用户指定或分支名推断环境：
- `main`/`master` 分支 → 生产环境（production）
- `staging`/`develop` 分支 → 预发环境（staging）
- 其他分支 → 开发环境（preview）

## 第三步：执行部署

### 分支A：Vercel部署（Next.js项目）
```bash
# 检查Vercel CLI
npx vercel --version
# 部署到对应环境
if [环境 = "production"]; then
  npx vercel --prod
else
  npx vercel
fi

# 构建镜像
docker build -t <项目名>:<版本> .
# 推送镜像
docker push <仓库地址>/<项目名>:<版本>
# 更新部署
kubectl set image deployment/<项目名> <项目名>=<仓库地址>/<项目名>:<版本>

npx serverless deploy --stage <环境名>

---

## 五、模式四：渐进披露Skill（Progressive Disclosure）

### 5.1 设计原则

渐进披露是最核心的Skill设计哲学。Skill内容不应一次性全部暴露给Claude，而是按需加载——先给摘要，需要时再展开细节。这能显著减少上下文占用，提高响应质量。

### 5.2 渐进披露的三层结构

```mermaid
graph TB
    L1[第一层：Frontmatter摘要<br/>name + description] --> L2[第二层：Skill主体<br/>核心指令与流程]
    L2 --> L3[第三层：参考资源<br/>脚本/模板/示例]
    L1 -->|"Skill发现阶段"| Claude
    L2 -->|"Skill激活阶段"| Claude
    L3 -->|"执行时按需加载"| Claude

mkdir -p .claude/skills/db-migration

---
name: db-migration
description: 安全执行数据库Schema迁移，支持PostgreSQL/MySQL，含回滚策略
trigger: 当用户提及数据库迁移、schema变更、alter table时激活
tools:
  - Bash
  - Read
  - Edit
effort: 4
---

# 数据库迁移Skill

## 安全检查清单（每次必须执行）

1. **备份确认**：执行前确认是否已有数据库备份
2. **影响评估**：分析迁移SQL影响的表和行数
3. **回滚准备**：为每个迁移步骤生成对应的回滚SQL

## 迁移类型决策树

- 添加列 → 直接执行，风险低
- 修改列类型 → 先添加新列 → 迁移数据 → 删除旧列
- 删除列 → 先标记废弃 → 确认无引用 → 延迟删除
- 重命名表 → 先创建视图别名 → 迁移代码 → 删除视图

## PostgreSQL迁移模板

<details>
<summary>点击展开完整迁移脚本模板</summary>

```sql
-- 迁移：添加用户头像字段
-- 创建时间：2026-05-26
-- 回滚SQL：ALTER TABLE users DROP COLUMN avatar_url;

BEGIN;
  ALTER TABLE users ADD COLUMN avatar_url VARCHAR(512);
  CREATE INDEX idx_users_avatar ON users(avatar_url) WHERE avatar_url IS NOT NULL;
COMMIT;

### 5.4 渐进披露的效果对比

| 指标 | 无渐进披露 | 有渐进披露 |
|------|-----------|-----------|
| 初始上下文消耗 | ~2000 tokens | ~200 tokens |
| 激活时消耗 | ~2000 tokens | ~800 tokens |
| 按需加载 | 无 | ~1200 tokens（仅加载所需部分） |
| 响应延迟 | 较高（上下文冗长） | 较低（指令精准） |

---

## 六、模式五：错误边界Skill（Error Boundary Skill）

### 6.1 设计原则

错误边界Skill将容错逻辑封装在Skill内部，而不是让调用者处理。核心设计：

- **预检（Pre-check）**：执行前验证前置条件
- **降级（Degradation）**：主要方案失败时提供备选方案
- **报告（Reporting）**：结构化输出错误信息

### 6.2 实战：带错误边界的依赖安装Skill

```bash
mkdir -p .claude/skills/safe-install

---
name: safe-install
description: 安全安装npm/pip依赖，含版本锁定、漏洞检查、回滚机制
trigger: 当用户要求安装新的依赖包时激活
tools:
  - Bash
  - Read
  - Edit
effort: 3
---

# 安全依赖安装Skill

## 预检阶段

执行安装前，必须依次验证：

1. **包存在性检查**
   ```bash
   npm view <包名> version
   ```
   若404，建议替代包名并询问用户确认。

2. **许可证兼容性**
   ```bash
   npx license-checker --production | grep <包名>
   ```
   标记GPL类许可证，提示用户风险评估。

3. **包大小评估**
   ```bash
   npm view <包名> dist.unpackedSize
   ```
   若超过5MB，提示用户确认是否必要。

## 安装阶段

### 首选方案：精确版本安装
```bash
# 锁定具体版本，避免语义版本陷阱
npm install <包名>@<具体版本> --save-exact

npm install <包名> --save

# 检查已知漏洞
npm audit
# 验证包可正常导入
node -e "require('<包名>'); console.log('✅ 导入成功')"

# 恢复package-lock.json
git checkout package-lock.json
# 重新安装原始依赖
npm ci

📦 安装报告
─────────────
包名：<name>@<version>
大小：<size>
许可证：<license>
漏洞：<count>个
状态：✅ 安装成功 / ❌ 安装失败
回滚命令：npm uninstall <name>

---

## 七、五大模式的完整Skill体系架构

下面展示如何将五种模式组合成一个完整的开发工作流Skill体系：

```mermaid
graph TB
    subgraph "编排层（Orchestrator）"
        ORC[dev-workflow<br/>开发工作流编排器]
    end

    subgraph "业务层（Conditional + Progressive）"
        DEPLOY[smart-deploy<br/>智能部署]
        REVIEW[code-review-orchestrator<br/>代码审查编排器]
        MIGRATE[db-migration<br/>数据库迁移]
    end

    subgraph "基础层（Atomic + Error Boundary）"
        FMT[code-formatter<br/>格式化]
        SEC[security-scanner<br/>安全扫描]
        INSTALL[safe-install<br/>安全安装]
        LOGIC[logic-reviewer<br/>逻辑审查]
    end

    ORC -->|"开发完成"| REVIEW
    ORC -->|"审查通过"| DEPLOY
    ORC -->|"需要迁移"| MIGRATE

    REVIEW --> FMT
    REVIEW --> SEC
    REVIEW --> LOGIC

    DEPLOY -->|"依赖安装"| INSTALL
    MIGRATE -->|"安全检查"| SEC

    style ORC fill:#6366f1,color:#fff
    style DEPLOY fill:#8b5cf6,color:#fff
    style REVIEW fill:#8b5cf6,color:#fff
    style MIGRATE fill:#8b5cf6,color:#fff
    style FMT fill:#06b6d4,color:#fff
    style SEC fill:#06b6d4,color:#fff
    style INSTALL fill:#06b6d4,color:#fff
    style LOGIC fill:#06b6d4,color:#fff

---
# === 必需字段 ===
name: string              # Skill唯一标识，用于发现和引用
description: string       # 一句话功能描述，出现在Skill列表中

# === 触发控制 ===
trigger: string           # 激活条件描述，告诉Claude何时使用此Skill

# === 工具控制 ===
tools:                    # 限制Skill可使用的工具列表
  - Bash
  - Read
  - Edit
  - Write
  - Glob
  - Grep
  - Task

# === 子Agent委托 ===
subagents:                # 声明此Skill依赖的子Skill
  - skill-name-a
  - skill-name-b

# === 模型控制 ===
model: sonnet | opus | haiku  # 指定Skill使用的模型
effort: 1-5               # 思考努力级别，5为最深入

# === 高级控制 ===
disable-model-invocation: boolean  # 禁止自动调用（用于手动触发）
max_tokens: number        # 限制最大token输出
---

graph LR
    A[创建Skill] --> B{需要限制工具？}
    B -->|是| C[添加 tools 字段]
    B -->|否| D[使用默认全部工具]
    C --> E{需要子Skill？}
    D --> E
    E -->|是| F[添加 subagents 字段]
    E -->|否| G{需要特定模型？}
    F --> G
    G -->|是| H[添加 model 字段]
    G -->|否| I[使用默认模型]
    H --> J[完成配置]
    I --> J

# 创建三个原子Skill
mkdir -p .claude/skills/{lint-checker,type-checker,test-runner}

---
name: lint-checker
description: 执行ESLint检查并输出结构化报告
trigger: 当需要检查代码质量、运行lint时激活
tools: [Bash, Read, Glob, Grep]
effort: 2
---

# Lint检查Skill

## 执行步骤

1. 检测ESLint配置文件位置
2. 对指定路径执行检查：
   ```bash
   npx eslint "<目标路径>" --format json 2>/dev/null
   ```
3. 解析JSON输出，统计错误和警告数量
4. 按文件分组输出结果

## 输出格式

---
name: type-checker
description: 执行TypeScript类型检查并报告类型错误
trigger: 当需要检查类型安全性、运行tsc时激活
tools: [Bash, Read]
effort: 2
---

# 类型检查Skill

## 执行步骤

1. 检测 tsconfig.json 位置
2. 运行类型检查：
   ```bash
   npx tsc --noEmit --pretty 2>&1
   ```
3. 解析输出，按错误码分类
4. 标注可快速修复的问题（如缺失类型注解）

## 输出格式

---
name: test-runner
description: 运行项目测试套件并分析测试结果
trigger: 当需要运行测试、检查测试覆盖率时激活
tools: [Bash, Read, Glob]
effort: 3
---

# 测试运行Skill

## 执行步骤

1. 检测测试框架（Jest / Vitest / Mocha）
2. 运行测试：
   ```bash
   # Jest/Vitest
   npx jest --coverage --json 2>/dev/null
   # 或
   npx vitest run --coverage --reporter=json 2>/dev/null
   ```
3. 解析测试结果
4. 计算覆盖率摘要

## 输出格式

mkdir -p .claude/skills/quality-gate

---
name: quality-gate
description: 编排代码质量门禁，串联lint、类型检查、测试三道关卡
trigger: 当用户要求质量检查、运行CI、提交前检查时激活
tools: [Task, Bash, Read]
subagents:
  - lint-checker
  - type-checker
  - test-runner
effort: 5
---

# 质量门禁编排器

## 编排流程

### 第一关：Lint检查
委托 `lint-checker` Skill执行代码风格检查。
- 如果错误数 > 0：标记为 ❌，但继续下一关
- 收集错误列表

### 第二关：类型检查
委托 `type-checker` Skill执行类型安全检查。
- 如果有类型错误：标记为 ❌，但继续下一关
- 收集错误列表

### 第三关：测试运行
委托 `test-runner` Skill执行测试套件。
- 如果有失败用例：标记为 ❌
- 收集失败详情

## 门禁判定

| 关卡 | 权重 | 通过条件 |
|------|------|---------|
| Lint | 30% | 错误数 = 0 |
| 类型 | 30% | 错误数 = 0 |
| 测试 | 40% | 全部通过 |

### 判定规则
- 三关全部通过 → ✅ 质量门禁通过
- 任一关失败 → ❌ 质量门禁未通过
- 输出修复优先级列表

## 最终输出

```markdown
# 🚪 质量门禁报告

| 关卡 | 状态 | 详情 |
|------|------|------|
| Lint | ✅/❌ | X错误 Y警告 |
| 类型 | ✅/❌ | X错误 |
| 测试 | ✅/❌ | X失败 Y通过 |

**结论：✅ 通过 / ❌ 未通过**

### 🔧 修复优先级
1. [最高优先级修复项]
2. [次高优先级修复项]

### 步骤3：验证完整体系

```bash
# 验证Skill已被发现
claude skills list

# 预期输出应包含：
# quality-gate      - 编排代码质量门禁
# lint-checker      - 执行ESLint检查
# type-checker      - 执行TypeScript类型检查
# test-runner       - 运行测试套件
# code-formatter    - 代码格式化

claude "请对 src/ 目录执行质量门禁检查"

子Skill → 写入临时文件/输出到stdout → 编排器读取

# 方法1：检查Skill发现列表
claude skills list

# 方法2：手动指定Skill
claude --skill code-formatter "格式化 src/"

# 方法3：在trigger字段中使用更具体的关键词
# 原来可能太宽泛的trigger：
#   trigger: 当需要格式化时激活
# 改为更具体的：
#   trigger: 当用户要求格式化代码、修复lint、运行prettier时激活

# ❌ 过于详细的description
description: 这个Skill帮助开发者执行代码格式化，包括JavaScript、TypeScript、CSS、HTML等多种文件类型，使用Prettier和ESLint...

# ✅ 精简的description
description: 使用Prettier和ESLint自动格式化代码