<!-- title: Skill设计六式：原子到流水线架构全实战 -->

# Claude Code Skill设计六式：从原子到流水线架构实战

## 概述

本教程面向已掌握Claude Code基础操作的开发者，系统讲解六种经过验证的Skill设计模式——原子模式、管道模式、路由模式、扇出模式、守卫模式和适配器模式。你将学会如何从零设计可组合、可复用、可维护的Skill架构，并通过一个完整的内容发布流水线项目将六种模式串联实战。适合正在构建团队Skill库、或希望将Claude Code升级为结构化开发平台的工程师。

## 前置条件

- 已安装 Claude Code CLI（`npm install -g @anthropic-ai/claude-code`）
- 了解 SKILL.md 基本格式和 YAML frontmatter
- 熟悉 Bash、Git 基本操作
- 一个用于练习的空目录

---

## 第一章：Skill架构认知——为什么需要设计模式

### 1.1 问题：单体Skill的困境

初学者创建的Skill往往是"万能型"的——一个 SKILL.md 试图涵盖所有场景：

```markdown
---
name: super-dev-assistant
description: 一个万能开发助手
---

你是一个高级开发助手，负责代码审查、测试编写、文档生成、部署发布...
（500行指令）
```

这种单体设计存在三个致命问题：

1. **触发冲突**：description 太宽泛，任何操作都可能误触发
2. **上下文污染**：500行指令全部加载，挤占有效上下文窗口
3. **不可复用**：代码审查逻辑和部署逻辑耦合，无法单独使用

### 1.2 解法：模式化思维

Skill设计模式提供了一套经过验证的"skill-to-skill"协作范式。每种模式解决一类特定的架构问题：

```mermaid
graph TB
    subgraph "六种Skill设计模式"
        A[原子模式<br/>单一职责]
        B[管道模式<br/>顺序链式]
        C[路由模式<br/>条件分发]
        D[扇出模式<br/>并行执行]
        E[守卫模式<br/>安全校验]
        F[适配器模式<br/>平台桥接]
    end

    A -->|组合| B
    A -->|组合| C
    B -->|需要| E
    C -->|触发| D
    D -->|输出| F
```

### 1.3 SKILL.md Frontmatter关键字段速查

在深入每种模式前，先掌握影响Skill行为的核心字段：

| 字段 | 类型 | 作用 | 使用场景 |
|------|------|------|----------|
| `name` | string | Skill唯一标识符 | 所有Skill必须 |
| `description` | string | 触发匹配依据 | 精确描述触发范围 |
| `triggers` | string | 激活关键词 | 缩小误触发范围 |
| `dependencies` | list | 前置Skill依赖 | 组合模式中声明依赖 |
| `tools` | list | 允许使用的工具集 | 限制Skill权限 |
| ` globs` | list | 文件匹配模式 | 限定作用文件范围 |

**关键原则**：`description` 决定了Claude Code何时激活你的Skill。写得越精确，误触发率越低。

---

## 第二章：模式一——原子Skill（Atomic Pattern）

### 2.1 模式定义

**核心思想**：一个Skill只做一件事，做好一件事。

**适用场景**：代码审查、提交信息生成、单文件重构、单一格式转换。

### 2.2 实战：创建原子Skill

创建目录结构：

```bash
mkdir -p .claude/skills/commit-msg-gen
```

编写 `.claude/skills/commit-msg-gen/SKILL.md`：

```markdown
---
name: commit-msg-gen
description: 根据暂存区变更生成符合Conventional Commits规范的提交信息
triggers:
  - /commit-msg
  - 生成提交信息
  - commit message
---

# 提交信息生成器

## 触发条件
当用户请求生成提交信息时激活此Skill。

## 工作流程

1. **分析暂存区**
   运行 `git diff --cached --stat` 获取变更概览。
   运行 `git diff --cached` 获取详细差异。

2. **推断变更类型**
   根据文件路径和diff内容判断类型：
   - `feat:` 新功能（新增文件、新API端点）
   - `fix:` 缺陷修复（修改bug相关代码）
   - `refactor:` 重构（无功能变化的代码调整）
   - `docs:` 文档变更（*.md文件）
   - `test:` 测试（test/目录下文件）
   - `chore:` 构建/工具变更（配置文件、CI）

3. **生成提交信息**
   格式：
   ```
   <type>(<scope>): <简明描述>

   <可选的详细说明>
   ```

4. **输出**
   直接输出生成的提交信息文本，不自动执行git commit。

## 约束
- 只生成提交信息，不执行提交操作
- 描述行不超过72字符
- 不猜测用户意图，只基于diff内容推断
```

