<!-- title: Skill与Subagent联合编排实战 -->

# 概述

在Claude Code的扩展体系中，Skill和Subagent是两个核心机制。大多数开发者只熟悉其中之一——要么写过简单的SKILL.md，要么配置过基本的自定义命令。但当我们将两者结合，利用Skill的动态上下文注入（`!`command``语法）与Subagent的隔离执行能力进行联合编排时，就能构建出远超单一功能的自动化工作流。

本文将从架构层面剖析Skill与Subagent的协作关系，通过一个完整的实战案例——构建「智能PR审查工作流」——演示如何将动态数据采集、多Agent并行分析、结果聚合与报告生成串联为一个端到端的自动化流程。这不是一篇入门教程，而是一次深入Claude Code高级编排模式的实战探索。

```mermaid
graph TB
    A[用户调用 /pr-review] --> B[Skill: pr-review]
    B --> C{动态上下文注入}
    C --> C1["!`gh pr diff`"]
    C --> C2["!`gh pr view --comments`"]
    C --> C3["!`gh pr diff --name-only`"]
    C1 & C2 & C3 --> D[渲染后的完整Skill内容]
    D --> E{context: fork}
    E --> F[Subagent: Explore]
    F --> F1[Glob搜索相关文件]
    F --> F2[Grep查找模式匹配]
    F --> F3[Read读取关键代码]
    F1 & F2 & F3 --> G[审查报告返回主会话]

    style A fill:#4A90D9,color:#fff
    style B fill:#7B68EE,color:#fff
    style C fill:#FF6B6B,color:#fff
    style E fill:#FFD93D,color:#333
    style F fill:#6BCB77,color:#fff
    style G fill:#4D96FF,color:#fff
```

# 前置知识

在深入本文之前，你需要具备以下基础：

**必备条件：**
- Claude Code CLI已安装并可正常使用（v2.1.63+）
- 理解SKILL.md的基本结构（frontmatter + markdown指令）
- 了解Claude Code的权限系统基础
- 熟悉Git和GitHub CLI（`gh`命令）的基本操作

**建议了解：**
- Subagent的基本概念（独立上下文窗口、工具限制）
- CLAUDE.md的配置方式
- MCP协议的基础知识

**环境准备：**
- 一个包含Git仓库的项目目录
- 已安装并认证的GitHub CLI（`gh auth login`）
- 文本编辑器（用于创建Skill文件）

# 正文

## 1. 理解Skill与Subagent的协作架构

### 1.1 两种扩展机制的本质差异

Skill和Subagent虽然都是Claude Code的扩展手段，但它们的定位截然不同：

**Skill** 是「知识注入」——它将指令、模板、上下文加载到当前会话中，Claude在主会话上下文中执行这些指令。Skill的内容一旦加载，就会在后续所有轮次中保留。

**Subagent** 是「任务隔离」——它在一个独立的上下文窗口中启动，拥有自己的系统提示词、工具集和权限。Subagent完成后只将结果摘要返回主会话，所有中间过程（文件搜索、代码阅读、命令输出）都留在隔离的上下文中，不会污染主会话。

```mermaid
graph LR
    subgraph 主会话上下文
        A[CLAUDE.md] --> B[Skill内容]
        B --> C[Claude主线程]
    end

    subgraph Subagent隔离上下文
        D[自定义系统提示词] --> E[受限工具集]
        E --> F[独立Agent执行]
    end

    C -->|"Agent工具委托"| D
    F -->|"结果摘要返回"| C

    style C fill:#4A90D9,color:#fff
    style F fill:#6BCB77,color:#fff
```

关键区别在于：Skill的内容会持续占用主会话的token预算，而Subagent的工作过程完全隔离。这意味着当你需要处理大量中间数据（如完整的diff、搜索结果、日志输出）时，Subagent是更好的选择。

### 1.2 context:fork——连接Skill与Subagent的桥梁

Claude Code提供了一个关键特性 `context: fork`，它让Skill可以在Subagent中执行。当Skill设置了 `context: fork` 时：

1. Skill的SKILL.md内容被作为任务提示词传递给Subagent
2. Subagent在独立上下文中执行，不接触主会话历史
3. 执行完成后，只有结果摘要返回主会话

这创造了一种强大的模式：**在Skill中定义"做什么"和"怎么做"，在Subagent中隔离执行"做的过程"**。

### 1.3 动态上下文注入——让Skill拥有实时数据

