🎯 Claude Code 的秘密武器：Subagent 和 Skills 入门指南

“授人以鱼不如授人以渔,授人以渔不如给 AI 一套钓鱼工具箱” —— 某位智者(大概)

📖 目录

• 什么是 Subagent?
• 什么是 Skills?
• 它们有什么用?
• 怎么写一个 Subagent?
• 怎么写一个 Skill?
• 实战案例
• 最佳实践

---

🤔 什么是 Subagent?

想象一下,你是一个公司的 CEO(主 Agent),公司业务越来越复杂:

• 前端问题需要处理 🎨
• 后端 bug 要修复 🔧
• DevOps 流程要优化 ⚙️
• 文档要写 📝

你一个人忙不过来怎么办?雇佣专家!

这就是 Subagent 的核心思想:

主 Agent (CEO)
    ├── Frontend Engineer (前端专家)
    ├── Backend Engineer (后端专家)
    ├── DevOps SRE (运维专家)
    └── Technical Writer (文档专家)

Subagent 是一个独立的 Agent 配置文件,它拥有:

• 🎭 专属角色定位 - 明确的职责范围
• 🔧 专用工具集 - 只能使用特定工具
• 🧠 领域知识 - 针对特定场景的提示词
• 🎯 自主决策能力 - 在权限范围内独立完成任务

Subagent 配置文件长什么样?

---
name: api-developer
description: API 开发专家,负责 RESTful API 的设计、开发、测试和文档编写
tools: ["Read", "Write", "Grep", "Glob", "Bash", "Edit"]
skills: ["api-scaffold", "api-testing", "api-documentation"]
---

你是一个资深的 API 开发专家...

## 核心职责
1. RESTful API 设计与开发
2. 遵循 OpenAPI 规范
3. API 测试和文档编写

核心要素:

1. name - Agent 的唯一标识
2. description - 干什么用的(让主 Agent 知道什么时候召唤你)
3. tools - 允许使用的工具白名单
4. skills - 可以调用的技能清单
5. Prompt 正文 - 详细的角色说明、工作流程、规范等

---

🎓 什么是 Skills?

如果说 Subagent 是"专家",那 Skills 就是**“专家的标准操作手册(SOP)”**。

想象你雇了一个新员工(Subagent),你不可能每次都口头指导他怎么做事,所以你给他写了一本《工作手册》:

📘 员工手册
    ├── 第1章: 如何创建项目脚手架
    ├── 第2章: 如何打包部署
    ├── 第3章: 如何编写代码规范
    └── 第4章: 如何提交 Git Commit

这就是 Skills!

Skills 的特点:

特性	说明	类比
可复用	多个 Subagent 可以共享同一个 Skill	多个员工共用同一本手册
模块化	每个 Skill 只负责一件事	手册的每一章只讲一个流程
标准化	确保操作一致性	无论谁执行都遵循相同步骤
可维护	修改一处,全局生效	更新手册,所有人都学到新流程

Skill 文件长什么样?

---
name: react-component-scaffold
description: 快速生成符合团队规范的 React 组件项目结构和模板代码
---

# React 组件脚手架生成

## 使用场景
当需要创建新的 React 组件时使用此技能

## 标准执行流程

### Phase 1: 信息收集 (使用 AskUserQuestion 工具)
**Step 1 - 收集组件基本信息**:
- 组件名称
- 组件类型 (functional/class)
- 是否需要样式文件

### Phase 2: 文件生成 (使用 Write 工具)
...

### Phase 3: 验证与输出
...

关键点:

• 场景触发条件 - 什么时候用这个技能
• 分阶段流程 - 每一步该做什么
• 工具调用顺序 - 先用什么工具,后用什么工具
• 输出格式 - 最终交付什么

---

🚀 它们有什么用?

场景 1: 提高效率

没有 Subagent/Skills 之前:

用户: "帮我创建一个 MCP 插件"
AI: "好的,我需要..."
    → 询问 10 个问题
    → 创建文件
    → 忘记某个步骤
    → 格式不统一
    → 花费 20 分钟

有了 Subagent/Skills 之后:

用户: "帮我创建一个 React 组件"
主 Agent: "我召唤 frontend-engineer!"
    → Subagent 读取 react-component-scaffold skill
    → 按照标准流程执行
    → 3 分钟搞定
    → 完全符合规范

场景 2: 保证质量

Skills 就像代码审查的 CheckList:

## 质量检查清单
- [ ] 目录名称符合命名规范
- [ ] 必需的4个文件都已创建
- [ ] 版本号在文件中一致
- [ ] 所有文件编码为 UTF-8

Subagent 每次执行都会遵循这个清单,不会遗漏。

场景 3: 知识沉淀

团队的最佳实践可以固化成 Skills:

git-commit.md      → Git 提交规范
code-review.md     → 代码审查流程
deployment.md      → 部署操作手册
troubleshoot.md    → 故障排查指南

新人入职?把这些 Skills 给他,立刻上手!

---

🛠️ 怎么写一个 Subagent?

Step 1: 明确职责边界

问自己 3 个问题:

1. 这个 Agent 负责什么领域? (前端/后端/测试/文档…)
2. 它的输入是什么? (用户需求/代码/配置…)
3. 它的输出是什么? (代码/文档/部署包…)

示例:

---
name: frontend-engineer
description: 前端工程师,负责 React/Vue 组件开发、CSS 样式优化、前端性能调优
tools: ["Read", "Write", "Edit", "Bash", "Grep", "Glob"]
skills: ["component-scaffold", "css-optimization", "performance-audit"]
---

Step 2: 编写角色提示词

核心结构:

## 你是谁
你是一个资深前端工程师,擅长 React 生态...

## 核心职责
1. 开发可复用的 React 组件
2. 优化 CSS 性能和兼容性
3. 进行前端性能审计

## 技术要求
- 遵循 React Hooks 最佳实践
- 使用 TypeScript 进行类型约束
- 遵循 Airbnb JavaScript Style Guide

## 工作流程
当用户提出前端开发需求时:
1. 分析需求,确认技术栈
2. 设计组件结构
3. 编写代码
4. 测试验证
5. 优化性能

## 代码规范
### 组件命名
- 组件文件使用 PascalCase (MyComponent.tsx)
- 组件函数使用 PascalCase
- Props 类型使用 PascalCase + Props 后缀

### 样式规范
- 使用 CSS Modules 或 styled-components
- 避免使用 !important
- 移动端优先的响应式设计

## 质量标准
- [ ] 组件有 TypeScript 类型定义
- [ ] 组件有 PropTypes 或 interface
- [ ] 复杂逻辑有注释
- [ ] 可访问性 (ARIA 标签)

Step 3: 定义技能依赖

## 技能使用指南

### component-scaffold - 组件脚手架生成
**触发时机**: 用户说"创建新组件"、"生成组件模板"
**执行步骤**:
1. 读取 `.claude/skills/frontend-engineer/component-scaffold.md`
2. 按照技能文件中的流程执行

### css-optimization - CSS 优化
**触发时机**: 用户说"优化样式"、"减少 CSS 体积"
**执行步骤**:
1. 读取 `.claude/skills/frontend-engineer/css-optimization.md`
2. 分析现有 CSS
3. 应用优化策略

Step 4: 放到正确位置

.claude/
└── agents/
    ├── frontend-engineer.md      # 你的 Subagent 文件
    ├── backend-engineer.md
    └── api-developer.md

---

📚 怎么写一个 Skill?

Step 1: 定义使用场景

先明确:

• 谁用这个 Skill? (哪些 Subagent)
• 什么时候用? (触发条件)
• 解决什么问题? (输入输出)

示例:

---
name: api-endpoint-scaffold
description: 快速生成符合 RESTful 规范的 API 端点项目结构和模板代码
---

# API 端点脚手架生成

## 使用场景
当需要创建新的 API 端点时使用此技能

**触发条件**:
- 用户说"创建 API"、"新建端点"、"生成接口"

**输入**: 端点名称、HTTP 方法、请求参数、响应格式

**输出**: 完整的 API 端点文件结构和初始代码

Step 2: 设计执行流程

用 Phase 思维拆解任务:

## 标准执行流程

### Phase 1: 信息收集 (使用 AskUserQuestion 工具)

**Step 1 - 收集 API 基本信息**:

使用 `AskUserQuestion` 工具,提问:
- API 端点名称是什么? (如: 用户管理)
- HTTP 方法是什么? (GET/POST/PUT/DELETE)
- 用一句话描述功能

**提取信息**:
- `endpoint_name`: 端点名称
- `http_method`: HTTP 方法
- `description`: 功能描述

---

### Phase 2: 文件生成 (使用 Write 工具)

