1. 三个月深度使用后的真实体感187K star这个数字放在任何一个开源项目上都是顶流级别的存在。superpowers 这个项目在 Claude Code 生态里火了大半年社区里到处是“用了就回不去”“效率翻十倍”的安利帖。我大概是在它突破 100K star 的时候入的坑到现在满打满算三个月中间经历过“哇这东西真牛”的兴奋期也踩过不少坑现在算是进入了一个比较理性的阶段。这篇文章不吹不黑就把我这三个月的真实使用体验、踩过的坑、以及我最终保留下来真正在用的 skill 清单完整地摊开来讲。先说结论superpowers 确实是个好东西但它的价值被高估了或者说被误读了。很多人以为装上它就能让 Claude Code 变成全能助手实际上它更像是一套“技能框架”核心价值在于给你提供了一套标准化的 skill 组织方式而不是直接给你一堆开箱即用的超能力。你需要自己往里填东西需要理解它的设计哲学需要花时间调试和筛选。如果你指望装完就起飞大概率会失望。这篇文章适合几类人看正在犹豫要不要入坑 superpowers 的 Claude Code 用户、已经装了但觉得“好像没啥用”的玩家、以及想自己写 skill 但不知道从哪下手的人。我会从整体设计思路、核心机制、实操配置、常见问题四个维度展开尽量把每个环节的“为什么”讲清楚让你看完能自己判断这东西到底适不适合你。2. superpowers 到底解决了什么问题2.1 从“每次都要重新解释”到“一次配置反复调用”在没有 superpowers 之前我用 Claude Code 的方式很原始每次开一个新会话都要把项目背景、代码规范、常用命令重新说一遍。比如我有个项目用的是特定的目录结构、特定的测试框架、特定的提交信息格式每次都要写一大段 prompt 来交代这些。时间长了就烦而且容易漏。superpowers 的核心思路就是把这些“重复交代”的东西抽象成 skill。一个 skill 本质上就是一个 Markdown 文件里面写清楚了“在什么场景下触发”“触发后执行什么操作”“有哪些注意事项”。你可以把它理解成给 Claude Code 装的“插件”但这个插件不是代码写的而是自然语言写的。这个设计很聪明因为自然语言的门槛极低你不需要会写 TypeScript 或者 Python只要能把事情说清楚就行。我举个例子。我有个 skill 叫commit-helper里面写的是当用户要求提交代码时先运行git diff --staged查看暂存区变更然后按照 Conventional Commits 规范生成提交信息格式为type(scope): descriptiontype 限定为 feat/fix/docs/style/refactor/test/chore 七种。这个 skill 写完之后我每次提交只需要说“帮我提交”Claude Code 就会自动按这个流程走。省下来的时间不多但省下来的脑力很可观。2.2 技能复用的边界在哪里但这里有个关键问题skill 的复用边界到底在哪我一开始很兴奋想着把所有东西都写成 skill结果发现不是所有东西都适合。有些任务太简单写 skill 的时间比直接做还长有些任务太复杂一个 skill 根本覆盖不了所有分支情况还有些任务高度依赖上下文每次的情况都不一样写死了反而碍事。我后来总结了一个判断标准如果一个任务你每周至少做三次且每次的流程基本一致那就值得写成 skill。比如代码提交、单元测试生成、API 文档更新、数据库迁移脚本生成这些都属于高频且流程固定的任务。反过来像“帮我设计一个架构方案”这种任务每次的约束条件都不一样写成 skill 就是给自己找麻烦。superpowers 官方文档里其实也提到了这一点但它没有说得很直白。社区里很多教程一上来就教你写十几个 skill好像越多越好这是误导。我现在的 skill 目录里常年保持在 8 到 10 个多了就删保持精简。2.3 和 claude-mem、agent-browser 这些热词的关系顺便说一下 claude-mem 和 agent-browser 这两个经常和 superpowers 一起出现的热词。claude-mem 解决的是“记忆”问题让 Claude Code 能跨会话记住一些东西agent-browser 解决的是“浏览器操作”问题让 Claude Code 能控制浏览器。superpowers 和它们是互补关系不是替代关系。superpowers 管的是“技能怎么组织和触发”claude-mem 管的是“信息怎么持久化”agent-browser 管的是“怎么和网页交互”。我自己的组合是superpowers 做 skill 管理claude-mem 做项目上下文记忆agent-browser 用得少只在需要抓取网页数据的时候开。这三个东西装在一起Claude Code 的能力边界确实会扩大不少但前提是你得花时间调教。3. 核心机制拆解skill 是怎么被触发和执行的3.1 skill 的文件结构和元数据一个标准的 superpowers skill 长这样--- name: commit-helper description: 当用户要求提交代码时触发按照 Conventional Commits 规范生成提交信息 trigger: 提交代码、commit、git commit --- ## 执行步骤 1. 运行 git diff --staged 查看暂存区变更 2. 分析变更内容判断 typefeat/fix/docs/style/refactor/test/chore 3. 生成提交信息格式为 type(scope): description 4. 执行 git commit -m 生成的信息 ## 注意事项 - 如果暂存区为空提示用户先 git add - 如果变更涉及多个 type取最主要的那个 - description 用中文不超过 50 个字这个文件放在~/.claude/skills/目录下Claude Code 启动时会自动扫描。关键在 frontmatter 里的trigger字段它决定了这个 skill 什么时候被激活。trigger 写得越精准误触发的概率越低。我踩过的坑是 trigger 写得太宽泛。比如我有个 skill 的 trigger 写了“代码”结果每次我提到“代码”两个字它都跳出来烦得不行。后来改成“生成单元测试”“写测试用例”这种具体短语就正常了。trigger 的设计原则是宁可窄一点也不要宽。窄了最多是不触发你手动喊一声就行宽了会频繁误触发打断你的工作流。3.2 触发机制背后的匹配逻辑superpowers 的触发匹配不是简单的关键词匹配它用的是语义相似度。具体来说当你输入一段话它会计算这段话和每个 skill 的 description 之间的语义距离超过阈值就触发。这个阈值是可以调的在配置文件里有个trigger_threshold参数默认是 0.75。我实测下来0.75 这个默认值偏敏感容易误触发。我调到了 0.82误触发明显减少但偶尔会漏触发。这个需要根据你的 skill 数量和 trigger 写法来微调。如果你只有五六个 skill0.75 够用如果你有十几个 skill建议调到 0.8 以上。还有一个细节superpowers 支持“组合触发”。比如你可以设置一个 skill 只在另一个 skill 执行完之后才可能触发。这个功能用得好的话可以搭出一套工作流。比如我先触发code-reviewskill 做代码审查审查通过后再触发commit-helper做提交。但这个功能配置起来比较绕我试过一次就放弃了觉得没必要搞这么复杂。3.3 skill 执行时的上下文注入skill 被触发后superpowers 会把 skill 文件的内容注入到当前会话的上下文里。注意是注入到上下文不是替换上下文。这意味着 Claude Code 在执行 skill 的时候仍然能看到你之前的对话历史。这个设计有利有弊。好处是 skill 可以利用之前的上下文信息。比如你前面刚讨论完某个函数的实现然后触发test-generatorskill它就能直接针对那个函数生成测试不需要你重新说明。坏处是如果上下文太长skill 的内容可能会被“淹没”导致执行效果打折扣。我遇到过好几次 skill 触发了但 Claude Code 没按 skill 里的步骤走就是因为上下文里其他信息太多把 skill 的指令稀释了。解决办法是在执行 skill 之前尽量开一个新会话或者用/clear清空上下文。这样 skill 的指令能占据主导地位执行准确率会高很多。这个技巧官方文档里没写是我自己试出来的。4. 实操配置从零搭建一套可用的 skill 体系4.1 安装 superpowers 的完整流程安装 superpowers 本身不复杂但有几个细节容易卡住。我以 Ubuntu 环境为例Windows 和 macOS 的流程大同小异。第一步确认 Claude Code 已经装好并且能正常使用。如果你还没装 Claude Code先去官方文档看安装指引。Ubuntu 下的安装命令大概是npm install -g anthropic-ai/claude-code装完之后运行claude --version确认版本。我建议用最新版老版本可能不兼容 superpowers 的一些新特性。第二步安装 superpowers。它本身是一个 Claude Code 的插件安装方式取决于你用的是哪种 Claude Code 客户端。如果你用的是命令行版直接在项目目录下运行claude plugin install superpowers如果你用的是 VS Code 插件版需要在 VS Code 的设置里找到 Claude Code 的插件配置手动添加 superpowers 的仓库地址。这里有个坑VS Code 版的插件市场里搜不到 superpowers必须手动添加。具体路径是设置 - 扩展 - Claude Code - 插件管理 - 添加插件然后输入 superpowers 的 GitHub 仓库地址。第三步验证安装。运行claude plugin list如果能看到 superpowers 就说明装好了。然后创建一个测试 skill 放在~/.claude/skills/目录下重启 Claude Code看能不能触发。注意如果你遇到 “your organization has disabled claude subscription access for claude code” 这个报错说明你的账号权限被限制了需要联系管理员开通。这个和 superpowers 本身没关系是账号层面的问题。4.2 目录结构和配置文件详解superpowers 的目录结构是这样的~/.claude/ ├── skills/ # 存放所有 skill 文件 │ ├── commit-helper.md │ ├── test-generator.md │ └── ... ├── superpowers.json # 全局配置文件 └── memory/ # claude-mem 的记忆存储目录superpowers.json是核心配置文件我常用的几个参数{ trigger_threshold: 0.82, max_skills_per_session: 5, auto_reload: true, skill_dirs: [~/.claude/skills/, ./project-skills/] }trigger_threshold前面说过了控制触发灵敏度。max_skills_per_session限制单次会话最多加载几个 skill防止上下文爆炸。我设的是 5因为超过 5 个 skill 同时加载Claude Code 的响应质量会明显下降。auto_reload设为 true 后你修改 skill 文件不需要重启 Claude Code它会自动重新加载。skill_dirs支持多个目录我一般把通用 skill 放在全局目录项目专用的 skill 放在项目目录下的project-skills/里。4.3 我实际在用的 8 个 skill 清单三个月下来我删删改改最终保留了 8 个 skill。这些是我每天都会用到的其他的要么合并了要么删了。skill 名称触发场景核心功能使用频率commit-helper提交代码生成规范提交信息每天 5 次test-generator写测试生成单元测试每天 3 次api-doc-updater改接口更新 API 文档每周 10 次db-migration改表结构生成迁移脚本每周 5 次code-review审查代码按规范检查代码每天 2 次bug-analyzer排查问题分析报错日志每天 3 次refactor-helper重构代码按模式重构每周 5 次deploy-checker部署前检查部署清单每周 3 次这 8 个 skill 覆盖了我日常工作的 80% 场景。剩下的 20% 要么太特殊不值得写 skill要么用通用 prompt 就够了。4.4 写一个好 skill 的五个关键点写了三个月 skill我总结出五个关键点。第一description 要写得像“触发条件”而不是“功能说明”。比如“当用户要求提交代码时触发”就比“这是一个提交辅助工具”好得多因为前者直接告诉 superpowers 什么时候该激活它。第二执行步骤要具体到可操作。不要写“分析代码质量”要写“运行eslint --format json获取检查结果然后按错误级别分类统计”。越具体执行越稳定。第三注意事项要写你踩过的坑。比如我那个 commit-helper 里写的“如果暂存区为空提示用户先 git add”就是因为我遇到过好几次 Claude Code 在暂存区为空的情况下硬编了一个提交信息结果提交失败。第四skill 文件不要超过 200 行。超过 200 行Claude Code 的执行准确率会下降。如果内容太多拆成多个 skill用组合触发的方式串联。第五定期清理。我每个月会 review 一次 skill 目录把一个月没用过的 skill 删掉。skill 不是越多越好多了反而互相干扰。5. 常见问题与排查技巧实录5.1 skill 不触发怎么办这是最常见的问题。排查思路按顺序来先检查 skill 文件是否在正确的目录下再检查 frontmatter 格式是否正确然后检查 trigger 字段是否写得太窄最后检查trigger_threshold是否设得太高。我遇到过一次 skill 死活不触发查了半天发现是 frontmatter 里的name字段和文件名不一致。superpowers 要求name字段必须和文件名去掉 .md 后缀完全一致否则会静默忽略。这个坑很隐蔽因为不会有任何报错提示。还有一个常见原因是 skill 文件里有语法错误比如 YAML frontmatter 的缩进不对。YAML 对缩进极其敏感多一个空格少一个空格都会导致解析失败。我建议用 VS Code 的 YAML 插件来写 frontmatter能实时检查语法。5.2 skill 触发了但执行不对这种情况通常是上下文干扰导致的。前面说过skill 的内容是注入到上下文里的如果上下文里其他信息太多skill 的指令就会被稀释。解决办法是开新会话或者/clear清空上下文。另一个原因是 skill 里的步骤写得太模糊。比如“分析代码”这种指令Claude Code 每次的理解可能都不一样。改成“运行npm run lint并解析输出”就稳定多了。skill 里的每一步都应该是可验证的这样执行结果才可预期。还有一种情况是 skill 之间互相冲突。比如你有两个 skill 的 trigger 都包含“测试”这个词那当你提到“测试”的时候两个 skill 可能同时触发Claude Code 就不知道该听谁的。解决办法是让 trigger 尽量互斥或者用组合触发来明确优先级。5.3 性能下降和上下文爆炸skill 装多了之后Claude Code 的响应会变慢有时候还会出现“答非所问”的情况。这是因为每次会话启动时superpowers 会把所有 skill 的 description 加载到上下文里做匹配skill 越多加载的内容越多上下文占用越大。我的经验是全局 skill 控制在 10 个以内项目级 skill 控制在 5 个以内。超过这个数性能下降会很明显。如果你确实有很多 skill可以用skill_dirs做分组不同项目加载不同的 skill 目录。另外max_skills_per_session这个参数要设好。我设的是 5意思是单次会话最多加载 5 个 skill。如果你发现响应变慢可以把这个值调低到 3 试试。5.4 常见问题速查表问题现象可能原因排查方法解决方案skill 不触发文件位置错误检查~/.claude/skills/目录移动到正确目录skill 不触发frontmatter 格式错误用 YAML 插件检查语法修正缩进和字段名skill 不触发trigger 太窄检查 trigger 字段增加同义词skill 不触发阈值太高检查trigger_threshold调低到 0.75-0.8执行结果不稳定上下文干扰检查会话历史长度开新会话或/clear执行结果不稳定步骤太模糊检查 skill 内容改成可验证的具体指令响应变慢skill 太多检查 skill 数量精简到 10 个以内响应变慢上下文爆炸检查max_skills_per_session调低到 3-5误触发频繁trigger 太宽检查 trigger 字段改成具体短语误触发频繁阈值太低检查trigger_threshold调高到 0.825.5 几个我踩过的坑和对应的技巧第一个坑skill 文件里的中文标点。superpowers 对中文标点的处理不太稳定有时候全角逗号和半角逗号会导致解析差异。我现在的习惯是 frontmatter 里全部用半角标点正文里随便。第二个坑skill 的触发词和 Claude Code 的内置命令冲突。比如你有个 skill 的 trigger 是“help”那当你输入claude help的时候可能会同时触发内置帮助和你的 skill。解决办法是避免用内置命令作为 trigger。第三个坑skill 更新后不生效。虽然auto_reload设了 true但有时候还是需要手动重启。我现在的习惯是改完 skill 后运行claude plugin reload强制重载比等自动重载靠谱。第四个坑skill 里的命令在 Windows 和 Linux 下不兼容。比如rm -rf在 Windows 下用不了。如果你的团队跨平台skill 里最好用跨平台的命令或者注明平台要求。6. 三个月后的理性评估值不值得用6.1 适合什么场景不适合什么场景superpowers 适合的场景很明确高频、流程固定、需要一致性的任务。比如代码提交、测试生成、文档更新这些用了之后确实省心。我算过一笔账commit-helper 这个 skill 每天帮我省大概 10 分钟一个月就是 5 个小时。test-generator 省得更多每天大概 20 分钟。加起来一个月省 15 个小时左右相当于两个工作日。不适合的场景也很明确低频、高度依赖上下文、每次都不一样的任务。比如架构设计、技术选型、复杂 bug 排查这些任务写 skill 的投入产出比很低。我试过给架构设计写 skill写了 300 多行结果用了两次就删了因为每次的约束条件都不一样skill 里的步骤根本套不上。还有一个不适合的场景是探索性任务。比如你刚接触一个新框架还不知道怎么用这时候写 skill 就是瞎写。正确的做法是先手动做几遍等流程稳定了再抽象成 skill。6.2 和直接写 prompt 相比的优势与劣势很多人问既然 skill 本质上就是一段 prompt那我直接写 prompt 不就行了为什么要用 superpowers这个问题问得好。直接写 prompt 的优势是灵活每次都可以根据情况调整。劣势是重复劳动同样的 prompt 要写很多遍。superpowers 的优势是复用写一次到处用。劣势是僵化skill 写死了之后遇到特殊情况不好变通。我的实际做法是高频任务用 skill低频任务用 prompt。两者不是替代关系是互补关系。我大概 70% 的任务用 skill30% 用 prompt。这个比例我觉得比较健康。6.3 关于 187K star 这个数字的冷思考最后说说 187K star 这个数字。star 多说明项目受关注但不代表它适合所有人。superpowers 的 star 增长曲线我观察过前期很平后来突然爆发大概率是因为某个大 V 推荐或者上了趋势榜。这种爆发式增长带来的问题是很多 star 的人其实没用过或者用了一下就放弃了。我身边用 Claude Code 的同事大概有十几个真正把 superpowers 用起来的只有三四个。其他人要么觉得配置麻烦要么觉得没必要。这个比例我觉得挺真实的。superpowers 不是银弹它只是一个工具工具有没有用取决于你怎么用。如果你现在还在犹豫要不要入坑我的建议是先花一个下午把基础配置跑通写两三个最简单的 skill 试试。如果觉得顺手再继续深入如果觉得麻烦那就别勉强直接写 prompt 也挺好。工具是为人服务的不是反过来。6.4 后续可以怎么扩展如果你已经把基础用起来了想进一步扩展有几个方向可以试试。一是把 skill 和 CI/CD 打通比如在 GitHub Actions 里调用 Claude Code 执行 skill实现自动化的代码审查和文档更新。二是把 skill 和 claude-mem 结合让 skill 能读取项目的历史记忆执行更精准。三是把 skill 做成团队共享的放在项目的.claude/skills/目录下团队成员共用一套 skill。我目前在做第二个方向把 claude-mem 里存的项目规范、历史决策记录和 skill 打通。效果还在观察中等有结论了再单独写一篇。提示skill 的编写没有标准答案最重要的是贴合你自己的工作流。别人的 skill 清单可以参考但不要照搬。花时间观察自己每天在做什么把那些重复的部分抽象出来这才是 skill 的正确打开方式。