Skill的另一个强大特性是 `!`command`` 语法（称为"shell injection"或"动态上下文注入"）。当Skill加载时，Claude Code会先执行这些shell命令，将输出替换到Skill内容中，然后才将最终结果发送给Claude。

这意味着Claude接收到的不是命令本身，而是命令的实际输出。例如：

```markdown
## 当前变更
!`git diff HEAD`
```

当这个Skill被加载时，`git diff HEAD` 会先被执行，其输出替换 `!`...`` 占位符。Claude最终看到的是当前工作树的实际diff内容。

**关键点：** 动态注入发生在Skill渲染阶段，而非Claude执行阶段。Claude只看到最终结果，无法修改或注入新的命令。

## 2. 实战：构建智能PR审查工作流

现在我们将上述三个核心概念——Skill定义、动态上下文注入、Subagent隔离执行——组合为一个完整的自动化工作流。

### 2.1 需求分析

我们的目标是构建一个 `/pr-review` Skill，它能够：

1. 自动获取当前PR的diff、评论和变更文件列表
2. 将这些数据连同分析指令发送给一个只读Subagent
3. Subagent在隔离上下文中完成深度代码审查
4. 将审查报告返回主会话

这个设计的好处是：大量diff数据和中间搜索过程不会占用主会话上下文。

### 2.2 创建Skill目录结构

```bash
mkdir -p ~/.claude/skills/pr-review
```

### 2.3 编写SKILL.md

创建文件 `~/.claude/skills/pr-review/SKILL.md`，内容如下：

```yaml
---
name: pr-review
description: >
  深度审查当前Pull Request。当用户要求审查PR、检查代码变更、
  或提到PR review时自动触发。分析代码质量、安全性、性能和可维护性。
context: fork
agent: Explore
allowed-tools: Bash(gh *)
---

# Pull Request 深度审查

## PR上下文数据

以下是当前PR的实时数据：

### 变更文件列表
!`gh pr diff --name-only 2>/dev/null || echo "未检测到PR上下文，请在PR分支上运行"`

### 完整Diff
!`gh pr diff 2>/dev/null | head -3000`

### PR评论与元信息
!`gh pr view --comments --json title,body,comments,reviews,labels,additions,deletions,changedFiles 2>/dev/null || echo "{}"`

## 审查任务

基于以上PR数据，执行以下审查流程：

### 第一步：理解变更范围
- 分析变更文件列表，识别受影响的模块
- 统计新增、修改、删除的文件数量
- 识别核心变更文件（变更行数最多的文件）

### 第二步：逐文件深度审查
对每个核心变更文件：
1. 使用Glob查找文件位置
2. 使用Read读取完整文件内容（不仅是diff片段）
3. 评估以下维度：
   - **代码质量**：命名规范、函数长度、代码重复
   - **安全性**：SQL注入、XSS、敏感信息暴露、不安全的依赖
   - **性能**：N+1查询、不必要的循环、内存泄漏风险
   - **可维护性**：过度嵌套、魔法数字、缺失的错误处理
   - **测试覆盖**：变更部分是否有对应测试

### 第三步：关联分析
- 检查变更是否影响其他模块的接口
- 使用Grep搜索项目中是否有调用被修改函数的其他位置
- 评估向后兼容性

### 第四步：生成审查报告

按以下格式输出：

## 审查报告

**PR标题**: [从数据中提取]
**变更统计**: [文件数] 个文件，+[新增行] / -[删除行]

### 关键发现

#### 🔴 必须修复
[列出严重问题，包含文件路径和行号]

#### 🟡 建议改进
[列出中等问题]

#### 🟢 值得肯定
[列出好的实践]

### 风险评估
- 向后兼容性: [高/中/低]
- 安全风险: [高/中/低]
- 性能影响: [高/中/低]

### 建议的测试补充
[列出需要补充的测试用例]
```

### 2.4 配置解析

让我们逐一分析这个Skill的关键配置：

**`context: fork`** — 这是整个设计的核心。它确保PR的大量diff数据、文件搜索过程都在隔离的Subagent上下文中处理。主会话只接收最终的审查报告。

**`agent: Explore`** — 指定使用内置的Explore Subagent。Explore是一个只读Agent，使用Haiku模型，速度快且成本低。它拥有Glob、Grep、Read等只读工具，非常适合代码审查场景。

