1. 为什么你的 Claude Code 需要 Superpowers 技能包

如果你已经在用 Claude Code 写代码，大概率遇到过这种情况：让它加个登录功能，它二话不说直接开始写app.post('/login')，写到一半你才发现技术栈选错了、数据库字段对不上、认证方式也不是你想要的。返工的成本比从头写还高。

Superpowers 就是来解决这个问题的。它是一套开源的 Agentic Skills 框架，由前 Anthropic 工程师 Jesse Vincent（GitHub @obra）创建，和 Anthropic 官方插件系统同期发布。它的核心理念只有一句话：技能赋予智能体超能力。注意，它不是给 Claude Code 加新功能，也不是换更强的模型，而是改变工作方法论——强制 Claude 在写代码之前，先走完 Clarify（澄清）→ Design（设计）→ Plan（计划）→ Code（编码）→ Verify（验证）五个阶段。

这套框架目前在 GitHub 上已经有约 167K Stars、6.7K Forks，内置 14+ 核心技能，MIT 协议开源。实测下来，中等复杂度任务能减少约 14% 的 API 调用，Opus 4.6 测试环境下成本节省约 9%。安装时间大概 30 秒。

这篇文章面向三类人：一是刚接触 Claude Code、想建立规范工作流的开发者；二是已经在用 Claude Code 但被"AI 乱写代码"困扰的人；三是想给团队定制专属技能、把工程规范固化下来的技术负责人。我会从技能包结构讲起，然后带你走完安装、启用、自定义技能编写、验证请求的完整流程，最后把常见的加载失败问题一个个拆开排查。

需要说明的是，Superpowers 本身是本地运行的技能框架，它不依赖任何特殊网络环境，所有技能文档都是 Markdown 文件，存在你的项目或用户目录里。下面所有操作都可以在普通开发机上完成。

2. Superpowers 技能包结构与加载机制解析

在动手安装之前，先搞清楚它的目录结构和加载逻辑，后面排查问题时你会感谢自己看了这一段。

2.1 技能包的目录长什么样

Superpowers 的每个技能本质上就是一个文件夹，里面放一个SKILL.md文件。安装后，技能文件通常落在两个位置之一：

• 用户级（User level）：~/.claude/plugins/superpowers/skills/
• 项目级（Project level）：<你的项目>/.claude/plugins/superpowers/skills/

每个技能目录的结构大致是这样：

skills/ ├── brainstorming/ │ └── SKILL.md ├── test-driven-development/ │ └── SKILL.md ├── systematic-debugging/ │ └── SKILL.md ├── writing-plans/ │ └── SKILL.md ├── executing-plans/ │ └── SKILL.md ├── using-git-worktrees/ │ └── SKILL.md ├── requesting-code-review/ │ └── SKILL.md └── writing-skills/ └── SKILL.md

SKILL.md的头部是 YAML frontmatter，用来声明技能名和触发描述，正文则是给 Claude 看的流程指令。一个典型的 frontmatter 长这样：

--- name: brainstorming description: Explores requirements through Socratic questioning before any code is written. Use when the user discusses a new feature or unclear requirement. ---

description字段非常关键——Claude Code 就是靠它来判断"当前上下文该不该激活这个技能"。写得越具体，触发越准。

2.2 加载机制：技能是怎么被"自动激活"的

Superpowers 的技能不是手动敲命令调用的，而是根据对话上下文自动激活。加载流程分三步：

第一步，Claude Code 启动时扫描插件目录，把所有SKILL.md的 frontmatter 读进内存，建立一张"技能名 → 触发描述"的索引表。

第二步，你每发一条消息，Claude 会把当前对话内容和索引表里的description做语义匹配。比如你说"帮我做个登录功能"，匹配到brainstorming的描述里有"new feature"，就会激活它。

第三步，激活后，该技能的SKILL.md正文被注入到当前上下文，Claude 按照里面的检查清单和流程执行。

这里有个容易踩的坑：技能激活依赖语义匹配，如果你把需求描述得太模糊，比如只说"改一下"，可能匹配不到任何技能，Claude 就退回默认的"直接写代码"模式。所以描述需求时尽量带上场景关键词。

2.3 五阶段工作流对应的技能映射

把技能和五阶段对应起来看，结构就清晰了：

