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++代码评审全流程

Plain 复制代码

用户触发 /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，实现全流程自动化评审，既提升效率，又保证评审标准化。