**`allowed-tools: Bash(gh *)`** — 预授权GitHub CLI命令。这里的工具授权发生在Skill渲染阶段（动态注入 `!`gh...`` 命令），而非Subagent执行阶段。Subagent本身使用Explore Agent的只读工具集。

**`!`gh pr diff`...`** — 三处动态上下文注入，在Skill加载时并行执行。Claude看到的是命令的输出结果，而非命令本身。

### 2.5 工作流执行流程

```mermaid
sequenceDiagram
    participant U as 用户
    participant CC as Claude Code
    participant SE as Shell引擎
    participant SA as Explore Subagent
    
    U->>CC: /pr-review
    CC->>CC: 识别Skill: pr-review
    CC->>SE: 执行 !`gh pr diff --name-only`
    CC->>SE: 执行 !`gh pr diff | head -3000`
    CC->>SE: 执行 !`gh pr view --comments --json ...`
    SE-->>CC: 返回命令输出
    CC->>CC: 渲染完整Skill内容<br/>（替换占位符为输出）
    CC->>SA: context:fork<br/>发送渲染后的Skill内容
    Note over SA: 在隔离上下文中执行
    SA->>SA: 分析变更文件列表
    SA->>SA: Glob查找核心文件
    SA->>SA: Read读取文件内容
    SA->>SA: Grep搜索关联引用
    SA->>SA: 生成结构化审查报告
    SA-->>CC: 返回审查报告摘要
    CC-->>U: 展示完整审查报告
```

### 2.6 测试Skill

在一个有活跃PR的Git仓库中：

```bash
# 确保在PR分支上
git checkout feature/my-feature
gh pr status

# 启动Claude Code
claude

# 方式1：直接调用
/pr-review

# 方式2：自然语言触发
请帮我审查当前的Pull Request
```

如果一切正常，你会看到Claude启动一个Explore Subagent，后者在隔离上下文中分析代码，最终返回一份结构化的审查报告。

## 3. 进阶：多Skill串联编排

单个Skill已经能完成不少工作，但真正的威力在于多个Skill之间的串联编排。

### 3.1 设计一个三层审查体系

我们可以设计三个Skill，分别处理不同维度的审查：

**Skill 1: `/pr-review`** — 代码质量审查（已创建）

**Skill 2: `/pr-security`** — 安全漏洞专项检查

```yaml
---
name: pr-security
description: >
  PR安全专项审查。检查SQL注入、XSS、CSRF、敏感信息泄露、
  不安全的依赖引入等安全问题。
context: fork
agent: Explore
allowed-tools: Bash(gh *)
---

# PR安全审查

## PR Diff
!`gh pr diff 2>/dev/null | head -3000`

## 变更文件
!`gh pr diff --name-only 2>/dev/null`

## 安全检查清单

逐一检查以下安全维度：

### 输入验证
- 搜索所有用户输入处理点（使用Grep搜索 req.body, params, query）
- 验证是否有适当的输入验证和消毒
- 检查是否存在原型污染风险

### 认证与授权
- 搜索认证相关代码（搜索 auth, token, session, cookie）
- 检查是否有权限绕过风险
- 验证敏感操作是否有适当的权限检查

### 数据保护
- 搜索敏感数据模式（搜索 password, secret, key, token, api_key）
- 检查是否有硬编码的凭据
- 验证日志中是否泄露敏感信息

### 注入风险
- 搜索SQL查询构建（搜索 query, execute, raw）
- 检查是否有参数化查询
- 搜索DOM操作（搜索 innerHTML, dangerouslySetInnerHTML）
- 检查命令注入风险（搜索 exec, spawn, system）

### 依赖安全
- 如果存在package.json变更，检查新增依赖的已知漏洞
- 检查是否有不安全的API使用

## 输出格式

### 🛡️ 安全审查报告

**严重程度**: 🔴 高危 / 🟡 中危 / 🟢 低危 / ✅ 安全

对每个发现的问题，提供：
- 问题类型和严重程度
- 文件路径和代码位置
- 潜在攻击向量
- 修复建议（含代码示例）
```

**Skill 3: `/pr-test-check`** — 测试覆盖分析