除了这五个阶段，还有几个辅助技能：using-git-worktrees负责隔离开发环境，dispatching-parallel-agents负责并行调度子代理，systematic-debugging负责系统化调试，writing-skills是元技能，用来写你自己的技能。

理解了这个映射关系，你就知道为什么 Superpowers 能"强制"Claude 按流程走了——每个阶段都有对应的技能在上下文里盯着。

3. 安装与可复制配置片段

这一章是实操核心。我会给出完整的安装命令、配置片段和验证方法，你照着敲就行。

3.1 官方市场安装（推荐路径）

从 2026 年 1 月起，Superpowers 已经入驻 Anthropic 官方插件市场。在 Claude Code 会话里直接输入：

/plugin install superpowers@claude-plugins-official

安装时 Claude Code 会问你安装级别，两个选项：

• User level (Global)：全局生效，所有项目和会话自动可用。推荐选这个。
• Project level：仅当前项目生效，适合先测试再全局安装。

如果你只是想先试试水，选 Project level；确认好用之后再重装成 User level。

3.2 社区市场安装（备选路径）

如果官方市场因为版本原因搜不到，可以走社区市场：

# 步骤 1：注册 Superpowers 市场源 /plugin marketplace add obra/superpowers-marketplace # 步骤 2：安装插件 /plugin install superpowers@superpowers-marketplace

两条命令都在 Claude Code 会话内执行，不需要退出到终端。

3.3 验证安装是否成功

安装完成后，运行：

/plugin list

输出里应该能看到superpowers这一项。如果看到了，重启一次 Claude Code 会话，技能就会自动生效。

3.4 关键配置片段：settings 与技能路径

如果你需要手动指定技能目录（比如团队共享技能库），可以在项目的.claude/settings.json里配置。下面是一个可复制的片段：

{ "plugins": { "superpowers": { "enabled": true, "skillsPath": ".claude/plugins/superpowers/skills", "autoActivate": true } }, "permissions": { "allow": [ "Read(.claude/plugins/superpowers/**)", "Bash(git worktree:*)" ] } }

几个字段说明：enabled控制插件开关；skillsPath指向技能目录，团队可以把技能库放在共享仓库里再软链过来；autoActivate打开自动激活；permissions.allow里放行技能目录读取和 git worktree 命令，否则using-git-worktrees技能会因为权限被拦。

如果你用的是 Codex CLI 或 Cline 这类兼容工具，配置思路类似，但字段名不同。以 Codex 的auth.json为例，接入时需要写全三件套——Base URL、Key、Model ID：

{ "base_url": "https://taotoken.net/api", "api_key": "sk-你的密钥", "model": "claude-sonnet-4-5" }

注意 Base URL 用https://taotoken.net/api，不要带任何多余路径。Key 在控制台的 API Keys 页面生成，模型 ID 按你实际订阅的填。

3.5 兼容性说明

Superpowers 不只支持 Claude Code，还兼容 Cursor、OpenAI Codex CLI、OpenCode、GitHub Copilot CLI、Gemini CLI。不同平台的技能目录位置略有差异，但SKILL.md的格式是通用的。跨平台使用时，把技能目录软链到对应平台的插件路径即可。

4. 验证请求与成功结果

装完不等于跑通。这一章给你一套可复制的验证流程，确认技能真的在工作。

4.1 第一步：确认技能列表加载

在 Claude Code 里输入/，你应该能看到以superpowers:开头的命令：

/superpowers:brainstorm # 交互式设计细化 /superpowers:write-plan # 创建实现计划 /superpowers:execute-plan # 使用子代理执行计划

如果这三个命令出现了，说明技能包已经加载成功。如果只看到部分，说明某些SKILL.md的 frontmatter 有问题，去第 5 章排查。

4.2 第二步：触发 brainstorming 验证自动激活

发一条测试消息，比如：

帮我做一个待办事项的 API

正常情况下，Claude 不会直接开始写代码，而是回复类似：

我将使用 brainstorming 技能来探索这个功能。 首先，让我问几个澄清问题： 1. 这个 API 是给哪个项目用的？还是全新项目？ 2. 你希望用什么技术栈？ 3. 数据存储用数据库还是内存？ 4. 需要哪些端点？（增删改查是否都要） 5. 是否需要用户认证？

