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

Wed, 29 Apr 2026 10:30:00 +0800

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

一、Agent Skill 概述

1.1 核心定义

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

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

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

1.2 学习背景与价值

为什么学习 Agent Skill？

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

适用场景：

复杂功能开发（需要 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 等高级技能

行业应用现状：

企业类型	应用场景	使用技能
初创公司	快速迭代开发	brainstorming + verification
中大型企业	规范流程管理	TDD + code review + finishing-branch
远程团队	协作质量保证	requesting-code-review + receiving-code-review
技术团队	复杂系统重构	systematic-debugging + executing-plans

二、技能分类体系

2.1 技能分类概览

Agent Skill 可分为四大类别：

类别	技能数量	核心作用	优先级
流程类	3	决定如何做事（思考方式）	最高
执行类	3	执行计划和处理任务	高
验证类	3	质量保证和合规检查	高
工具类	4	辅助功能和配置	中

2.2 流程类技能（Process Skills）

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

2.2.1 brainstorming（创意工作）

触发场景：

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

核心原则：

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

2.2.2 systematic-debugging（系统调试）

触发场景：

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

核心原则：

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

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

触发场景：

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

核心原则：

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

2.3 执行类技能（Execution Skills）

2.3.1 executing-plans

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

使用方式：

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

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

核心检查项：

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

2.4.2 requesting-code-review

触发场景：

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

2.4.3 receiving-code-review

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

核心原则：

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

2.5 工具类技能（Utility Skills）

技能名	用途	使用频率
`simplify`	代码质量审查	中
`loop`	定期循环执行命令	低
`update-config`	Claude Code 配置	低
`claude-api`	Claude API 开发	低

三、核心使用规则

3.1 触发规则（1% 规则）

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

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

错误思维	实际情况
“这只是个小问题”	小问题也可能有技能适用
“我需要先探索一下”	技能告诉你如何探索
“我已经知道怎么做”	技能可能提供更好方法
“太简单了不需要”	简单任务也可能需要验证

正确思维流程：

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

3.2 技能优先级

优先级矩阵：

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

说明：

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

3.3 技能调用方式

使用 Skill 工具：

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

命令行格式：

`1`	`/skill superpowers:brainstorming`

3.4 技能选择流程

决策树：

任务类型 → 推荐技能

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

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

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

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

4.3 多任务并行流程

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

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

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

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

五、技能详解

5.1 brainstorming 技能

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

使用流程：

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

输出产物：

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

5.2 systematic-debugging 技能

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

步骤：

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

常用命令：

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

# 检查配置
git diff HEAD~5

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

5.3 verification-before-completion 技能

检查清单：

检查项	通过标准
编译/运行	无错误，无警告
功能测试	所有用例通过
边界条件	极端输入正常处理
副作用	无意外的状态变更
性能	响应时间在可接受范围

六、常见问题与解决方案

6.1 何时必须使用技能

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

解决方案：

场景	所需技能
开始新功能	brainstorming
写代码实现	test-driven-development
声称完成	verification-before-completion
遇到报错	systematic-debugging
代码提交	requesting-code-review
收到反馈	receiving-code-review
多个任务并行	dispatching-parallel-agents

6.2 技能冲突处理

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

解决方案：

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

6.3 技能执行中断

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

解决方案：

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

七、学习总结

7.1 核心收获

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

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

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

7.3 后续学习计划

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

八、资源推荐

8.1 官方文档

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

8.2 学习资源

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

8.3 社区资源

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

修订记录

修订时间	修订内容	修订人	备注
2026-04-29	首次发布	Claude	基于官方文档整理

AI工具 on Zell Blog

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

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

一、Agent Skill 概述

1.1 核心定义

1.2 学习背景与价值

1.3 发展历程与行业应用

二、技能分类体系

2.1 技能分类概览

2.2 流程类技能（Process Skills）

2.2.1 brainstorming（创意工作）

2.2.2 systematic-debugging（系统调试）

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

2.3 执行类技能（Execution Skills）

2.3.1 executing-plans

2.3.2 subagent-driven-development

2.3.3 dispatching-parallel-agents

2.4 验证类技能（Verification Skills）

2.4.1 verification-before-completion

2.4.2 requesting-code-review

2.4.3 receiving-code-review

2.5 工具类技能（Utility Skills）

三、核心使用规则

3.1 触发规则（1% 规则）

3.2 技能优先级

3.3 技能调用方式

3.4 技能选择流程

四、典型工作流

4.1 功能开发完整流程

4.2 Bug 修复流程

4.3 多任务并行流程

五、技能详解

5.1 brainstorming 技能

5.2 systematic-debugging 技能

5.3 verification-before-completion 技能

六、常见问题与解决方案

6.1 何时必须使用技能

6.2 技能冲突处理

6.3 技能执行中断

七、学习总结

7.1 核心收获

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

7.3 后续学习计划

八、资源推荐

8.1 官方文档

8.2 学习资源

8.3 社区资源

修订记录