```yaml
---
name: pr-test-check
description: >
  检查PR的测试覆盖情况。分析哪些变更代码缺少对应测试，
  并建议需要补充的测试用例。
context: fork
agent: Explore
allowed-tools: Bash(gh *)
---

# PR测试覆盖分析

## 变更文件
!`gh pr diff --name-only 2>/dev/null`

## PR Diff
!`gh pr diff 2>/dev/null | head -3000`

## 分析流程

### 第一步：识别变更的生产代码文件
从变更文件列表中，过滤出生产代码文件（排除test、spec、__tests__目录）。

### 第二步：定位对应测试文件
对每个变更的生产代码文件：
1. 使用Glob搜索对应的测试文件
   - `src/foo.ts` → 搜索 `**/*foo*.test.*`、`**/*foo*.spec.*`
2. 使用Read读取找到的测试文件
3. 分析测试是否覆盖了新增/修改的函数和方法

### 第三步：评估覆盖缺口
对每个缺少测试的变更：
- 列出未覆盖的函数/方法
- 建议应编写的测试用例
- 评估风险等级（核心逻辑 vs 辅助函数）

## 输出格式

### 🧪 测试覆盖报告

**已覆盖变更**: [文件数]/[总数]
**覆盖率**: [百分比]%

#### ❌ 缺少测试的变更
| 文件 | 变更内容 | 建议测试 | 风险等级 |
|------|---------|---------|---------|
| ... | ... | ... | ... |

#### 建议新增的测试用例
[为每个缺口提供具体的测试代码建议]
```

### 3.2 编排层：统一调用接口

现在我们有三个独立的审查Skill，可以在主会话中通过一个CLAUDE.md规则实现统一编排。在项目的 `.claude/CLAUDE.md` 中添加：

```markdown
## PR审查规则

当用户要求"全面审查PR"或使用 `/pr-full-review` 时：

1. 依次执行以下三个Skill：
   - `/pr-review` → 获取代码质量报告
   - `/pr-security` → 获取安全审查报告
   - `/pr-test-check` → 获取测试覆盖报告

2. 汇总三个报告，生成综合评估：
   - 整体风险等级
   - 必须修复的阻塞问题
   - 合并建议（通过/需修改/拒绝）
```

也可以创建一个编排Skill：

```yaml
---
name: pr-full-review
description: >
  一键执行完整的PR审查流程，包括代码质量、安全性和测试覆盖分析。
  自动串联三个专项审查Skill并汇总结果。
disable-model-invocation: true
---

# 全面PR审查

执行完整的PR审查流程：

1. 使用 /pr-review 进行代码质量审查
2. 使用 /pr-security 进行安全专项检查
3. 使用 /pr-test-check 进行测试覆盖分析

收集三个审查的报告后，生成综合评估：

## 综合评估

### 风险矩阵
| 维度 | 风险等级 | 关键发现数 |
|------|---------|-----------|
| 代码质量 | ... | ... |
| 安全性 | ... | ... |
| 测试覆盖 | ... | ... |

### 合并建议
基于综合分析，给出明确的合并建议：
- ✅ 可以合并
- ⚠️ 修复后可合并（列出必须修复项）
- ❌ 不建议合并（列出阻塞原因）

### 优先修复事项
按紧急程度排列所有必须修复的问题。
```

```mermaid
graph TB
    A["/pr-full-review"] --> B["/pr-review<br/>代码质量"]
    A --> C["/pr-security<br/>安全审查"]
    A --> D["/pr-test-check<br/>测试覆盖"]

    B --> E["Explore Subagent<br/>隔离执行"]
    C --> F["Explore Subagent<br/>隔离执行"]
    D --> G["Explore Subagent<br/>隔离执行"]

    E --> H["质量报告"]
    F --> I["安全报告"]
    G --> J["测试报告"]

    H & I & J --> K["主会话汇总"]
    K --> L["综合评估 + 合并建议"]

    style A fill:#4A90D9,color:#fff
    style E fill:#6BCB77,color:#fff
    style F fill:#6BCB77,color:#fff
    style G fill:#6BCB77,color:#fff
    style L fill:#FF6B6B,color:#fff
```

## 4. Subagent选择与自定义策略

在上面的案例中我们使用了内置的Explore Agent。但Claude Code允许创建自定义Subagent，为Skill提供更精准的执行环境。

### 4.1 创建专用的代码审查Subagent

创建文件 `~/.claude/agents/code-analyzer.md`：