如果 Claude 直接开始写app.get('/todos')，说明 brainstorming 没被激活。检查两点：一是技能是否真的安装成功（回到 3.3 验证），二是你的需求描述是否太模糊导致语义匹配失败。

4.3 第三步：验证 TDD 技能强制生效

发一条明确带 TDD 关键词的消息：

使用 TDD 实现用户认证模块

预期行为是 Claude 先写测试、运行确认失败（RED），再写最小实现、运行确认通过（GREEN），最后重构（REFACTOR）。你会看到类似输出：

激活 test-driven-development 技能 🔴 RED: 编写用户名/密码验证测试 运行测试 - 全部失败（预期） 🟢 GREEN: 编写最小实现 运行测试 - 全部通过 🔵 REFACTOR: 提取共享逻辑 再次运行测试 - 全部通过

注意：如果你不提及 TDD，Claude 可能不会主动写测试。这个技能的作用是强制执行流程纪律，确保测试不被"遗忘"。

4.4 第四步：验证 Git Worktree 隔离

当任务涉及多文件改动时，using-git-worktrees会自动激活。你可以在另一个终端窗口运行：

git worktree list

应该能看到类似输出：

/path/to/project abc1234 [main] /path/to/project-feature def5678 [feature-branch]

这说明 Claude 在隔离的 worktree 里工作，main 分支保持干净。任务完成后，worktree 会被自动清理。

4.5 第五步：验证代码审查触发

所有任务完成后，requesting-code-review会自动激活，输出一份审查报告，包含代码质量、安全性、测试覆盖率三块。看到类似下面的结构就说明验证链路完整：

## Code Review Report ### 代码质量 ### 安全性 ### 测试覆盖率 ### 结论：代码质量良好，可以合并

走到这一步，说明从安装到自动激活的完整链路都通了。

5. 常见加载失败排查

这一章对照真实报错来。我把踩过的坑按报错类型整理成表，你对着查。

5.1 报错：401 Unauthorized

这是最常见的接入问题，通常出现在你通过 API 方式调用模型时。原因有三类：

第一，Key 没填对。检查auth.json或环境变量里的api_key是否完整，有没有多余空格。第二，Base URL 写错了。正确写法是https://taotoken.net/api，不要写成https://taotoken.net/api/v1或带其他后缀。第三，Key 过期或被禁用，去控制台的 API Keys 页面重新生成一个。

排查命令：

curl -X POST https://taotoken.net/api/v1/messages \ -H "Authorization: Bearer sk-你的密钥" \ -H "Content-Type: application/json" \ -d '{"model":"claude-sonnet-4-5","max_tokens":50,"messages":[{"role":"user","content":"hi"}]}'

如果这条 curl 返回 200，说明 Key 和 Base URL 都没问题，问题在 Claude Code 的配置层。

5.2 报错：local proxy failed

这个报错说明本地代理层没起来。Superpowers 本身不需要代理，但如果你在 Claude Code 里配置了自定义 endpoint，代理进程挂了就会报这个。

排查步骤：先确认没有残留的代理进程占用端口，然后检查.claude/settings.json里的 endpoint 配置是否指向了正确的地址。如果你用的是 TaoToken 的 API，直接填https://taotoken.net/api即可，不需要额外起本地代理。

5.3 报错：reading choices 相关错误

这类报错通常出现在响应解析阶段，提示reading 'choices'或类似字段找不到。原因是返回的 JSON 结构和你配置的模型格式不匹配。比如你按 OpenAI 格式解析，但实际返回的是 Anthropic 格式。

解决办法：确认auth.json里的model字段和实际调用的模型一致。Claude 系列模型走 Anthropic 格式，返回字段是content而不是choices。如果你混用了格式，解析就会失败。

5.4 报错：OAuth 相关失败

如果你用 OAuth 方式登录 Claude Code，偶尔会遇到 token 刷新失败。表现是会话突然中断，提示 OAuth token expired。

处理方式：退出当前会话，重新执行登录流程。如果频繁出现，检查系统时间是否准确——OAuth 对时间戳敏感，系统时间偏差超过几分钟就会导致签名校验失败。

5.5 技能不激活（无报错但行为不对）