**Step 1 - 创建目录**:
```bash
mkdir -p routes/${endpoint_name}

Step 2 - 生成必需文件:

1. 创建 router.js - 路由定义
2. 创建 controller.js - 业务逻辑
3. 创建 validator.js - 参数校验
4. 创建 README.md - API 文档

---

Phase 3: 验证与输出

Step 1 - 语法验证:

node --check router.js
node --check controller.js

Step 2 - 输出提示信息:

✅ API 端点脚手架已生成!
📦 端点信息: ...
📁 生成的文件: ...
🔧 下一步操作: ...

Step 3: 提供完整示例

当然可以，以下是针对 CSDN 博客平台优化后的 Markdown 格式内容。我已调整标题层级、代码块格式、列表样式，并确保排版清晰、可读性强，适合发布在技术博客中：

---

Step 2 - 输出提示信息

✅ API 端点脚手架已生成!
📦 端点信息: GET /users, POST /users
📁 生成的文件: 
   - routes/user.routes.js
   - controllers/user.controller.js
   - models/User.js
🔧 下一步操作: 运行 `npm start` 启动服务，访问 /api/users 查看结果

---

Step 3：提供完整示例（真实对话案例）

明白了，以下是根据您的原始内容进行简洁美化和格式优化后的版本，保持原有信息结构和表达风格，仅提升可读性与排版美观度，适用于 CSDN 博客发布：

---

Step 2 - 输出提示信息

✅ API 端点脚手架已生成!
📦 端点信息: ...
📁 生成的文件: ...
🔧 下一步操作: ...

---

Step 3：提供完整示例

真实对话案例非常重要！

场景：创建用户管理 API

用户：
我需要创建一个用户管理 API，包含获取用户列表和创建用户两个端点。

Agent：
好的，我将帮你创建用户管理 API。首先需要收集一些基本信息：

[使用 AskUserQuestion 工具提问]
问题1：请确认 API 模块名称
问题2：数据库表名
问题3：是否需要认证中间件？

---

用户回答：

1. user-management
2. users
3. 需要

---

Agent 执行步骤：

• Step 1：解析用户需求
• Step 2：创建目录结构
• Step 3：生成路由和控制器文件
• Step 4：验证文件完整性
• Step 5：输出结果

Step 4: 添加质量检查

## 质量检查清单

- [ ] 目录名称符合命名规范
- [ ] 必需文件都已创建
- [ ] 版本号保持一致
- [ ] 所有文件编码为 UTF-8
- [ ] JSON 格式正确
- [ ] Python 语法无误

Step 5: 放到正确位置

.claude/
└── skills/
    ├── shared/                           # 共享技能
    │   ├── git-commit.md
    │   └── code-review.md
    └── api-developer/                    # 专属技能
        ├── api-endpoint-scaffold.md      # 你的 Skill 文件
        ├── api-testing.md
        └── api-documentation.md

技能组织原则:

• shared/ - 通用技能,多个 Subagent 共享
• {agent-name}/ - 专属技能,只被特定 Subagent 使用

---

💡 实战案例

案例 1: 电商 API 开发完整流程

场景: 用户想开发一个产品管理 API

用户: "帮我创建一个产品管理 API,支持增删改查操作"

主 Agent: "我来召唤 api-developer!"

api-developer (Subagent):
  → 读取 api-endpoint-scaffold skill
  → 使用 AskUserQuestion 收集信息
  → 用户回答: 模块名=product, 表名=products
  → 生成路由和控制器文件
  → 输出: ✅ API 脚手架已生成!

用户: "好的,现在实现具体功能"

api-developer:
  → 读取 api-testing skill
  → 编写单元测试
  → 实现 CRUD 方法
  → 添加参数校验和错误处理
  → 输出: ✅ 功能已实现!

用户: "生成 API 文档"

api-developer:
  → 读取 api-documentation skill
  → 分析代码生成 OpenAPI 规范
  → 创建 Swagger UI 文档
  → 生成 Postman Collection
  → 输出: ✅ API 文档已生成! (docs/product-api.yaml)

整个流程中:

• Subagent 负责专业领域(API 开发)
• Skills 提供标准操作流程(scaffold → testing → documentation)
• 用户 只需关注业务需求,不需要了解技术细节

案例 2: Git 提交规范

场景: 确保团队的 Git 提交符合规范

创建 shared skill:

# .claude/skills/shared/git-commit.md

---
name: git-commit
description: Git 提交规范和最佳实践指南
---

## 提交信息格式

### 标准格式

():

Type 类型

• feat: 新功能
• fix: 修复 bug
• docs: 文档变更
• refactor: 重构
• perf: 性能优化

示例

feat(calculator): add square root function

Add sqrt function to basic calculator plugin
- Supports non-negative numbers only
- Returns error for negative inputs

Closes #123

Agent 使用指南

1. 使用 git status 查看变更
2. 使用 git diff 查看具体改动
3. 根据变更内容确定 type
4. 编写清晰的 subject
5. 执行 git commit

**所有 Subagent 都可以引用这个 Skill:**

```markdown
# .claude/agents/frontend-engineer.md
skills: ["component-scaffold", "git-commit"]

# .claude/agents/backend-engineer.md
skills: ["api-scaffold", "git-commit"]

---

🎯 最佳实践

1. Subagent 设计原则

✅ 好的做法:

# 单一职责,边界清晰
name: frontend-engineer
description: 专注于 React 组件开发和前端性能优化