```yaml
---
name: code-analyzer
description: 专注代码分析的高级Agent，支持深度代码理解
tools: Read, Grep, Glob, Bash
model: sonnet
---

你是一位资深代码分析师。你的任务是深度分析代码变更并生成结构化报告。

## 工作原则

1. **上下文优先**：在分析任何变更前，先理解所属模块的整体架构
2. **证据驱动**：每个发现都必须引用具体的文件路径和代码片段
3. **分层报告**：按严重程度分级，区分阻塞性问题和改进建议
4. **可操作性**：每个建议都附带具体的修复方案

## 分析框架

- 变更影响范围分析
- 代码模式识别（反模式检测）
- 依赖关系追踪
- 接口兼容性评估

## 输出要求

使用中文输出报告。技术术语保持英文原文。
```

然后在Skill中引用这个自定义Agent：

```yaml
---
name: pr-review-pro
description: 使用自定义分析Agent进行深度PR审查
context: fork
agent: code-analyzer
---
```

### 4.2 Agent选择决策矩阵

| 场景 | 推荐Agent | 原因 |
|------|----------|------|
| 快速代码探索 | Explore (Haiku) | 速度快、成本低、只读安全 |
| 深度代码分析 | 自定义code-analyzer (Sonnet) | 更强的推理能力 |
| 需要修改代码 | general-purpose | 拥有Edit/Write工具 |
| 规划与研究 | Plan | 自动跳过CLAUDE.md，节省上下文 |

### 4.3 Skill预加载到Subagent

反向场景：你可以将Skill预加载到Subagent中，而不是让Skill运行在Subagent里。这适用于你需要给Subagent提供领域知识的情况：

```yaml
---
name: api-developer
description: 按团队规范实现API端点
tools: Read, Edit, Write, Bash
skills:
  - api-conventions
  - error-handling-patterns
---

实现API端点。严格遵循预加载的约定和模式。
```

当这个Subagent被调用时，`api-conventions` 和 `error-handling-patterns` 两个Skill的完整内容会被注入到Subagent的启动上下文中。这意味着Subagent不需要在运行时发现和加载这些Skill，它们从一开始就在上下文里。

**两种模式对比：**

```mermaid
graph LR
    subgraph "模式A: Skill在Subagent中运行"
        A1[SKILL.md] -->|"context:fork"| A2[Subagent执行]
    end

    subgraph "模式B: Skill预加载到Subagent"
        B1[Agent定义] -->|"skills字段"| B2[Skill内容注入]
        B2 --> B3[Subagent启动时已拥有知识]
    end

    style A1 fill:#7B68EE,color:#fff
    style B1 fill:#6BCB77,color:#fff
```

- **模式A**（Skill → Subagent）：Skill控制任务逻辑，Subagent提供执行环境
- **模式B**（Subagent ← Skill预加载）：Subagent控制执行逻辑，Skill提供领域知识

## 5. 动态上下文注入的深度应用

### 5.1 多行命令与复杂脚本

动态注入不仅支持单行命令，还支持多行脚本块：

```markdown
## 环境信息
```!
node --version
npm --version
git log --oneline -5
git status --short
```
```

使用 ` ```! ` 语法（三个反引号加感叹号）可以执行多行命令，所有输出合并替换整个代码块。

### 5.2 条件化上下文

通过shell逻辑实现条件化上下文注入：

```markdown
## 测试状态
!`if [ -f "package.json" ]; then npm test 2>&1 | tail -20; elif [ -f "pytest.ini" ]; then pytest --tb=short -q 2>&1 | tail -20; else echo "未检测到测试框架"; fi`
```

这段注入会根据项目类型自动选择合适的测试命令。

### 5.3 使用${CLAUDE_SKILL_DIR}引用技能内文件

当Skill包含辅助脚本时，使用 `${CLAUDE_SKILL_DIR}` 变量确保路径正确：

```markdown
## 执行分析脚本
```!
python3 ${CLAUDE_SKILL_DIR}/scripts/analyze.py
```
```

Skill目录结构：

```
codebase-analyzer/
├── SKILL.md
├── scripts/
│   └── analyze.py
└── templates/
    └── report.md
