Skills 单独使用已经很强但它真正的威力在于与 SubAgent 组合——把一个通用的 Agent 打造成领域专家。一、两个组合方向谁包含谁Skills 解决的是“怎么做”的问题本质是知识注入——它让同一个 Agent 学会新的能力就像给一个员工发了一本操作手册员工还是那个人只是掌握了更多方法与规范。SubAgents 解决的是“谁来做”的问题本质是任务委托——它创建一个独立的执行者去完成某件事就像把任务交给另一位同事对方拥有自己的上下文、职责边界和决策空间。当你犹豫到底是用 Skill 还是用 SubAgent 的时候做出选择的核心判断标准在于这件事到底需要“另一个人”来承担还是只需要“多一本手册”来指导而更常见的情况是结合起来使用。当你把两者组合时本质上只有两个原子方向——是 SubAgent 内部加载 Skills还是由主 Agent 通过 Skills 去编排和调用 SubAgents。1、方向 ASubAgent 包含 Skillskills 字段此时你定义子代理的角色通过 skills 字段给它预加载领域知识。SubAgent 是老板Skill 是工具书。# .claude/agents/api-doc-generator.md---name: api-doc-generatordescription: Generate API documentation by scanning Express route files.tools: [Read, Grep, Glob, Write, Bash]skills:- api-generating # ← 关键预加载 Skill 作为领域知识---You are an API documentation specialist.## Your MissionGenerate or update API documentation for Express.js routes.这种情况下Claude Code 的执行流程如下Claude 主对话: 用 api-doc-generator 为 src/ 生成 API 文档主对话 SubAgent (api-doc-generator)│ │├─ 创建子代理 注入 Skill ──────→ ││ ├─ 上下文中已有角色定义 SKILL.md 全文│ ├─ 按 SKILL.md 步骤执行任务│ ├─ 使用 Skill 提供的脚本和模板│ ├─ 生成文档│ ←──── 返回结果摘要 ──────────── │├─ 继续对话 子代理结束SubAgent 包含 Skill 是最常见的情况适用场景包括子代理需要特定领域的专业知识来完成任务同一个 Skill 可以被不同角色的 SubAgent 复用以及需要长期维护的专家型 Agent。2、方向 BSkill 包含 SubAgentcontext: fork在这种情况下Skill 自带任务指令通过 context: fork 配置自动“派遣”一个子代理去执行。Skill 是老板SubAgent 是执行者。---name: deep-researchdescription: Research a topic thoroughly in the codebasecontext: fork # ← 关键让 Skill 在独立子代理中执行agent: Explore # ← 子代理类型---Research $ARGUMENTS thoroughly:1. Find relevant files using Glob and Grep2. Read and analyze the code3. Summarize findings with specific file references此时的 Claude Code 执行流程如下用户: /deep-research authentication flow主对话 子代理Explore│ │├─ 创建隔离上下文 ────────────────→ ││ ├─ 收到任务Research authentication flow...│ ├─ Glob/Grep 搜索相关文件│ ├─ Read 分析代码│ ├─ 生成结构化摘要│ ←──── 返回结果摘要 ──────────── │├─ 继续对话上下文干净 子代理结束子代理看不到你之前的对话历史因此 SKILL.md 的内容成为子代理的任务指令。agent 字段决定子代理类型Explore只读探索、Plan规划、general-purpose通用省略 agent 时默认使用)。这种应用方式的适用场景是研究型任务深度探索代码库不污染主对话重型生成批量生成文档中间过程不需要用户看到以及安全隔离Skill 的操作不应影响主对话状态3、方向C 串联使用上面讲到了sub agent和skill的包含关系这可以是单向应用也可以串联使用。如08-skill-pipeline/├── CLAUDE.md ← 流水线编排指令├── .claude/│ ├── agents/│ │ ├── route-scanner.md ← 阶段 1: 路由扫描专家 (haiku)│ │ ├── doc-writer.md ← 阶段 2: 文档编写专家 (sonnet)│ │ └── quality-checker.md ← 阶段 3: 质量检查专家 (haiku)│ ├── skills/│ │ ├── route-scanning/│ │ │ ├── SKILL.md ← 扫描工作流程│ │ │ └── scripts/scan-routes.py ← 路由扫描脚本│ │ ├── doc-writing/│ │ │ ├── SKILL.md ← 文档生成工作流程│ │ │ └── templates/endpoint-doc.md ← 文档模板│ │ └── quality-checking/│ │ ├── SKILL.md ← 质量检查工作流程│ │ └── rules/doc-standards.md ← 质量标准规则│ └── settings.local.json├── src/routes/│ ├── products.js ← 7 条路由含链式路由│ └── categories.js ← 5 条路由└── docs/ ← 生成的文档输出流水线的编排逻辑写在 CLAUDE.md 中# API Documentation PipelineWhen the user asks to run the documentation pipeline:### Stage 1: Route ScanningUse the route-scanner agent to scan the source directory.Collect the route manifest (JSON) from its output.### Stage 2: Documentation GenerationUse the doc-writer agent to generate documentation.Pass the route manifest from Stage 1 as input context.### Stage 3: Quality ValidationUse the quality-checker agent to validate the generated docs.Report the quality verdict to the user.要点一定义清晰的阶段间接口这些就是阶段间的“接口合约”。每个阶段的 SKILL.md 都明确写了输出格式。阶段 1 输出 JSON 路由清单阶段 2 输出文件列表 路由覆盖数阶段3 输出 PASS/NEEDS_REVISION 报告要点二每个 Skill 只关注一件事route-scanning 只扫描路由不生成文档。doc-writing 只生成文档不检查质量。quality-checking 只检查质量不修改文档。单一职责让每个 Skill 更简洁、更可测试、更可复用。要点三编排逻辑集中管理流水线的顺序、数据传递逻辑都放在 CLAUDE.md 中。如果要调整流程比如跳过阶段 3只需修改 CLAUDE.md不需要动 Skill 或 SubAgent。