### 2.3 设计要点

**为什么它是原子的**：
- 单一输入：git diff
- 单一输出：提交信息文本
- 无副作用：不修改任何文件，不执行任何git操作
- 独立可用：不依赖其他Skill

**frontmatter精要**：`triggers` 字段用列表限定触发词，避免在普通对话中被激活。`description` 精确到"根据暂存区变更生成提交信息"而非"帮助提交代码"。

---

## 第三章：模式二——管道Skill（Pipeline Pattern）

### 3.1 模式定义

**核心思想**：多个原子Skill按固定顺序串联，前一个的输出是后一个的输入。

```mermaid
graph LR
    A[Skill A<br/>数据采集] -->|输出| B[Skill B<br/>内容生成]
    B -->|输出| C[Skill C<br/>格式校验]
    C -->|输出| D[Skill D<br/>发布]
```

**适用场景**：CI/CD流水线、内容发布工作流、多步代码审查。

### 3.2 实战：创建管道编排Skill

创建目录结构：

```bash
mkdir -p .claude/skills/blog-pipeline
```

编写 `.claude/skills/blog-pipeline/SKILL.md`：

```markdown
---
name: blog-pipeline
description: 端到端博客文章发布流水线，从选题研究到最终发布
triggers:
  - /blog-pipeline
  - 发布博客
  - 博客流水线
dependencies:
  - deep-research
  - content-creator
  - markdown-to-image
---

# 博客发布流水线

## 工作流程

此Skill协调以下步骤的顺序执行：

### Step 1: 选题研究（调用 deep-research）
使用TodoWrite记录任务：`[pending] 选题研究`

```
任务：对指定主题进行深度调研
输入：用户提供的主题关键词
输出：调研报告（Markdown格式，包含要点、数据、引用来源）
```

标记任务完成：`[completed] 选题研究`

### Step 2: 内容创作（调用 content-creator）
使用TodoWrite记录任务：`[in_progress] 内容创作`

```
任务：基于调研报告撰写博客文章
输入：Step 1 的调研报告
要求：
  - 3000字以上
  - 包含代码示例
  - 包含 Mermaid 图表
输出：完整博客文章（Markdown格式）
```

标记任务完成：`[completed] 内容创作`

### Step 3: 封面图生成（调用 markdown-to-image）
使用TodoWrite记录任务：`[in_progress] 封面图生成`

```
任务：为文章生成封面图
输入：文章标题和核心概念
输出：封面图PNG文件
```

### Step 4: 最终校验
使用TodoWrite记录任务：`[in_progress] 最终校验`

检查清单：
- [ ] 文章字数 >= 3000
- [ ] 所有代码块语法高亮正确
- [ ] Mermaid图表可渲染
- [ ] 封面图已生成
- [ ] 参考来源已列出

## 错误处理
任何步骤失败时，在TodoWrite中标记该步骤为pending，并提示用户决定：
1. 重试当前步骤
2. 跳过当前步骤
3. 终止整个流水线
```

### 3.3 管道模式的设计关键

**显式依赖声明**：`dependencies` 字段列出前置Skill，Claude Code会在激活时确保这些Skill可用。

**TodoWrite驱动**：每一步都通过TodoWrite记录状态，这是管道模式的"状态机"。用户可以实时看到进度。

**错误传播策略**：管道中某一步失败不应静默跳过，而应暴露给用户决策。

---

## 第四章：模式三——路由Skill（Router Pattern）

### 4.1 模式定义

**核心思想**：根据输入内容动态选择不同的处理Skill，类似路由器的分发逻辑。