```

## 6. 错误处理与边界情况

### 6.1 命令执行失败

当动态注入的命令失败时（非零退出码），Claude Code会将错误信息插入到Skill内容中。为了优雅地处理这种情况，使用shell的错误处理：

```markdown
## PR信息
!`gh pr view --json title,body 2>/dev/null || echo '{"error": "未在PR上下文中，请确保当前分支有关联的Pull Request"}'`
```

### 6.2 输出过大时的截断

大型diff或日志可能超出上下文窗口。务必使用管道限制输出：

```markdown
## 有限Diff
!`gh pr diff 2>/dev/null | head -3000`
```

### 6.3 Skill内容的生命周期管理

Skill内容一旦加载，会在整个会话期间保留。对于大型Skill，这会持续消耗token。`context: fork` 模式天然解决了这个问题——Skill内容在Subagent的隔离上下文中，不会影响主会话的token预算。

但在非fork模式下，需要注意：
- 保持SKILL.md简洁，控制在500行以内
- 将详细参考资料放入单独的文件，在SKILL.md中链接引用
- 使用 `disable-model-invocation: true` 防止Skill被意外加载

## 7. 性能优化实践

### 7.1 模型选择策略

Subagent的模型选择直接影响成本和速度：

```mermaid
graph TD
    A[任务类型分析] --> B{需要深度推理?}
    B -->|是| C{需要修改代码?}
    B -->|否| D[使用 Haiku<br/>快速、低成本]
    C -->|是| E[使用 Sonnet<br/>平衡能力与成本]
    C -->|否| F[使用 Sonnet<br/>强推理、只读执行]

    D --> D1[Explore Agent<br/>只读工具集]
    E --> E1[general-purpose<br/>全工具集]
    F --> F1[自定义只读Agent<br/>Sonnet + 只读工具]

    style D fill:#6BCB77,color:#fff
    style E fill:#FFD93D,color:#333
    style F fill:#FFD93D,color:#333
```

### 7.2 并行Subagent执行

当多个审查任务互相独立时，可以让Claude并行启动多个Subagent。在编排Skill中明确指示：

```markdown
请并行执行以下三个审查任务，不要等待前一个完成再启动下一个：
1. 使用pr-review进行代码质量审查
2. 使用pr-security进行安全审查
3. 使用pr-test-check进行测试覆盖分析
```

Claude会根据任务描述自动决定是否并行。明确的指令可以帮助它做出正确判断。

### 7.3 上下文预算管理

Claude Code对Skill描述有一个上下文预算（默认为模型上下文窗口的1%）。当Skill数量很多时，低优先级Skill的描述可能被截断。

使用 `skillOverrides` 设置控制哪些Skill应该保留完整描述：

```json
{
  "skillOverrides": {
    "pr-review": "on",
    "pr-security": "on",
    "pr-test-check": "on",
    "legacy-helper": "name-only"
  }
}
```

# 实战案例：运行效果演示

以下是一个真实的 `/pr-review` 执行过程的模拟：

**场景**：一个Node.js项目，PR新增了一个用户注册API端点。

**用户输入**：
```
/pr-review
```

**Claude Code执行流程**：

1. **动态注入阶段**（约2-3秒）：
   - `gh pr diff --name-only` → 输出5个变更文件
   - `gh pr diff` → 输出约800行diff
   - `gh pr view --json` → 输出PR元信息

2. **Subagent启动阶段**（约1秒）：
   - 创建Explore Agent隔离上下文
   - 注入渲染后的Skill内容（包含实际diff数据）

3. **Subagent执行阶段**（约30-60秒）：
   - Explore Agent分析变更文件列表
   - 使用Glob查找 `src/routes/auth.ts`、`src/models/user.ts`
   - 使用Read读取完整文件
   - 使用Grep搜索 `password`、`hash`、`validate` 关键词
   - 生成结构化审查报告

4. **结果返回**（约2秒）：
   - 审查报告摘要返回主会话

**输出示例**：

```markdown
## 审查报告

**PR标题**: feat: add user registration endpoint
**变更统计**: 5 个文件，+247 / -12

### 关键发现

#### 🔴 必须修复
1. **src/routes/auth.ts:34** — 密码未使用bcrypt哈希，直接存储明文
   ```typescript
   // 当前代码
   const user = await User.create({ email, password });
   // 建议修改
   const hashedPassword = await bcrypt.hash(password, 12);
   const user = await User.create({ email, password: hashedPassword });
   ```

2. **src/routes/auth.ts:28** — 缺少输入验证，存在注入风险

#### 🟡 建议改进
1. **src/models/user.ts:15** — 邮箱唯一约束缺少数据库层索引
2. **src/routes/auth.ts:45** — 错误消息过于详细，可能泄露系统信息

#### 🟢 值得肯定
1. 使用了参数化查询
2. 引入了速率限制中间件

