1. 为什么你的 Claude Code 需要 Superpowers 技能包如果你已经在用 Claude Code 写代码大概率遇到过这种情况让它加个登录功能它二话不说直接开始写app.post(/login)写到一半你才发现技术栈选错了、数据库字段对不上、认证方式也不是你想要的。返工的成本比从头写还高。Superpowers 就是来解决这个问题的。它是一套开源的 Agentic Skills 框架由前 Anthropic 工程师 Jesse VincentGitHub 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.mdSKILL.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 五阶段工作流对应的技能映射把技能和五阶段对应起来看结构就清晰了阶段主要技能作用Clarify 澄清brainstorming苏格拉底式提问澄清需求Design 设计brainstorming 后续生成结构化设计文档Plan 计划writing-plans拆分为 2-5 分钟小任务Code 编码test-driven-development、executing-plans、subagent-driven-developmentTDD 循环 分批执行Verify 验证requesting-code-review、verification-before-completion自动代码审查除了这五个阶段还有几个辅助技能using-git-worktrees负责隔离开发环境dispatching-parallel-agents负责并行调度子代理systematic-debugging负责系统化调试writing-skills是元技能用来写你自己的技能。理解了这个映射关系你就知道为什么 Superpowers 能强制Claude 按流程走了——每个阶段都有对应的技能在上下文里盯着。3. 安装与可复制配置片段这一章是实操核心。我会给出完整的安装命令、配置片段和验证方法你照着敲就行。3.1 官方市场安装推荐路径从 2026 年 1 月起Superpowers 已经入驻 Anthropic 官方插件市场。在 Claude Code 会话里直接输入/plugin install superpowersclaude-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 superpowerssuperpowers-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: 提取共享逻辑 再次运行测试 - 全部通过注意如果你不提及 TDDClaude 可能不会主动写测试。这个技能的作用是强制执行流程纪律确保测试不被遗忘。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 排查速查表报错/现象最可能原因处理401 UnauthorizedKey 错误或 Base URL 带多余路径用 curl 验证Base URL 用https://taotoken.net/apilocal proxy failed本地代理进程挂了检查 endpoint 配置去掉多余代理reading choices响应格式与模型不匹配确认 model 字段与返回格式一致OAuth token expired系统时间偏差校准系统时间重新登录技能不激活frontmatter 格式错误用最小技能测试worktree 技能失效权限未放行在 settings.json 加 allow 规则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 Weeks 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/apiKey 在控制台的 API Keys 页面生成模型 ID 按实际订阅填。配置完成后用第 4 章的验证流程走一遍确认技能能正常激活。需要生成 Key 的话直接去控制台的 API Keys 页面操作接入过程中遇到报错对照第 5 章的速查表排查想验证模型是否正常工作可以用模型对话页面发一条测试消息如果是长期编码或 Agent 场景Coding Plan 会更划算。文档页有完整的接入说明遇到配置问题可以先翻那里。