Agent Skill 使用指南 - 知识点总结

一、Agent Skill 概述

1.1 核心定义

Agent Skill 是 Claude Code 的扩展能力集，是预定义的工作流程模板和最佳实践集合。这些技能以结构化的方式引导用户完成特定任务，确保在开发过程中遵循统一的规范和流程。Skill 本质上是一种元工具，它告诉 AI 在什么场景下应该如何思考和行动，而非执行具体的代码操作。

Agent Skill 的核心价值在于：将专家经验封装为可复用的工作流程，使 AI 能够在特定场景下表现出专家级的判断力和执行力。

! 警示：Agent Skill 是 Claude Code 的内置机制，不可单独下载或安装，只能通过 Skill 工具调用。

1.2 学习背景与价值

为什么学习 Agent Skill？

1. 提升开发效率：通过结构化的工作流，避免重复试错，直接调用经过验证的最佳实践
2. 保证工作质量：在关键节点（如完成前验证、代码审查）强制检查，确保交付质量
3. 统一团队规范：所有成员使用相同的技能流程，输出一致性的结果
4. 降低认知负担：不需要记住所有细节，技能会引导你完成每个步骤

适用场景：

• 复杂功能开发（需要 brainstorming → planning → implementation → review）
• Bug 修复（需要 systematic debugging 避免盲目试错）
• 多任务并行处理（需要 dispatching-parallel-agents）
• 关键里程碑完成（需要 verification-before-completion）

1.3 发展历程与行业应用

技术演进：

• 2024 年：Superpowers 技能集首次发布，包含基础的 brainstorming 和 debugging 技能
• 2025 年：扩展至 TDD、code review、parallel execution 等场景
• 2026 年：新增 subagent-driven-development、finishing-a-development-branch 等高级技能

行业应用现状：

二、技能分类体系

2.1 技能分类概览

Agent Skill 可分为四大类别：

2.2 流程类技能（Process Skills）

定义：决定「如何做」的技能，优先于任何实现工作。

2.2.1 brainstorming（创意工作）

触发场景：

• 创建新功能
• 设计系统架构
• 提出解决方案
• 任何需要「先想清楚」的场景

核心原则：

1. 探索用户意图，不直接跳入实现
2. 分析需求和约束条件
3. 设计多个可行方案
4. 选择最优路径

2.2.2 systematic-debugging（系统调试）

触发场景：

• 遇到 bug 或错误
• 测试失败
• 行为不符合预期

核心原则：

1. 不盲目猜测原因
2. 系统性收集信息
3. 形成假设并验证
4. 追踪根本原因

2.2.3 test-driven-development（测试驱动开发）

触发场景：

• 实现任何新功能
• 修复任何 bug

核心原则：

1. 先写测试，再写实现
2. 小步快走，快速反馈
3. 重构不改变行为

2.3 执行类技能（Execution Skills）

2.3.1 executing-plans

触发场景：有书面实现计划需要执行时。

使用方式：

1
2
3
4

1. 阅读计划文档
2. 按步骤执行
3. 在检查点验证
4. 处理偏差

2.3.2 subagent-driven-development

触发场景：任务可分解为独立子任务时。

核心优势：

• 并行处理多个独立任务
• 隔离复杂任务的上下文
• 充分利用多核资源

2.3.3 dispatching-parallel-agents

触发场景：2+ 个独立任务需要同时处理。

前置条件：

• 任务间无共享状态
• 无顺序依赖

2.4 验证类技能（Verification Skills）

2.4.1 verification-before-completion

触发场景：声称工作完成前。

核心检查项：

1. 代码是否编译/运行通过
2. 功能是否满足需求
3. 边界条件是否处理
4. 是否有副作用

2.4.2 requesting-code-review

触发场景：

• 完成任务后
• 实现重要功能后
• 合并前

2.4.3 receiving-code-review

触发场景：收到代码审查反馈时。

核心原则：

1. 不盲目接受，也不盲目拒绝
2. 理解反馈的技术依据
3. 验证假设的正确性

2.5 工具类技能（Utility Skills）

三、核心使用规则

3.1 触发规则（1% 规则）

规则内容：只要有 1% 的可能性某个技能适用，就必须调用它检查。

违反示例（需避免的思维）：

正确思维流程：

1
2
3
4
5

收到任务 → 是否有技能可能适用？ → 是 → 调用 Skill 工具
                                         ↓
                                         否 → 继续
                                         ↓
                                    直接响应

3.2 技能优先级

优先级矩阵：

1

用户显式指令 > Superpowers 技能 > 默认系统提示

说明：

• 用户在 CLAUDE.md 等文件中明确指定的指令具有最高优先级
• 如果 CLAUDE.md 说「不要用 TDD」，但 skill 说「要用 TDD」，遵循用户指令
• 默认系统提示的优先级最低

3.3 技能调用方式

使用 Skill 工具：

1
2
3
4
5
6

{
  "tool": "Skill",
  "parameters": {
    "skill": "superpowers:brainstorming"
  }
}

命令行格式：

1

/skill superpowers:brainstorming

3.4 技能选择流程

决策树：