这是最隐蔽的一类问题：没有任何报错，但 Claude 就是不按技能流程走。原因通常是SKILL.md的 frontmatter 格式有问题。

检查清单：

• name字段是否和目录名一致
• description是否包含明确的触发场景关键词
• YAML 的---分隔符是否成对出现
• 文件编码是否是 UTF-8（带 BOM 会导致解析失败）

你可以用一个最小技能测试：

--- name: test-skill description: Use when the user says the exact phrase "activate test skill". --- # Test Skill When activated, reply with "test skill activated".

然后发消息"activate test skill"，如果 Claude 回复了指定内容，说明加载机制正常，问题出在原来那个技能的 frontmatter 上。

5.6 权限被拦导致技能失效

using-git-worktrees和dispatching-parallel-agents需要执行 git 命令和创建子进程。如果.claude/settings.json的permissions.allow里没放行，技能会静默失败。

对照第 3.4 节的配置片段，确保这两条在 allow 列表里：

"Bash(git worktree:*)", "Read(.claude/plugins/superpowers/**)"

5.7 排查速查表

6. 自定义技能编写与长期使用建议

跑通内置技能之后，真正的价值在于写你自己的技能。这一章给你一个可复制的自定义技能模板，以及长期使用的配置建议。

6.1 自定义技能的最小模板

在~/.claude/plugins/superpowers/skills/下新建一个目录，比如team-report，里面放SKILL.md：

--- name: team-report description: Creates standardized weekly team updates. Use when the user wants a team status report or weekly update. --- # Weekly Team Update Skill ## Instructions When creating a weekly team update, follow this structure: 1. **Wins This Week**: 3-5 bullet points of accomplishments 2. **Challenges**: 2-3 current blockers or concerns 3. **Next Week's Focus**: 3 key priorities 4. **Requests**: What the team needs from others ## Tone - Professional but conversational - Specific with metrics where possible - Solution-oriented on challenges

保存后重启会话，发消息"帮我写这周的团队周报"，技能就会被激活。

6.2 写技能的三条经验

第一，description要写"什么时候用"，不是"这是什么"。对比一下：description: A skill for reports几乎不会触发；description: Use when the user wants a team status report or weekly update触发率高得多。

第二，正文用检查清单而不是大段说明。Claude 对结构化清单的执行率明显高于散文式描述。

第三，给技能加"红旗警示"。比如在 TDD 技能里写一句"如果你发现自己想跳过测试直接写实现，停下来"——这种负面约束能有效防止 Claude 走捷径。

6.3 长期使用的配置建议

全局安装优先。选 User level 安装，避免每个项目重复配置。团队共享的话，把技能库放在一个 git 仓库里，各成员软链到自己的~/.claude/plugins/superpowers/skills/。

善用暂停机制。executing-plans的暂停设计是让你在每个任务后验证方向，别嫌烦，方向错了返工成本更高。

结合 Routine 做自动化。把技能驱动的工作流提升为 Claude Code Routine，可以实现定时触发，比如每天早上自动跑一遍代码审查技能。

6.4 什么时候不该用 Superpowers

不是所有场景都适合。快速原型阶段，速度比质量重要，走完整五阶段反而拖慢节奏；现有代码库的小改动，不值得完整规范的 overhead；需要和 AI 紧密互动的即时协作场景，暂停确认机制会打断心流。

有个数据可以参考：简单任务使用 Superpowers 反而会增加约 8% 的 token 开销。所以判断标准很简单——任务复杂度是否值得走完整流程。

6.5 接入配置速查

如果你需要把 Superpowers 和 TaoToken 的 API 配合使用，核心配置就三件套：

{ "base_url": "https://taotoken.net/api", "api_key": "sk-在控制台生成", "model": "claude-sonnet-4-5" }

Base URL 固定用https://taotoken.net/api，Key 在控制台的 API Keys 页面生成，模型 ID 按实际订阅填。配置完成后，用第 4 章的验证流程走一遍，确认技能能正常激活。

需要生成 Key 的话，直接去控制台的 API Keys 页面操作；接入过程中遇到报错，对照第 5 章的速查表排查；想验证模型是否正常工作，可以用模型对话页面发一条测试消息；如果是长期编码或 Agent 场景，Coding Plan 会更划算。文档页有完整的接入说明，遇到配置问题可以先翻那里。