★ FEATURED ARTICLE 1. 为什么你的 Cursor Agent 总是「一上来就写码」如果你已经在用 Cursor 的 Agent 模式或者 Claude Code 写代码大概率遇到过这种场景你只说了一句「帮我做个待办列表」它立刻开始噼里啪啦生成组件、写样式、装依赖等你反应过来它已经写了三百行但技术选型不是你想要的目录结构也和你项目对不上。你只能推翻重来或者硬着头皮在它的基础上改。这不是模型不够聪明而是缺少一层「行为规范」。Superpowers 就是干这个的它不是模型也不是插件市场里的花哨工具而是一套挂在宿主Cursor、Claude Code、Codex里的技能库把 TDD、调试、设计对齐、拆计划、代码评审这些工程实践写成智能体可读、可复用的操作规程。核心载体是skills/技能名/SKILL.mdYAML 头里带name和description宿主在会话启动时先扫描技能目录命中触发条件就强制加载对应流程。它适合谁已经用 Cursor Agent 或 Claude Code 做日常开发、希望流程稳定可复盘的工程师和小团队。不太适合只问一两个语法点的短对话也不适合坚持完全自定义提示、不愿被技能抢占流程的人。我试过在几个中型项目里挂载它最直观的变化是Agent 不再急着写代码而是先问你成功标准是什么、要不要落一份设计文档。这篇会从目录结构、触发条件、可复制配置讲到一次完整的安装验证帮你判断技能到底有没有被正确加载。涉及模型调用和 Key 管理的地方我会用 TaoToken 的接入方式做演示因为它的 API 兼容性好配置起来不折腾。2. Superpowers 技能目录结构与触发条件详解要判断技能有没有生效先得知道它长什么样。Superpowers 的仓库结构大致分几层插件入口、会话钩子、技能本体、子 Agent 人设、文档落盘区。下面这张表是我整理的核心路径对照你可以直接拿去核对本地目录。类别代表路径作用插件入口.cursor-plugin/plugin.json、.claude-plugin/、.codex-plugin/多宿主声明告诉宿主去哪加载技能会话钩子hooks/session-startbootstrap会话启动即注入「必须先考虑技能」的行为技能本体skills/*/SKILL.md各主题操作规程核心中的核心子 Agentagents/code-reviewer.md评审向 Agent 人设文档样例docs/superpowers/specs/、plans/设计稿与实现计划默认落盘区每个SKILL.md的 YAML 头是关键。name是技能标识description决定触发时机。比如brainstorming的 description 里会写「动工前澄清意图、对比方案」当你的输入包含「做个」「实现一个」这类模糊需求时宿主就会命中它。using-superpowers是元技能约定何时必须调用 Skill、与用户指令的优先级、各宿主挂载方式的差异。触发逻辑不是关键词硬匹配而是宿主把技能列表和 description 一起塞进系统提示模型在规划阶段先检索「有没有适用技能」有就加载并遵照。这意味着技能是强制流程不是泛泛建议。旧版的commands/brainstorm.md、write-plan.md、execute-plan.md已经 Deprecated现在统一走技能目录别再照着老教程配 commands 了。内置技能分两类。流程与设计类包括using-superpowers、brainstorming、writing-plans、executing-plans、subagent-driven-development、dispatching-parallel-agents、using-git-worktrees。质量与收尾类包括test-driven-development、systematic-debugging、verification-before-completion、requesting-code-review、receiving-code-review、finishing-a-development-branch、writing-skills。你不需要一次全用按项目阶段挑几个挂上就行。3. 在 Cursor 与 Claude Code 中挂载技能的完整配置这一节是重点配置写不对技能永远不会触发。先讲 Cursor再讲 Claude Code最后给一份通用的 settings 片段。Cursor 的挂载靠.cursor-plugin/plugin.json加sessionStart钩子。在项目根目录建.cursor-plugin/plugin.json内容如下{ name: superpowers, version: 1.0.0, skills: [skills], agents: [agents], hooks: { sessionStart: hooks/session-start } }skills指向技能根目录agents指向子 Agent 人设sessionStart是会话启动钩子负责注入「先找技能」的行为。配好后重启 Cursor新开会话时钩子会执行。Claude Code 的挂载走.claude-plugin/目录结构类似但入口文件名和字段略有差异。在项目根建.claude-plugin/plugin.json{ name: superpowers, skillsDir: skills, agentsDir: agents, hooks: { SessionStart: hooks/session-start } }注意 Claude Code 的钩子字段首字母大写这是它和 Cursor 的一个小区别写错了钩子不触发。如果你同时用两个宿主可以两个目录都保留互不干扰。模型接入部分我用 TaoToken 的 API 做演示。它的 Base URL 是https://taotoken.net/apiKey 在控制台生成。在 Cursor 的模型设置里填{ baseUrl: https://taotoken.net/api, apiKey: sk-你的Key, model: claude-sonnet-4-20250514 }Claude Code 则在~/.claude/settings.json或项目级.claude/settings.json里配{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的Key, ANTHROPIC_MODEL: claude-sonnet-4-20250514 } }三件套齐了Base URL、Key、Model ID。少任何一个请求都会失败。Key 去https://taotoken.net/api-keys生成模型对话可以在https://taotoken.net/chat先试通再写进配置。长期跑编码任务的话Coding Plan 更划算地址是https://taotoken.net/coding-plan。配完别急着写业务代码先做一次验证下一节讲。4. 验证技能是否被正确加载的实测步骤配置写完不代表生效得用一次真实请求验证。我踩过的坑是plugin.json 写对了但钩子路径写错技能列表根本没进系统提示Agent 行为跟没挂载一样。验证分三步。第一步确认技能目录被扫描到。在 Cursor 里新开一个会话输入列出当前可用的 skills如果挂载成功Agent 会返回using-superpowers、brainstorming、writing-plans等技能名和 description。如果它说「没有可用技能」或者答非所问说明 plugin.json 的skills路径不对或者钩子没执行。第二步触发一个具体技能。输入一句模糊需求帮我做一个 React 待办列表支持新增和勾选完成挂载成功时Agent 不会直接写组件而是先走brainstorming问你成功标准、技术取舍、要不要落设计文档。它会说类似「在动工前我想先确认几个点」然后把设计写到docs/superpowers/specs/下。如果它直接开始生成代码说明技能没命中回去检查brainstorming的 description 是否被正确加载。第三步验证落盘。看项目里有没有生成docs/superpowers/specs/目录和对应的设计文件。有说明流程走通了没有说明技能加载了但执行被跳过可能是模型没遵循强制流程换个模型或检查系统提示注入。用 TaoToken 的模型对话页面https://taotoken.net/chat可以先单独测模型连通性排除是 Key 或 Base URL 的问题。如果那边正常Cursor 里不正常问题一定在插件配置或钩子。实测下来三步都过技能就算正确加载了。之后每次新会话钩子都会重新注入不用重复配置。5. 常见报错排查401、local proxy failed 与技能不触发配置过程中最容易撞的几个错我按真实报错整理成对照表方便你直接定位。报错原因处理401 UnauthorizedKey 无效或没带上检查ANTHROPIC_API_KEY是否填对去https://taotoken.net/api-keys重新生成local proxy failedBase URL 写错或网络不通确认是https://taotoken.net/api不要带多余路径reading choices 报错响应格式不匹配检查 Model ID 是否拼错换claude-sonnet-4-20250514试OAuth 相关报错用了 OAuth 流程但配置不完整改用 API Key 方式别混用技能不触发plugin.json 路径错或钩子没执行核对skills路径重启宿主新开会话401最常见九成是 Key 没填或者填了带空格的。local proxy failed通常是 Base URL 多写了/v1或者少了https。reading choices是响应结构对不上多半是 Model ID 写错。OAuth 报错在 Claude Code 里出现说明你走了 OAuth 但没配全直接切 API Key 最省事。技能不触发是另一类问题跟网络无关。先确认.cursor-plugin/plugin.json或.claude-plugin/plugin.json在项目根目录不在的话宿主扫不到。再确认hooks/session-start文件存在且可执行。最后新开会话旧会话不会重新加载钩子。如果用了 CC Switch 或 Cline MCP 这类工具记得三件套写全Base URL、Key、Model ID。Codex 的auth.json里也是同样三个字段缺一个就连不上。排障时优先看 API Keys 页面和接入文档地址分别是https://taotoken.net/api-keys和https://taotoken.net/doc。6. 把技能接进日常开发流从验证到长期使用验证通过后怎么把它变成日常习惯我的做法是分阶段挂载不要一次全开。新项目启动时挂brainstorming和writing-plans强制先对齐设计和拆任务。进入编码阶段挂test-driven-development和subagent-driven-development让红绿重构和子 Agent 审查跑起来。收尾阶段挂requesting-code-review和finishing-a-development-branch把评审和分支清理做成清单。并行任务多的时候dispatching-parallel-agents很有用但前提是计划已经定好任务之间没有强顺序依赖。否则并行子 Agent 会互相踩汇总时一团乱。using-git-worktrees配合它做分支隔离基线测试先跑绿再并行。长期跑编码和 Agent 任务Coding Plan 比按量付费稳地址https://taotoken.net/coding-plan。模型对话调试用https://taotoken.net/chat接入文档在https://taotoken.net/docKey 管理在https://taotoken.net/api-keys。Claude Code 相关的接入细节可以看https://taotoken.net/claude-code-anthropic。最后说个实用技巧技能不是越多越好。挂太多系统提示变长模型注意力被稀释反而容易跳过关键流程。按项目阶段挑三到五个用完再换比一次性全挂效果好。技能生效的标志不是它出现在列表里而是 Agent 真的按流程走了——先问、再设计、后编码、最后验证。你可以在第一次触发时盯着它有没有落盘设计文档有就说明这套机制在你项目里跑起来了。
阅读完成 · 觉得有帮助？