1
2
3
4
5
6
7
8
9

任务类型 → 推荐技能

新建功能 → brainstorming → test-driven-development → verification
Bug 修复 → systematic-debugging → verification
有计划 → executing-plans
多任务 → dispatching-parallel-agents → subagent-driven-development
完成前 → verification-before-completion
代码审查 → requesting-code-review / receiving-code-review
分支完成 → finishing-a-development-branch

四、典型工作流

4.1 功能开发完整流程

场景：开发一个新的用户认证功能

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

1. brainstorming
   - 明确需求：用户名密码登录、第三方登录、Token 刷新
   - 分析约束：安全性要求、会话管理、API 兼容性
   - 设计方案：方案 A（传统 Session）、方案 B（JWT）
   - 选择路径：基于项目现状选择 JWT

2. test-driven-development
   - 编写登录测试用例
   - 编写 Token 刷新测试用例
   - 编写注销测试用例

3. 实现功能
   - 按测试要求实现
   - 确保所有测试通过

4. verification-before-completion
   - 运行完整测试套件
   - 检查代码覆盖率
   - 验证边界条件

5. requesting-code-review
   - 提交代码
   - 请求团队审查
   - 处理反馈

6. finishing-a-development-branch
   - 合并到主分支
   - 清理开发分支

4.2 Bug 修复流程

场景：用户反馈登录后有时会莫名掉线

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

1. systematic-debugging
   - 收集信息：复现步骤、日志、用户环境
   - 形成假设：Token 过期、服务器重启、缓存问题
   - 验证假设：通过日志分析确认是 Token 刷新竞态条件
   - 定位根因：并发请求时 Token 刷新逻辑有 TOCTOU 问题

2. 修复代码
   - 添加分布式锁
   - 重构 Token 刷新逻辑

3. verification-before-completion
   - 编写回归测试
   - 压力测试并发场景
   - 验证修复有效

4. requesting-code-review
   - 提交修复
   - 请求审查

4.3 多任务并行流程

场景：同时开发用户模块和订单模块

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

1. dispatching-parallel-agents
   - 分析任务依赖关系
   - 识别独立任务

2. subagent-driven-development
   - Agent 1：处理用户模块
   - Agent 2：处理订单模块
   - 并行执行

3. 汇总结果
   - 验证两个模块
   - 集成测试

五、技能详解

5.1 brainstorming 技能

触发时机：任何创意性工作前（创建功能、修改行为、设计方案）

使用流程：

1. 探索意图：理解用户真正想要什么
2. 分析需求：功能需求、非功能需求、约束条件
3. 设计方案：提出多个可行方案
4. 选择路径：推荐最优方案

输出产物：

• 明确的需求描述
• 设计方案决策
• 实现路径规划

5.2 systematic-debugging 技能

核心思想：不盲目猜测，通过系统化方法定位问题。

步骤：

1. 收集信息：错误信息、环境配置、复现步骤
2. 形成假设：基于信息的合理推断
3. 验证假设：设计实验验证
4. 定位根因：找到真正的 bug 源头
5. 修复验证：确保修复有效

常用命令：

1
2
3
4
5
6
7
8

# 查看错误日志
git log --oneline -20

# 检查配置
git diff HEAD~5

# 对比正常和异常状态
git stash list

5.3 verification-before-completion 技能

检查清单：

六、常见问题与解决方案

6.1 何时必须使用技能

问题：如何判断是否需要使用技能？

解决方案：

6.2 技能冲突处理

问题：多个技能同时适用怎么办？

解决方案：

1. 流程技能优先于实现技能
2. 验证技能优先于执行技能
3. 优先级相同时，选择最具体的技能

6.3 技能执行中断

问题：执行技能过程中被打断怎么办？

解决方案：

1. 记录当前步骤
2. 使用 TaskCreate 创建待办事项
3. 继续时从中断处恢复
4. 使用 TaskList 查看进度

七、学习总结

7.1 核心收获

1. Agent Skill 是结构化的工作流：不是命令，而是指导 AI 如何思考和行动的框架
2. 1% 触发规则：宁可多检查，不可漏过任何可能的适用场景
3. 流程优先于实现：先确定方法，再执行操作
4. 验证是质量保障：任何「完成」前都必须验证
5. 技能可组合使用：复杂场景需要多个技能配合

7.2 未掌握知识点（待深入）

• finishing-a-development-branch 的具体分支清理策略
• subagent-driven-development 的上下文隔离机制
• loop 技能与 Cron 任务的结合使用

7.3 后续学习计划

1. 本周：熟悉所有技能的触发时机
2. 下周：在项目中实践 TDD 工作流
3. 下月：掌握多代理并行处理

八、资源推荐

8.1 官方文档

• Claude Code 官方文档 — 最权威的 Agent Skill 使用说明
• Superpowers 技能集 — 所有技能的源码和说明

8.2 学习资源

• B 站：Claude Code 入门教程 — 视频演示适合入门
• GitHub：claude-code-examples — 实战案例集合

8.3 社区资源

• Claude Code Discord — 社区讨论和问题解答
• GitHub Issues — 问题反馈和功能建议

修订记录