### 风险评估
- 向后兼容性: 高（新增端点，不影响现有API）
- 安全风险: 高（密码存储和输入验证问题）
- 性能影响: 低
```

**关键观察**：整个审查过程（包括800行diff、5个文件的完整读取、多个关键词搜索）都在Explore Agent的隔离上下文中完成。主会话的上下文窗口只增加了审查报告本身（约500 tokens），而非完整的中间数据（可能超过10,000 tokens）。

# Mermaid流程图：完整的Skill-Subagent协作架构

```mermaid
graph TB
    subgraph 用户层
        U[开发者] -->|"/pr-review<br/>/pr-security<br/>/pr-full-review"| CLI[Claude Code CLI]
    end

    subgraph Skill层
        CLI -->|识别与加载| SK1[pr-review SKILL.md]
        CLI -->|识别与加载| SK2[pr-security SKILL.md]
        CLI -->|识别与加载| SK3[pr-test-check SKILL.md]
        CLI -->|识别与加载| SK4[pr-full-review SKILL.md]
    end

    subgraph 动态注入层
        SK1 & SK2 & SK3 -->|!`command`| SH[Shell执行引擎]
        SH -->|替换占位符| RENDER[渲染后的完整内容]
    end

    subgraph Subagent调度层
        RENDER -->|context:fork| DISP[Agent调度器]
        DISP -->|agent:Explore| EXP[Explore Agent]
        DISP -->|agent:code-analyzer| CUSTOM[自定义Agent]
    end

    subgraph 隔离执行层
        EXP --> TOOLS1["工具集: Glob, Grep, Read"]
        CUSTOM --> TOOLS2["工具集: Read, Grep, Glob, Bash"]
    end

    subgraph 结果层
        TOOLS1 & TOOLS2 --> RESULT[审查报告]
        RESULT -->|返回摘要| CLI
        CLI -->|展示| U
    end

    style U fill:#4A90D9,color:#fff
    style EXP fill:#6BCB77,color:#fff
    style CUSTOM fill:#6BCB77,color:#fff
    style RESULT fill:#FF6B6B,color:#fff
```

# 延伸阅读

- [Claude Code官方文档：Extend Claude with skills](https://docs.anthropic.com/en/docs/claude-code/skills) — Anthropic官方Skill完整参考，涵盖frontmatter字段、动态注入、支持文件等全部特性
- [Claude Code官方文档：Create custom subagents](https://docs.anthropic.com/en/docs/claude-code/sub-agents) — Subagent完整配置指南，包括工具限制、模型选择、Hooks、持久化内存等高级功能
- [Claude Code Skills: A Practical Guide for 2026](https://dev.to/muhammad_moeed/claude-code-skills-a-practical-guide-for-2026-3f6p) — 2026年Skill实战指南，包含多个实用Skill示例
- [Claude Code Customization Guide: CLAUDE.md, Skills, Subagents](https://alexop.dev/posts/claude-code-customization-guide-claudemd-skills-subagents/) — Claude Code定制化全景指南，系统讲解三大扩展机制的配合使用
- [Under the Hood of Claude Code Skills](https://mikhail.io/2025/10/claude-code-skills/) — 深入分析Skill的内部工作机制，包括内容生命周期和上下文管理

# 训练营适用性评估

| 评估维度 | 评分 | 说明 |
|---------|------|------|
| **概念难度** | ★★★★☆ | 需要理解Skill、Subagent、动态注入三个独立概念及其协作关系 |
| **实践门槛** | ★★★☆☆ | 只需创建Markdown文件，但需要理解shell命令和Git工作流 |
| **调试难度** | ★★★★☆ | 隔离上下文中的错误不易追踪，需要查看Subagent日志 |
| **实用性** | ★★★★★ | PR审查、代码分析、安全审计等场景均有直接价值 |
| **可扩展性** | ★★★★★ | 模式可复用于任何需要"数据采集+隔离分析+结果汇总"的场景 |
| **推荐学员级别** | 中高级 | 建议已具备Claude Code基础使用经验，理解Git和CLI工具 |

**适合的训练营模块：**
- Day 3-4：高级扩展机制（Skill + Subagent联合使用）
- 作为「从基础Skill到生产级编排」的进阶课程内容
- 小组项目：各团队设计并实现一个面向特定场景的审查/分析工作流

**前置模块建议：**
1. Claude Code基础操作与CLAUDE.md配置
2. Skill基础：创建简单的SKILL.md
3. 本文内容：Skill与Subagent联合编排

> [!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)