❌ 不好的做法:

# 职责模糊,什么都做
name: super-engineer
description: 全栈开发、运维、测试、文档、项目管理...

原则:

• 单一职责 - 一个 Subagent 只负责一个领域
• 明确边界 - 清楚地定义输入输出
• 工具最小化 - 只给必需的工具权限

2. Skills 设计原则

✅ 好的做法:

# 流程清晰,步骤明确
## Phase 1: 信息收集
**Step 1 - 收集基本信息**
**Step 2 - 收集工具定义**

## Phase 2: 文件生成
**Step 1 - 创建目录**
**Step 2 - 生成必需文件**

❌ 不好的做法:

# 流程模糊,缺少细节
## 创建插件
1. 收集信息
2. 生成文件
3. 完成

原则:

• 可操作性 - 每一步都有明确的工具调用
• 可复现性 - 任何人执行都能得到相同结果
• 可维护性 - 结构清晰,易于更新

3. 命名规范

类型	命名格式	示例
Subagent	{角色}-{领域}	frontend-engineer, api-developer
Shared Skill	{动作}-{对象}	git-commit, code-review
Exclusive Skill	{功能描述}	project-scaffold, packaging

4. 目录组织

.claude/
├── agents/                           # Subagent 配置
│   ├── frontend-engineer.md
│   ├── backend-engineer.md
│   └── api-developer.md
│
├── skills/
│   ├── shared/                       # 通用技能(多 Agent 共享)
│   │   ├── git-commit.md
│   │   ├── code-review.md
│   │   └── deployment.md
│   │
│   ├── frontend-engineer/            # 前端专属技能
│   │   ├── component-scaffold.md
│   │   └── css-optimization.md
│   │
│   ├── backend-engineer/             # 后端专属技能
│   │   ├── database-schema.md
│   │   └── database-migration.md
│   │
│   └── api-developer/                # API 开发专属技能
│       ├── api-endpoint-scaffold.md
│       ├── api-testing.md
│       └── api-documentation.md
│
└── settings.json                     # 全局配置

5. 技能复用策略

# 高复用技能 → shared/
- git-commit.md        (所有 Agent 都需要)
- code-review.md       (所有开发类 Agent)
- testing.md           (涉及测试的 Agent)

# 低复用技能 → {agent-name}/
- api-documentation.md (只有 api-developer 用)
- react-ssr.md         (只有 frontend-engineer 用)

6. 技能调用模式

在 Subagent 中明确说明什么时候读取技能:

## 技能使用指南

### api-endpoint-scaffold - API 端点脚手架生成
**触发时机**:
- 用户说"创建新 API"、"生成端点"、"初始化接口"

**执行步骤**:
1. 使用 `Read` 工具读取 `.claude/skills/api-developer/api-endpoint-scaffold.md`
2. 按照技能文件中的 Phase 1-3 标准流程执行

### api-testing - API 测试
**触发时机**:
- 用户说"测试 API"、"编写测试"、"单元测试"

**执行步骤**:
1. 使用 `Read` 工具读取 `.claude/skills/api-developer/api-testing.md`
2. 按照技能文件中的标准流程执行

---

🎓 总结

Subagent vs Skills 对比

维度	Subagent	Skills
本质	独立的 Agent 实例	可复用的操作手册
作用	扮演专业角色	提供标准流程
类比	公司的专家员工	员工的工作手册
数量	按领域划分(少量)	按任务划分(中量)
复用	不可复用(独立配置)	可复用(多 Agent 共享)
粒度	粗粒度(角色级)	细粒度(任务级)

关键要点

1. Subagent 定义"谁" - 角色和职责
2. Skills 定义"怎么做" - 具体操作流程
3. Subagent 调用 Skills - 专家使用手册完成工作
4. Skills 可以被多个 Subagent 共享 - 一本手册多人使用

何时使用?

使用 Subagent 当:

• 任务需要特定领域的专业知识
• 需要限制工具使用权限
• 想要清晰的角色分工

使用 Skills 当:

• 有标准化的操作流程
• 需要确保执行一致性
• 多个场景需要复用同一流程

开始你的第一个 Subagent/Skill!

# 1. 创建目录结构
mkdir -p .claude/agents
mkdir -p .claude/skills/shared

# 2. 创建你的第一个 Subagent
touch .claude/agents/my-first-agent.md

# 3. 创建你的第一个 Skill
touch .claude/skills/shared/my-first-skill.md

# 4. 开始编写...

---

📚 延伸阅读

• Claude Code 官方文档
• MCP 协议规范

---

记住: Subagent 和 Skills 不是黑魔法,它们只是帮你把复杂的工作流程结构化、标准化、自动化的工具。

开始小,迭代快,持续优化! 🚀