```mermaid
graph TD
    R[路由Skill<br/>分析输入] -->|代码变更| A[代码审查Skill]
    R -->|文档变更| B[文档审查Skill]
    R -->|配置变更| C[安全审查Skill]
    R -->|测试变更| D[测试审查Skill]
```

**适用场景**：智能代码审查、多语言项目处理、多平台内容分发。

### 4.2 实战：创建路由Skill

```bash
mkdir -p .claude/skills/smart-reviewer
```

编写 `.claude/skills/smart-reviewer/SKILL.md`：

```markdown
---
name: smart-reviewer
description: 智能代码审查路由器，根据变更类型自动选择审查策略
triggers:
  - /review
  - 审查代码
  - code review
---

# 智能代码审查路由器

## 路由逻辑

当用户请求代码审查时，按以下规则分发：

### 路由规则表

| 变更特征 | 目标策略 | 说明 |
|----------|----------|------|
| `*.py` 文件变更 | Python审查模式 | PEP8、类型注解、docstring |
| `*.ts/*.tsx` 文件变更 | TypeScript审查模式 | 类型安全、React最佳实践 |
| `*.sql` 文件变更 | 数据库审查模式 | SQL注入检测、索引优化 |
| `docker-compose*.yml` | 基础设施审查模式 | 安全基线、资源限制 |
| `.env*` 或 `*secret*` | 安全紧急审查模式 | 凭据泄露检测 |
| 混合变更 | 多策略并行 | 识别所有变更类型，分别审查 |

### 执行流程

1. 运行 `git diff --name-only` 获取变更文件列表
2. 根据文件扩展名和路径匹配路由规则
3. 对每种匹配的类型，应用对应的审查清单
4. 汇总所有审查结果，按严重程度排序输出

### 输出格式

```markdown
## 审查结果

### 🔴 严重 (必须修复)
- [文件:行号] 问题描述

### 🟡 建议 (推荐修复)
- [文件:行号] 改进建议

### 🟢 良好 (值得肯定)
- 良好实践说明
```

## 约束
- 每次审查最多输出20条发现
- 安全问题始终排在最前面
- 不审查自动生成的文件（node_modules/、dist/、build/）
```

### 4.3 路由模式的精髓

路由模式的核心是**规则表**——一个清晰的映射关系，让Claude Code能根据输入特征做出确定性判断。这比"AI自行判断"更可靠，因为规则是显式声明的。

**设计技巧**：路由规则要覆盖所有可能的输入类型，最后一条规则应该是"默认路由"（如上例中的"混合变更"），避免出现无法路由的情况。

---

## 第五章：模式四——扇出Skill（Fan-out Pattern）

### 5.1 模式定义

**核心思想**：将一个任务拆分为多个独立子任务，并行分发给多个Subagent执行。

```mermaid
graph TD
    O[编排Skill] -->|子任务1| A1[Agent 1<br/>前端测试]
    O -->|子任务2| A2[Agent 2<br/>后端测试]
    O -->|子任务3| A3[Agent 3<br/>集成测试]
    O -->|子任务4| A4[Agent 4<br/>安全扫描]
    A1 -->|结果| M[结果聚合]
    A2 -->|结果| M
    A3 -->|结果| M
    A4 -->|结果| M
```

**适用场景**：全栈测试、多环境部署、批量文件处理。

### 5.2 实战：创建扇出Skill

```bash
mkdir -p .claude/skills/parallel-test-runner
```

编写 `.claude/skills/parallel-test-runner/SKILL.md`：

```markdown
---
name: parallel-test-runner
description: 并行测试运行器，同时启动多个独立测试任务
triggers:
  - /test-all
  - 运行全部测试
  - parallel test
---

# 并行测试运行器

## 执行策略

当收到测试请求时，使用 Task 工具并行启动以下子代理：

### 扇出配置

```javascript
// 伪代码展示扇出逻辑
const tasks = [
  {
    subagent_type: "general-purpose",
    description: "前端单元测试",
    prompt: "运行前端测试套件：cd frontend && npm test。收集所有测试结果，输出通过/失败计数。"
  },
  {
    subagent_type: "general-purpose",
    description: "后端API测试",
    prompt: "运行后端测试套件：cd backend && pytest --tb=short。收集所有测试结果，输出通过/失败计数。"
  },
  {
    subagent_type: "general-purpose",
    description: "集成测试",
    prompt: "运行集成测试：docker compose up -d test-db && npm run test:integration。收集所有测试结果。"
  },
  {
    subagent_type: "general-purpose",
    description: "Lint和类型检查",
    prompt: "运行代码质量检查：npm run lint && npm run typecheck。报告所有警告和错误。"
  }
];
// 所有Task工具调用在同一消息中并行发出
```

### 结果聚合

所有子代理完成后，汇总结果：

| 测试类型 | 通过 | 失败 | 跳过 | 耗时 |
|----------|------|------|------|------|
| 前端单元 | ? | ? | ? | ?s |
| 后端API | ? | ? | ? | ?s |
| 集成测试 | ? | ? | ? | ?s |
| Lint | ? | ? | ? | ?s |
| **总计** | **?** | **?** | **?** | **?s** |

### 失败处理
- 任何测试失败时，输出失败测试的详细信息
- 建议修复方向，但不自动修改代码

## 关键约束
- 使用 `run_in_background: true` 让所有Task并行执行
- 每个子代理设置 `max_turns: 10` 防止失控
- 总超时不超过300秒
```

### 5.3 扇出模式的实现要点

扇出模式在Claude Code中的实现依赖 **Task工具的并行调用**。关键技巧：

1. **在同一消息中发起多个Task调用**——这确保了真正的并行执行
2. **每个子代理设置 `max_turns`**——防止单个任务无限循环
3. **使用 `run_in_background: true`**——让主线程不被阻塞
4. **显式定义聚合格式**——子代理的输出格式必须统一，才能正确聚合

---

## 第六章：模式五——守卫Skill（Guard Pattern）

### 6.1 模式定义

**核心思想**：在其他Skill执行前/后执行校验逻辑，充当安全闸门。

```mermaid
sequenceDiagram
    participant U as 用户请求
    participant G as 守卫Skill
    participant T as 目标Skill
    
    U->>G: 请求执行操作
    G->>G: 前置校验
    alt 校验通过
        G->>T: 放行，执行操作
        T->>G: 返回结果
        G->>G: 后置校验
        G->>U: 返回最终结果
    else 校验失败
        G->>U: 返回错误原因
    end
```

**适用场景**：部署前的安全检查、代码提交前的合规性验证、文件操作前的权限确认。

### 6.2 实战：创建守卫Skill

```bash
mkdir -p .claude/skills/deploy-guard
```

编写 `.claude/skills/deploy-guard/SKILL.md`：

```markdown
---
name: deploy-guard
description: 部署安全守卫，在执行部署前执行全面的安全合规检查
triggers:
  - /deploy
  - 部署
  - deploy
---

# 部署安全守卫

## 前置检查清单

在任何部署操作之前，必须按顺序执行以下检查：

### 第一关：代码状态检查
```bash
# 检查是否有未提交的变更
git status --porcelain
# 检查当前分支
git branch --show-current
# 检查是否与远程同步
git fetch && git status -uno
```

**失败条件**：
- 存在未提交的变更 → 阻止：请先提交或暂存所有变更
- 当前分支不是 main/master 且未指定 `--branch` → 警告
- 远程有新提交 → 阻止：请先拉取远程变更

### 第二关：安全扫描
```bash
# 检查环境变量文件
find . -name ".env*" -not -path "./.git/*" -not -name ".env.example"
# 检查硬编码的密钥
grep -rn "sk-\|api_key\|secret\|password" --include="*.ts" --include="*.py" --include="*.js" .
# 检查敏感文件是否在.gitignore中
cat .gitignore | grep -E "\.env|credentials|secret"
```

**失败条件**：
- .env文件存在且不在.gitignore中 → 阻止：环境变量文件可能被提交
- 发现硬编码密钥 → 阻止：检测到可能的凭据泄露
- .gitignore缺少必要条目 → 警告

### 第三关：测试验证
```bash
npm test 2>&1 | tail -5
```

**失败条件**：
- 测试失败 → 阻止：所有测试必须通过
- 测试覆盖率低于阈值 → 警告（不阻止）

### 第四关：构建验证
```bash
npm run build 2>&1 | tail -5
```

**失败条件**：
- 构建失败 → 阻止
- 构建警告超过10个 → 警告

## 结果报告

```
🛡️ 部署守卫报告
================
✅ 代码状态：[通过/失败] - 详情
✅ 安全扫描：[通过/失败] - 详情
✅ 测试验证：[通过/失败] - 详情
✅ 构建验证：[通过/失败] - 详情
================
最终决策：[允许部署 / 阻止部署]
```

## 约束
- 四关全部通过才允许部署
- 任何一关"阻止"级失败，立即停止后续检查
- 守卫只报告结果，不执行实际部署
```

### 6.3 守卫模式的分层设计

守卫模式的精髓在于**分级阻断**：

- **阻止级（Block）**：绝对不能跳过，如凭据泄露检测
- **警告级（Warn）**：提示风险但允许继续，如覆盖率不足
- **信息级（Info）**：纯通知，如构建警告数量

这种分层让守卫既严格又灵活，不至于因为小问题完全卡死流水线。

---

## 第七章：模式六——适配器Skill（Adapter Pattern）

### 7.1 模式定义

**核心思想**：将Claude Code的标准输出转换为特定平台或工具期望的格式。

**适用场景**：生成不同平台的文档、适配多种CI系统的配置、跨平台内容发布。

### 7.2 实战：创建适配器Skill

```bash
mkdir -p .claude/skills/notion-adapter
```

编写 `.claude/skills/notion-adapter/SKILL.md`：

```markdown
---
name: notion-adapter
description: 将Markdown文档转换为Notion API兼容的块格式
triggers:
  - /to-notion
  - 发布到Notion
  - notion adapter
dependencies:
  - markdown-to-image
---

# Notion内容适配器

## 转换规则

将标准Markdown转换为Notion API的Block格式：

| Markdown元素 | Notion Block类型 | 转换规则 |
|-------------|------------------|----------|
| `# 标题` | `heading_1` | 直接映射 |
| `## 标题` | `heading_2` | 直接映射 |
| `### 标题` | `heading_3` | 直接映射 |
| `` `code` `` | `rich_text` + code annotation | 行内代码 |
| ` ```code block``` ` | `code` | 需指定language |
| `> 引用` | `quote` | 直接映射 |
| `- 列表` | `bulleted_list_item` | 支持嵌套 |
| `1. 列表` | `numbered_list_item` | 支持嵌套 |
| `[link](url)` | `rich_text` + href | 保留链接 |
| `![img](url)` | `image` | 需上传或使用外部URL |
| `---` | `divider` | 直接映射 |
| `| 表格 |` | Notion API table block | 逐行转换 |
| Mermaid代码块 | 截图上传 | 先渲染为PNG再上传 |

## 执行步骤

1. 读取源Markdown文件
2. 逐行解析，按转换规则映射为Notion Block对象
3. 处理特殊情况：
   - Mermaid图表：调用 markdown-to-image 渲染为PNG
   - 内嵌图片：验证URL可达性
   - 表格：转换Notion table_block格式
4. 构建完整的Notion API请求体
5. 通过MCP Notion工具或直接API调用发布
6. 输出发布后的页面URL

## 输出验证
发布后验证：
- 页面标题正确
- 所有代码块保留语法高亮
- 图片正常显示
- 链接可点击

## 约束
- Notion API单次请求最多100个Block
- 超过100个Block时分批发送
- 图片大小不超过5MB
```

### 7.3 适配器模式的价值

适配器模式解决的核心问题是**格式异构性**。当你的Skill需要对接多种外部平台时，不要在核心逻辑中硬编码目标格式，而是创建独立的适配器Skill：

```
核心Skill → 适配器A → 平台A
           → 适配器B → 平台B
           → 适配器C → 平台C
```

这样新增平台支持只需添加新适配器，核心逻辑完全不动。

---

## 第八章：综合实战——六模式合一的内容发布平台

### 8.1 架构设计

我们将构建一个完整的内容发布平台Skill，综合运用全部六种模式：

```mermaid
graph TB
    subgraph "内容发布平台"
        CLI[用户输入主题] --> ROUTER[路由模式<br/>判断内容类型]

        ROUTER -->|技术博客| RESEARCH[原子模式<br/>深度调研]
        ROUTER -->|教程| OUTLINE[原子模式<br/>大纲生成]
        ROUTER -->|新闻| DIGEST[原子模式<br/>新闻摘要]

        RESEARCH --> WRITER[原子模式<br/>内容创作]
        OUTLINE --> WRITER
        DIGEST --> WRITER

        WRITER --> GUARD[守卫模式<br/>质量检查]

        GUARD -->|通过| FANOUT[扇出模式<br/>多平台适配]
        GUARD -->|失败| WRITER

        FANOUT --> ADAPTER_N[适配器模式<br/>Notion]
        FANOUT --> ADAPTER_M[适配器模式<br/>Markdown]
        FANOUT --> ADAPTER_W[适配器模式<br/>微信公众号]
    end
```

### 8.2 编排Skill实现

```bash
mkdir -p .claude/skills/content-platform
```

编写 `.claude/skills/content-platform/SKILL.md`：

```markdown
---
name: content-platform
description: 全自动化内容发布平台，从选题到多平台发布一站式完成
triggers:
  - /publish
  - 内容发布
  - content platform
dependencies:
  - smart-reviewer
  - deploy-guard
  - notion-adapter
---

# 内容发布平台

## 系统架构

本Skill是内容发布平台的编排层，协调六个子模块完成端到端发布流程。

## 完整工作流

### Phase 1: 路由分析
接收用户输入的主题和内容类型。根据类型选择生成策略：
- `tech` → 技术深度调研路线
- `tutorial` → 教程结构化路线
- `news` → 新闻聚合路线
- 未指定 → 自动判断

使用TodoWrite创建任务列表：
```
[pending] 路由分析
[pending] 内容调研
[pending] 大纲生成
[pending] 内容创作
[pending] 质量守卫
[pending] 多平台适配
[pending] 发布确认
```

### Phase 2: 内容生成（管道模式）

按顺序执行调研 → 大纲 → 创作：

**调研步骤**：
使用Task工具（subagent_type: general-purpose）执行调研。
输入：主题关键词
输出：调研笔记（含数据点、引用来源）

**大纲步骤**：
基于调研结果生成结构化大纲，包含：
- 每节的要点
- 代码示例位置标记
- 图表插入位置

**创作步骤**：
根据大纲生成完整内容：
- 技术博客：3000字以上，含代码和图表
- 教程：分步骤，每步有操作说明和预期结果
- 新闻摘要：500-800字，多源对比

### Phase 3: 质量守卫

执行三重校验：
1. **格式守卫**：Markdown语法正确性、代码块闭合
2. **内容守卫**：字数达标、无占位符、引用来源完整
3. **安全守卫**：无敏感信息泄露、URL可达

任何守卫不通过 → 返回Phase 2修改

### Phase 4: 多平台扇出

守卫通过后，并行执行平台适配：

同时启动3个Task子代理：
- Task 1: Notion适配（notion-adapter）
- Task 2: 纯Markdown输出（格式化本地文件）
- Task 3: 微信公众号适配（HTML转换）

### Phase 5: 发布确认

汇总所有平台输出：
```
📊 发布报告
===========
✅ Notion: [URL]
✅ 本地文件: [路径]
✅ 微信公众号: [预览链接]

总耗时: Xs
内容字数: X
```

等待用户确认后执行最终发布。

## 错误恢复
- Phase 2失败：记录失败步骤，允许用户选择重试或跳过
- Phase 3失败：自动返回Phase 2并附上修改建议
- Phase 4失败：成功的平台继续发布，失败的重试一次
- Phase 5失败：保留所有本地副本，提示手动发布
```

### 8.3 验证Skill系统

创建完所有Skill后，验证目录结构：

```bash
# 预期目录结构
.claude/skills/
├── commit-msg-gen/          # 原子模式
│   └── SKILL.md
├── blog-pipeline/           # 管道模式
│   └── SKILL.md
├── smart-reviewer/          # 路由模式
│   └── SKILL.md
├── parallel-test-runner/    # 扇出模式
│   └── SKILL.md
├── deploy-guard/            # 守卫模式
│   └── SKILL.md
├── notion-adapter/          # 适配器模式
│   └── SKILL.md
└── content-platform/        # 编排层
    └── SKILL.md
```

测试命令：

```bash
# 测试原子Skill
claude "/commit-msg"

# 测试路由Skill
claude "/review"

# 测试完整流水线
claude "/publish 写一篇关于Rust异步编程的技术博客"
```

---

## 第九章：模式选择决策树

当你面对一个新的Skill需求时，用以下决策树选择合适的模式：

```mermaid
graph TD
    START[新Skill需求] --> Q1{是否只做一件事?}
    Q1 -->|是| ATOMIC[原子模式]
    Q1 -->|否| Q2{步骤是否固定?}

    Q2 -->|是,按顺序| Q3{是否需要校验?}
    Q2 -->|否| Q4{需要选择分支吗?}

    Q3 -->|是| GUARD[守卫模式 + 管道模式]
    Q3 -->|否| PIPELINE[管道模式]

    Q4 -->|是| ROUTER[路由模式]
    Q4 -->|否| Q5{是否并行处理?}

    Q5 -->|是| FANOUT[扇出模式]
    Q5 -->|否| Q6{是否格式转换?}

    Q6 -->|是| ADAPTER[适配器模式]
    Q6 -->|否| COMPOSITE[组合使用多种模式]
```

### 选择速查表

| 我想要... | 选择模式 | 组合建议 |
|-----------|----------|----------|
| 生成一段代码/文本 | 原子 | 单独使用 |
| 自动完成多步骤工作流 | 管道 | 管道中的每步可以是原子 |
| 根据输入类型走不同路径 | 路由 | 路由目标可以是管道或原子 |
| 同时做几件不相关的事 | 扇出 | 扇出的每个分支可以是任意模式 |
| 在操作前后做安全检查 | 守卫 | 守卫包装其他任何模式 |
| 输出要适配多个目标平台 | 适配器 | 适配器通常跟在扇出后面 |

---

## 第十章：Skill设计七条黄金法则

### 法则一：Description即契约

`description` 不是装饰，它是Skill的"对外契约"。写得模糊，误触发率飙升。

```yaml
# ❌ 坏：太宽泛
description: 帮助处理代码

# ✅ 好：精确到触发场景
description: 分析Python函数的执行时间复杂度并生成Big-O报告
```

### 法则二：Triggers缩窄靶心

`triggers` 是第二道防线。用户说"帮我review一下"应该触发代码审查Skill，而不是测试Skill。

```yaml
triggers:
  - /review          # 斜杠命令精确触发
  - 审查代码          # 自然语言触发
  - code review       # 英文触发
```

### 法则三：原子优先

能用原子模式解决的，不要用管道。每增加一层编排，就增加一分复杂度和出错概率。

### 法则四：显式优于隐式

不要让Claude Code"猜测"下一步。在Skill中用明确的编号步骤和条件分支代替模糊的"视情况处理"。

### 法则五：错误是特性

每个Skill都应该有"错误处理"章节，定义：
- 什么算失败
- 失败后做什么
- 如何通知用户

### 法则六：可观测性

关键操作要有日志输出。使用TodoWrite让用户实时看到进度，而不是面对一个"黑箱"。

### 法则七：测试你的Skill

写完Skill后，用三种方式测试：
1. **精确触发测试**：使用 `triggers` 中的关键词，确认能正确激活
2. **边界测试**：输入不完整或异常的数据，确认错误处理生效
3. **冲突测试**：同时存在多个Skill时，确认不会误触发

---

## 第十一章：进阶技巧与常见陷阱

### 11.1 Skill之间的数据传递

Skill之间不共享内存。数据传递的唯一方式是**文件系统**——前一个Skill将结果写入文件，后一个Skill读取该文件。

```markdown
<!-- 在管道Skill中约定中间文件路径 -->
## 数据传递规范
- 调研结果保存到: `.claude/cache/research-output.md`
- 大纲保存到: `.claude/cache/outline.md`
- 最终内容保存到: `.claude/cache/content.md`
```

### 11.2 避免循环依赖

Skill A 依赖 Skill B，Skill B 又依赖 Skill A → 无限循环。

```mermaid
graph LR
    A[Skill A] -->|依赖| B[Skill B]
    B -->|依赖| A
    style A fill:#f66
    style B fill:#f66
```

**解决方案**：将共享逻辑提取为独立的原子Skill C，让A和B都依赖C而非彼此。

### 11.3 控制Skill的"权限"

通过限制Skill可使用的工具集，实现最小权限原则：

```yaml
# 只允许文件读取，禁止写入
tools:
  - Read
  - Glob
  - Grep
```

这可以防止一个审查Skill意外修改了代码——它只能读，不能写。

### 11.4 常见陷阱一览

| 陷阱 | 表现 | 解决方案 |
|------|------|----------|
| Description太宽泛 | 频繁误触发 | 精确描述触发场景 |
| Triggers缺失 | 只靠description匹配 | 添加明确的触发词列表 |
| 循环依赖 | Skill互相调用 | 提取共享逻辑为独立Skill |
| 无错误处理 | 失败时静默 | 添加错误处理章节 |
| 过度编排 | 简单任务用了复杂模式 | 优先使用原子模式 |
| 文件路径硬编码 | 跨项目不可用 | 使用相对路径和变量 |

---

## 延伸阅读

- [Anthropic官方Skills仓库](https://github.com/anthropics/skills) — Anthropic开源的17个高质量Skill，是学习Skill写作的最佳参考
- [Claude Code官方Skills文档](https://code.claude.com/docs/en/skills) — 最权威的SKILL.md格式说明和字段参考
- [Skill Composition Chapter - Claude Code Handbook](https://joeyyu23.github.io/claude-code-handbook/en/book2-advanced/03-skill-composition) — 深入讲解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构建完整指南
- [Claude Code Skill Frontmatter详解](https://allahabadi.dev/blogs/ai/claude-code-skills-frontmatter-complete-guide/) — 每个YAML字段的详细解释和使用场景

## 训练营适用性评估

| 维度 | 评估 |
|------|------|
| 适合训练营类型 | 进阶开发者训练营、AI工具链训练营、DevOps自动化训练营 |
| 预计教学时长 | 6-8小时（含实操） |
| 学员基础要求 | 已掌握Claude Code基本操作，理解YAML格式 |
| 实操难度 | 中等偏高（需理解六种模式的组合使用） |
| 最佳教学顺序 | 先讲原子模式和管道模式（基础），再讲路由和扇出（进阶），最后讲守卫和适配器（高级） |
| 推荐分组方式 | 2-3人一组，每组完成一种模式的Skill，最后合流完成编排层 |

## 参考来源

1. [Extend Claude with skills - Claude Code Docs](https://code.claude.com/docs/en/skills) — Anthropic官方Skills创建和管理文档，涵盖SKILL.md格式、自定义命令和分享机制
2. [anthropics/skills - GitHub](https://github.com/anthropics/skills) — Anthropic官方开源Skill仓库，包含17个生产级Skill的完整实现
3. [SKILL.md Format Specification - DeepWiki](https://deepwiki.com/anthropics/skills/2.2-skill.md-format-specification) — SKILL.md格式的完整规范文档，涵盖所有YAML frontmatter字段
4. [Skill Composition - Claude Code Handbook](https://joeyyu23.github.io/claude-code-handbook/en/book2-advanced/03-skill-composition) — 深入解析Skill组合模式和架构设计
5. [Claude Code Skills Complete Guide - Duet.so](https://duet.so/guides/claude-code-skills-complete-guide) — 2026年最全面的Skill开发指南，涵盖SKILL.md、MCP、Subagents和团队协作

> [!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 等场景全覆盖。

![51学通信知识星球海报-扫码加入](https://wiki.500nian.com/images/zhixingqiu_qrcode.png)