Claude Code 从入门到精通（七）：Sub Agent 与 Skill 终极PK
Sub Agent（子代理）和 Skill（技能）是 Claude Code 插件系统中模块化扩展AI能力的两大核心组件，二者设计初衷、能力边界、调用方式差异显著，适配不同的自动化/智能化开发场景，且可配合使用形成更强大的组合能力。本文结合官方定义+开发实战，完整覆盖「核心定位→维度化区别→专属场景→典型案例→选型方法→搭配技巧」，助力开发者在实际开发中精准落地。
一、核心定位（一句话快速区分）
两者的核心差异源于「任务覆盖范围」，可通过一句话精准区分：
Sub Agent（子代理）：专属领域的“专业助手”，聚焦单一核心领域的全流程任务，具备独立的逻辑判断、工具调用、流程编排能力，需显式触发，适合复杂、多步骤、强领域属性的任务。
Skill（技能）：通用/细分的“功能原子”，聚焦单个具体的小功能/操作，无独立流程编排能力，需被调用（AI/Sub Agent/用户），适合轻量、可复用、单一动作的高频操作。
简单类比：Sub Agent 是“完整完成一件事”（如完成C++代码全流程评审），Skill 是“完成一件事里的一个具体动作”（如用clang-tidy做静态检查）；Skill 是基础能力积木，Sub Agent 是用积木搭建的专属工具。
二、核心区别（维度化对比）
| 对比维度 | Sub Agent（子代理） | Skill（技能） |
|---|---|---|
| 核心定位 | 领域专属的专业助手，负责全流程复杂任务 | 通用/细分的功能原子，负责单一具体操作 |
| 能力边界 | 独立思考、流程编排、多工具/多Skill组合调用、结果整合 | 无独立思考，仅执行单一动作，无流程编排能力 |
| 调用方式 | 1. 用户显式触发（/subagent run 代理名）；2. Hooks 自动触发（@on_file_change）；3. 其他Sub Agent调用 | 1. AI 自动调用（基于用户指令匹配）；2. Sub Agent 主动调用（作为流程步骤）；3. 用户显式调用（/skill 技能名） |
| 复用性 | 领域专属，复用性低（如C++代码评审代理仅适配C++场景） | 通用/跨领域，复用性高（如“代码格式化”可适配C++/Go/Java） |
| 配置复杂度 | 高，需定义角色、规则、流程、输出格式，完整Prompt工程 | 低，仅需定义触发条件、执行动作、入参/出参，轻量化配置 |
| 生命周期 | 独立生命周期，任务完成后结束，可返回结构化结果 | 无独立生命周期，调用即执行，执行完即结束，返回单一结果 |
| 维护成本 | 高，需维护流程逻辑、领域规则及Skill调用适配 | 低，仅需维护单一操作的执行逻辑和参数适配 |
| 异常处理 | 支持复杂异常处理（步骤失败终止、分支逻辑、错误重试） | 无复杂异常处理，仅捕获工具执行错误并返回结果 |
| 输出形式 | 结构化定制结果（如评审报告、部署日志、调试报告） | 单一结果（如格式化后的代码、检查原始日志、文件内容） |
三、专属场景及典型实战案例
结合C++/Go开发、Unity游戏开发等高频场景，分别说明两者的适用场景及实战案例，同时补充组合使用场景，贴合开发落地需求。
（一）Sub Agent：复杂全流程任务的专属助手
核心适用场景
适合复杂、多步骤、强领域属性、有固定流程的开发任务，替代人工完成“专业领域的全流程工作”，需显式或自动触发，无需用户干预中间步骤。
典型实战案例
案例1：C++ 代码评审子代理（核心适配代码评审需求）
定位：C++领域专属的代码评审专家，负责C++代码的全流程评审。
核心能力：
接收用户/钩子触发的C++文件评审指令；
自动拆解评审步骤：静态检查（调用clang-tidy Skill）→ 规范校验（内置C++规则）→ 性能/安全分析 → 结果整合；
调用通用Skill：
clang-tidy-check（静态检查）、code-syntax-highlight（代码片段提取）；输出标准化评审报告（问题ID+描述+错误示例+修复示例+优先级）。
触发方式：
手动触发：
/subagent run cpp-code-review --input main.cpp自动触发：
@on_file_change *.cpp /subagent run cpp-code-review --input $FILE
案例2：Go 项目构建部署子代理
定位：Go项目专属的构建部署助手，负责Go项目从编译→测试→打包→部署的全流程。
核心能力：
拆解部署流程：依赖检查（go mod tidy）→ 单元测试（go test）→ 编译构建（go build）→ 服务器上传（scp）→ 进程重启；
调用通用Skill：
go-mod-check、go-test-run、ssh-command；异常处理：某步骤失败（如测试不通过），自动终止流程并返回错误详情。
触发方式：/subagent run go-deploy --input ./project --env prod
案例3：Unity 2D游戏脚本调试子代理
定位：Unity C#脚本专属调试助手，负责游戏脚本的错误排查、日志分析、修复建议。
核心能力：
接收Unity报错日志+脚本文件；
步骤拆解：日志解析（提取错误行/原因）→ 脚本语法检查 → 游戏逻辑漏洞分析 → 修复代码生成；
调用Skill：
csharp-lint、unity-log-parse、code-fix-generate；输出调试报告+可直接复制的修复代码。
触发方式：/subagent run unity-csharp-debug --input PlayerController.cs --log error.log
（二）Skill：可复用的功能原子
核心适用场景
适合轻量、可复用、单一动作的高频操作，无独立流程编排能力，需被AI、Sub Agent或用户调用，是构建复杂能力的基础积木。
典型实战案例（按复用性分类）
第一类：通用Skill（跨语言/跨领域，复用性最高）
适用于所有开发场景，是Sub Agent的基础调用组件，官方插件市场已内置大部分。
代码格式化类：
clang-format（C++格式化）、gofumpt（Go格式化）、prettier（前端格式化）功能：输入代码文件/片段，输出格式化后的代码，无额外逻辑；
调用场景：所有代码评审、代码生成Sub Agent都会调用。
静态检查类：
clang-tidy-check（C++静态检查）、golangci-lint-check（Go静态检查）、eslint-check（前端检查）功能：输入代码文件，输出静态检查的原始结果（错误行、错误类型）；
调用场景：代码评审Sub Agent的核心步骤组件。
工具调用类：
git-diff（获取代码差异）、file-reader（读取文件内容）、ssh-command（执行远程SSH命令）功能：输入参数（如文件路径/SSH指令），输出工具执行结果；
调用场景：构建部署、代码评审Sub Agent均会调用。
第二类：领域细分Skill（单一领域的小功能，复用性中等）
适配特定语言/场景的单一操作，比通用Skill更贴合领域需求，但仍为单一动作。
C++专属：
cpp-raiicheck（检查RAII规范）、cpp-memory-leak-scan（轻量内存泄漏扫描）功能：仅检查C++代码的RAII规范/内存泄漏点，输出具体问题行；
调用场景：C++代码评审Sub Agent的细分步骤。
Go专属：
go-errcheck（检查未处理error）、go-goroutine-scan（检查裸goroutine）功能：仅扫描Go代码的未处理error/裸goroutine，输出问题位置；
调用场景：Go代码评审Sub Agent的细分步骤。
Unity专属：
unity-log-parse（解析Unity报错日志）、csharp-serialize（C#代码序列化）功能：仅解析Unity日志/序列化C#代码，输出结构化结果；
调用场景：Unity脚本调试Sub Agent的细分步骤。
第三类：自定义轻量Skill（项目专属，复用性低）
针对当前项目的高频单一操作，开发者自定义的轻量化技能。
项目配置读取：
proj-config-reader功能：输入配置项名称，从项目
config.json中读取对应值，输出结果；调用场景：所有项目相关Sub Agent（构建、调试、部署）均可调用。
测试用例生成：
unit-test-gen-simple功能：输入简单函数（如C++/Go工具函数），输出基础单元测试代码；
调用场景：代码评审、开发辅助Sub Agent的辅助步骤。
（三）组合使用场景（Sub Agent + Skill 最大化价值）
二者并非互斥，而是互补协作的关系——Skill作为基础能力积木，Sub Agent作为领域助手，通过组合调用多个Skill完成复杂任务，是Claude Code插件系统的核心设计思路。
典型组合案例：C++代码评审全流程
用户触发 /subagent run cpp-code-review --input main.cpp ↓ C++代码评审Sub Agent 启动，拆解流程： 1. 读取文件内容 → 调用通用Skill：file-reader 2. 代码格式化检查 → 调用通用Skill：clang-format 3. 静态语法检查 → 调用通用Skill：clang-tidy-check 4. RAII规范检查 → 调用C++细分Skill：cpp-raiicheck 5. 内存泄漏扫描 → 调用C++细分Skill：cpp-memory-leak-scan 6. 整合所有Skill返回的原始结果，按内置C++评审规则做二次分析 7. 生成结构化评审报告（问题ID+描述+修复示例）并输出 ↓ 任务完成，Sub Agent 生命周期结束其他组合案例
Go项目构建部署：Go部署Sub Agent → 调用
go-mod-check→go-test-run→go-build→ssh-command→ 整合结果返回；Unity脚本调试：Unity调试Sub Agent → 调用
unity-log-parse→file-reader→csharp-lint→code-fix-generate→ 输出调试报告+修复代码。
四、实际开发选型指南（可直接落地）
核心遵循「任务粒度+流程属性+复用性」三大判断标准，结合触发方式、领域属性、维护成本做二次取舍，以下是可直接套用的决策框架和场景清单。
（一）核心决策三步法
按优先级排序，快速确定选型：
步骤1：判断「任务粒度」（第一优先级）
单一动作（输入→处理→输出，无中间步骤）：选 Skill；
多步骤流程（需拆解步骤、按逻辑执行、步骤间有依赖/判断）：选 Sub Agent。
步骤2：判断「复用性」（二次筛选）
若选Skill：优先封装跨领域/跨项目的通用操作，避免为单一场景做无意义封装；
若选Sub Agent：聚焦强领域属性的专属任务，避免把通用流程封装为Sub Agent。
步骤3：判断「触发/调用方式」（最终适配）
需被主AI/Sub Agent/其他组件调用（作为基础能力）：选 Skill；
需用户显式触发/钩子自动触发（独立完成一个业务任务）：选 Sub Agent。
（二）高频场景选型清单
| 实际开发任务 | 任务特征 | 选型 | 原因 |
|---|---|---|---|
| C++/Go代码格式化、静态检查 | 单一动作、通用、可被调用 | Skill | 纯工具调用，无流程，可被代码评审Sub Agent复用 |
| C++/Go完整代码评审（含检查、规则校验、报告生成） | 多步骤、领域专属、需显式触发 | Sub Agent | 需拆解流程，整合多个Skill结果，输出标准化领域报告 |
| Unity报错日志解析、C#脚本静态检查 | 单一动作、Unity领域细分、可被调用 | Skill | 纯解析/检查操作，可被Unity调试Sub Agent复用 |
| Unity 2D脚本全流程调试 | 多步骤、Unity专属、需独立触发 | Sub Agent | 需组合多个Unity Skill，按调试逻辑执行，生成调试报告 |
| 项目依赖检查、单元测试执行 | 单一动作、通用、可被调用 | Skill | 纯工具操作，可被构建/部署Sub Agent复用 |
| Go/前端项目构建部署 | 多步骤、项目/语言专属、需自动触发 | Sub Agent | 步骤间有依赖（测试不通过则终止编译），需独立完成全流程 |
| 读取文件、执行SSH命令、生成简单单元测试代码 | 单一动作、通用、高频 | Skill | 基础工具操作，跨所有场景和Sub Agent复用 |
| 数据库脚本审核+执行 | 多步骤、后端领域专属、需显式触发 | Sub Agent | 有流程判断（语法错误则终止），需整合多个操作结果 |
（三）选型避坑原则
不“过度封装”：单一操作不做Sub Agent，通用操作不做领域Skill。避免把“clang-tidy静态检查”封装为Sub Agent，也避免把“通用代码格式化”封装为C++专属Skill。
不“碎片化拆分”：强关联的多步骤流程，不拆分为多个独立Skill。如C++代码评审的全流程的强关联步骤，需封装为Sub Agent，而非多个独立Skill。
优先搭积木再组装：先把高频单一操作封装为Skill，再组合Skill封装Sub Agent，提升复用性，减少重复开发。
临时任务不封装：一次性/临时任务（如临时修改一行代码、执行git pull），直接执行终端命令，无需封装Skill/Sub Agent。
五、总结
Sub Agent 与 Skill 的核心差异在于「任务覆盖范围」和「独立能力」，二者协同构成Claude Code的模块化扩展体系：
Skill 是“功能原子”，解决“单一操作复用”问题，适配轻量、高频、通用的开发动作；
Sub Agent 是“领域助手”，解决“复杂流程自动化”问题，适配多步骤、强领域、全流程的开发任务；
实战核心思路：先封装Skill搭建基础能力库，再组合Skill封装Sub Agent，兼顾复用性和领域化自动化能力。
针对C++/Go代码评审等核心需求，最优实践是：封装对应静态检查、格式化的通用/领域Skill，再构建专属Sub Agent整合这些Skill，实现全流程自动化评审，既提升效率，又保证评审标准化。
