1. 从“超能力”到可落地的技能系统我为什么盯上了 superpowers第一次看到 “superpowers” 这个词是在一个开发者社群里有人问“有没有那种能让日常工作效率直接翻倍的工具集”底下有人回了一句“你去看看 superpowers装完就像给自己开了挂。”说实话这种描述放在以前我是不信的毕竟“开挂”这个词被用烂了。但当我真正花了一个周末把 superpowers 从安装到实际跑通、再到拆解它内部的 skills 机制之后我承认这个名字起得确实不夸张。superpowers 本质上是一套面向 AI 编程助手尤其是 Claude Code 这类终端里的智能体的技能扩展框架。它做的事情简单说就是把你平时反复要跟 AI 解释的“工作规范”“操作流程”“领域知识”提前打包成一个个可复用的 skill技能模块让 AI 在需要的时候自动加载、按你的规矩干活。它解决的核心痛点是——AI 每次对话都像失忆你得反复交代背景、反复纠正格式、反复提醒它别乱改代码。而 superpowers 通过一套结构化的技能注入机制让 AI 在特定场景下自动“想起”该怎么做。这套东西适合谁我梳理了一下大概三类人最该关注第一类是每天用 AI 写代码、但被 AI 的“自由发挥”折磨到崩溃的开发者第二类是想把团队内部规范沉淀下来、让 AI 自动遵守的技术负责人第三类是对 AI 工作流感兴趣、想搞明白“技能注入”到底怎么实现的技术爱好者。哪怕你只是刚接触 AI 编程助手只要你能照着步骤操作也能在半小时内把基础框架跑起来。我写这篇东西的出发点很简单网上关于 superpowers 的中文资料太碎了要么是几句安装命令要么是截图堆砌没人把“它为什么这么设计”“skills 到底怎么写”“引入技能时踩了哪些坑”讲透。我把自己从零搭建、调试、再到实际项目里用起来的完整过程整理出来包括那些官方文档里不会写的细节。你照着做能少走至少两天的弯路。2. 核心机制拆解superpowers 到底是怎么“注入技能”的2.1 技能不是插件而是“按需加载的上下文”很多人第一次接触 superpowers会下意识把它理解成“插件系统”——装一个功能就多一个按钮。但实际用下来你会发现它的设计哲学更接近上下文注入。每个 skill 本质上是一个结构化的 Markdown 文件通常叫SKILL.md里面写清楚了这个技能叫什么、什么时候触发、触发后 AI 应该遵循哪些步骤、有哪些注意事项、输出格式是什么样。当你在终端里跟 AI 对话时superpowers 会根据你当前的任务描述去匹配已安装的 skill。匹配上了就把这个 skill 的内容作为额外上下文塞给 AI。AI 看到的不再是干巴巴的用户提问而是“用户提问 这个场景下的操作手册”。这就是为什么装完 superpowers 之后你会感觉 AI “突然懂规矩了”——不是模型变聪明了而是你提前把规矩写好了。这种设计的好处非常明显。传统做法是你每次都要在 prompt 里写一大段“请按照以下规范……”又长又容易漏。而 skill 是持久化的、可版本管理的、可分享的。你写一次以后每次触发都自动生效。更关键的是skill 文件是纯文本你可以用 Git 管理可以团队共享可以随时改。这比把规范写在某个文档里然后指望大家自觉遵守靠谱太多了。2.2 一个 skill 的标准结构长什么样我拆了几个官方和社区里质量比较高的 skill发现它们基本都遵循一个相似的结构。虽然不强制但按这个结构写AI 的识别率和执行准确率明显更高。我把它总结成下面这张表字段/区块作用是否必需我的经验name技能唯一标识用于匹配和引用必需用英文小写加连字符别用中文description一句话说明这个技能干什么、什么时候用必需写得越具体匹配越准when_to_use触发条件的详细描述强烈建议把用户可能说的原话列几个进去steps具体操作步骤有序列表必需每步都要可执行别写“适当调整”这种废话constraints禁止事项、边界条件强烈建议这是防止 AI 乱来的关键output_format期望的输出格式模板可选有固定格式需求时一定要写examples正例和反例可选加一两个例子效果提升很明显我一开始偷懒只写了 name 和 steps结果 AI 经常在边缘情况下跑偏。后来补上 constraints 和 examples稳定性肉眼可见地变好。特别是 constraints你一定要把“不要做什么”写清楚。AI 的默认倾向是“尽量帮忙”你不告诉它边界它就会过度发挥。2.3 技能匹配的底层逻辑关键词、语义与优先级superpowers 匹配 skill 的方式我实测下来是关键词命中 语义相似度的混合策略。它不是简单地看你这句话里有没有某个词而是会综合判断。举个例子你写了一个叫code-review的技能触发条件里写了“审查代码”“检查代码质量”“review”。当你说“帮我看看这段代码有没有问题”时虽然没有完全命中关键词但语义上很接近它也能匹配上。但这里有个坑如果你装了很多技能有些技能的触发条件写得太宽泛就会互相抢。比如一个技能写“任何时候都可以用”那它几乎会污染所有对话。我的做法是给每个技能的when_to_use加上限定词比如“当用户明确提到‘部署’且涉及服务器配置时”。限定得越清楚误触发越少。另外superpowers 支持给技能设置优先级。当多个技能同时匹配时优先级高的先加载。这个机制在团队协作场景里特别有用——你可以把公司强制规范设成高优先级个人偏好设成低优先级冲突时以公司规范为准。2.4 为什么是 Markdown 而不是代码这个问题我一开始也没想明白。按理说技能逻辑用代码写不是更灵活吗后来用久了才体会到Markdown 的优势在于人和 AI 都能读。你用代码写逻辑AI 得先理解代码再执行中间多了一层翻译。而 Markdown 本身就是自然语言AI 直接读直接执行路径最短。更重要的是Markdown 让非程序员也能参与技能编写。我们团队里有个产品经理他不懂代码但他能把自己那套需求评审的流程写成 skill。写完之后 AI 就能按他的流程走他特别有成就感。如果技能必须用代码写这件事就跟他没关系了。所以这个设计选择表面看是技术决策实际上是在扩大使用者的范围。3. 从零安装到跑通第一个技能完整实操记录3.1 安装前的环境确认与依赖检查在动手之前你得先确认自己的环境。superpowers 主要是配合终端里的 AI 编程助手使用的所以你的机器上得先有对应的运行环境。我当时的配置是 macOSNode.js 版本 18 以上终端用的是 iTerm2。Windows 用户用 WSL 或者 PowerShell 都可以但路径处理上会有些差异后面我会提到。第一步确认 Node.js 和包管理器是否就绪。打开终端跑这两条命令node -v npm -v如果版本号正常输出说明基础环境没问题。Node.js 建议 18 LTS 或更高太低版本有些依赖装不上。我有个朋友用 Node 14 折腾了半天最后升级到 20 才顺利跑通。第二步确认你的 AI 编程助手已经安装并可以正常对话。superpowers 本身不是一个独立的 AI它是给现有助手加技能的。所以你得先有一个能用的助手环境。这部分每个人的情况不一样按你平时用的来就行。第三步找一个合适的目录存放技能文件。我建议单独建一个目录比如~/superpowers-skills/不要跟项目代码混在一起。原因是技能文件需要长期维护和版本管理混在项目里容易误删也不方便跨项目复用。提示如果你在公司网络环境下操作先确认包管理器的源是可访问的。我遇到过因为源配置问题导致安装卡住的情况换成默认源就正常了。3.2 安装 superpowers 框架的三种方式与选择建议superpowers 的安装方式我试过三种各有适用场景。下面这张表是我实测后的对比安装方式命令/操作适合场景我的评价全局安装npm install -g superpowers个人长期使用多个项目共享最省事推荐新手项目本地安装npm install superpowers --save-dev团队项目技能随项目走版本可控适合协作手动克隆git clone官方仓库到本地想改源码、深度定制灵活但维护成本高我个人的选择是全局安装 项目本地技能目录的组合。框架全局装一份技能文件放在项目里用 Git 管理。这样框架升级不影响技能技能变更也能被团队看到。安装命令跑完之后用下面这条命令验证是否成功superpowers --version能输出版本号就说明框架就位了。如果提示命令找不到大概率是全局 bin 目录没加到 PATH 里。macOS 和 Linux 下通常是/usr/local/bin或~/.npm-global/binWindows 下是 npm 的全局目录。把这个路径加到环境变量里再试。3.3 初始化技能目录与配置文件框架装好之后需要初始化技能目录。superpowers 默认会去几个固定位置找 skill 文件你也可以通过配置文件指定自定义路径。我建议第一次用的时候先跑初始化命令superpowers init这个命令会在当前目录下生成一个.superpowers/文件夹里面包含skills/子目录和一个config.json。skills/就是你放技能文件的地方config.json控制加载行为。打开config.json你会看到类似这样的结构{ skillsDir: ./skills, autoLoad: true, priority: { default: 5 }, maxSkillsPerTurn: 3 }几个关键参数我解释一下。skillsDir是技能文件目录可以改成绝对路径。autoLoad控制是否自动匹配加载设成false的话就得手动指定用哪个技能。maxSkillsPerTurn限制单次对话最多加载几个技能这个很重要——加载太多会稀释 AI 的注意力我实测下来 3 个是比较舒服的上限超过 5 个效果反而下降。注意maxSkillsPerTurn不要设太大。我一开始图省事设成 10结果 AI 经常把不相关的技能内容也带进回答里输出变得又长又乱。后来降到 3精准度明显提升。3.4 写第一个 skill从“代码审查”开始理论说再多不如动手写一个。我选“代码审查”作为第一个技能因为这个场景高频、需求明确、容易验证效果。在skills/目录下新建一个文件夹code-review里面创建SKILL.md内容如下--- name: code-review description: 对用户提供的代码进行结构化审查输出问题清单和改进建议 when_to_use: 当用户说“审查代码”“检查代码”“review”“看看这段代码有没有问题”时触发 priority: 7 --- ## 审查步骤 1. 先通读代码理解整体意图不要急着挑毛病 2. 按以下维度逐项检查 - 正确性逻辑是否有漏洞边界条件是否处理 - 可读性命名是否清晰结构是否合理 - 性能是否有明显的低效操作 - 安全性是否有输入未校验、敏感信息硬编码等问题 3. 每个问题标注严重程度阻塞 / 建议 / 提示 4. 给出具体的修改建议不要只说“这里不好” ## 约束 - 不要直接重写用户的代码除非用户明确要求 - 不要对代码风格做主观评价除非违反了明确的规范 - 如果代码片段不完整先指出缺失部分再审查已有部分 ## 输出格式 ### 问题清单 | 位置 | 问题 | 严重程度 | 建议 | |------|------|----------|------| ### 整体评价 一段话总结代码质量指出最需要优先处理的问题写完保存然后在终端里跟 AI 说一句“帮我审查一下这段代码”后面贴上任意一段代码。如果配置正确AI 的输出应该会严格按照你定义的格式来先出表格再出总结。我第一次看到这个效果的时候确实有点惊喜——以前得反复交代的格式现在一句话就自动生效了。3.5 验证技能是否生效的三种方法写完技能不代表就生效了得验证。我用三种方法交叉确认第一种直接触发法。用when_to_use里列出的原话去问 AI看它是否按 skill 的格式回答。这是最直观的。第二种调试模式。superpowers 有个--debug参数加上之后会输出技能匹配的详细日志告诉你哪个技能被命中、匹配分数是多少。命令是superpowers --debug日志里会显示类似matched skill: code-review (score: 0.87)的信息。如果分数很低或者没匹配上说明你的when_to_use写得不够准得回去改。第三种冲突测试。故意说一句模糊的话看会不会误触发。比如你说“帮我看看这个东西”如果code-review被触发了说明它的触发条件太宽需要加限定词。我建议每次写完新技能这三种方法都跑一遍。特别是冲突测试能帮你提前发现技能之间的干扰问题。4. 技能体系进阶怎么组织、复用和团队共享4.1 技能分类的三种思路与我的选择当你写到第五个、第十个技能的时候就会面临一个现实问题怎么组织全堆在一个目录里找起来费劲匹配也容易乱。我试过三种分类思路最后选了第三种。第一种是按功能分比如coding/、writing/、ops/。这种分法直观但边界模糊——一个“写技术文档”的技能算 coding 还是 writing第二种是按触发频率分高频的放一起低频的放一起。这种分法对性能优化有帮助但维护起来很别扭因为你很难判断一个技能到底算高频还是低频。第三种是按工作流阶段分比如planning/、implementation/、review/、deployment/。我最后选了这个因为 AI 的工作场景本身就是按阶段走的按阶段分匹配时的上下文更一致误触发也少。具体目录结构大概是这样skills/ ├── planning/ │ ├── requirement-analysis/ │ └── task-breakdown/ ├── implementation/ │ ├── code-review/ │ └── refactor-guide/ ├── review/ │ └── security-check/ └── deployment/ └── release-checklist/每个阶段下的技能触发条件都限定在对应阶段互相干扰的概率大大降低。4.2 技能复用的两个实用技巧写多了之后你会发现很多技能之间有重复内容。比如好几个技能都需要“先确认用户意图再动手”这一步。如果每个技能都抄一遍改的时候就得改好几处。我用了两个技巧来解决。第一个技巧是公共片段抽取。superpowers 支持在 skill 文件里引用其他文件语法是{{include: common/confirm-intent.md}}。你把公共步骤写在一个单独文件里各个技能按需引用。改一处全部生效。第二个技巧是技能继承。你可以定义一个基础技能然后让其他技能继承它。比如定义一个base-coding技能包含所有编码类技能的通用约束然后code-review和refactor-guide都继承它。继承的语法是在 frontmatter 里加一行extends: base-coding。这两个技巧我是在写到大概十五个技能的时候才开始用的。前期技能少重复就重复了没必要过度设计。但一旦超过十个不抽公共部分维护成本会指数级上升。4.3 团队共享技能库的落地方式一个人用和团队用完全是两码事。团队用的核心挑战是怎么保证大家用的是同一套技能怎么处理个性化需求怎么更新。我的方案是三层结构基础层公司或团队强制规范放在一个独立的 Git 仓库里所有人必须引用。这层技能优先级最高不允许个人覆盖。项目层跟项目代码放在一起随项目走。项目特有的流程、约定放这里。个人层每个人自己的目录放个人偏好。优先级最低冲突时让位于前两层。superpowers 的配置支持指定多个技能目录并且可以设置加载顺序。在config.json里这样写{ skillsDirs: [ /path/to/team-skills, ./.superpowers/skills, ~/my-personal-skills ], priority: { team-skills: 10, project: 7, personal: 3 } }这样配置之后团队规范永远优先个人习惯只在没有冲突时生效。我们团队用这套结构跑了三个月基本没出现过“AI 按某个人的习惯乱来”的情况。提示团队技能库的更新要有流程。我们的做法是走 Pull Request至少一个人 review 通过才能合并。技能文件虽然简单但它直接影响 AI 的行为改错了影响面不小。4.4 技能版本管理与回滚策略技能文件是纯文本天然适合 Git 管理。但有个细节容易被忽略技能的行为会随 AI 模型版本变化。同一个技能在模型 A 上表现很好换到模型 B 可能就触发不准了。所以版本管理不能只管文件还得记录“这个技能在哪个模型版本下验证过”。我的做法是在 skill 的 frontmatter 里加两个字段tested_with: claude-sonnet-4 last_verified: 2025-01-15每次模型升级或者技能大改都更新这两个字段。如果发现某个技能突然不灵了先看last_verified是不是太久没更新大概率是模型行为变了需要重新调触发条件。回滚策略也很简单技能库用 Git 分支管理主分支是稳定版开发在 feature 分支。出问题了直接git revert或者切回上一个 tag。我建议每次批量更新技能前打个 tag方便回退。5. 常见问题与排查技巧实录5.1 技能不触发或误触发怎么办这是最高频的问题没有之一。我整理了一个排查流程按顺序走基本都能定位现象可能原因排查方法解决方式完全不触发技能目录配置错误跑--debug看有没有扫描到检查skillsDir路径完全不触发frontmatter 格式错误检查---是否成对用 YAML 校验工具检查偶尔触发when_to_use太窄看 debug 日志的匹配分数补充更多触发原话频繁误触发when_to_use太宽故意说模糊话测试加限定词缩小范围被其他技能抢优先级冲突看 debug 日志哪个技能命中调整 priority 值我踩过最坑的一次是 frontmatter 里的name用了中文结果匹配一直失败。debug 日志里显示技能被扫描到了但就是匹配不上。后来改成英文就好了。所以命名这块老老实实用英文小写加连字符别图省事。还有一个隐蔽问题如果你的 skill 文件编码不是 UTF-8中文内容会乱码AI 读到的就是乱码自然匹配不上。保存文件时确认编码格式这个细节很容易被忽略。5.2 技能加载后 AI 输出变慢或变啰嗦加载技能会往上下文里塞额外内容塞多了自然影响输出。我遇到过两种情况一种是加载了太多技能AI 把每个技能的内容都复述一遍另一种是单个技能写得太长光读技能就花掉大量 token。解决办法有两个。第一控制maxSkillsPerTurn我前面说了3 个是上限。第二精简技能内容。skill 文件不是越长越好能一句话说清就别写三段。我现在的标准是单个 skill 文件控制在 200 行以内超过就拆成多个技能或者抽公共片段。另外steps部分尽量用短句别写长段落。AI 读短句的效率比读长段落高执行也更准。我做过对比同样一个技能步骤写成短句列表比写成段落AI 的执行准确率大概高两成。5.3 多个技能冲突时的优先级处理冲突的表现是AI 同时遵循了两个技能的矛盾要求输出变得四不像。比如一个技能说“输出用表格”另一个说“输出用列表”AI 可能给你来个“表格里套列表”。处理原则是明确优先级 消除矛盾。首先在config.json里给不同目录设不同优先级团队规范最高。其次如果两个技能确实会在同一场景触发就得在其中一个里加约束明确“当 X 技能也适用时以 X 为准”。我还会定期做一次“冲突审计”把所有技能两两组合看触发条件有没有重叠。重叠的要么合并要么加互斥条件。这个工作有点繁琐但做一次能管很久。5.4 技能更新后行为不一致的排查技能改了之后AI 的行为跟预期不符这种情况多半是缓存或者加载顺序的问题。superpowers 会缓存已加载的技能改完文件后可能需要重启会话或者跑一下superpowers reload才能生效。如果重启后还是不对检查是不是有同名的技能存在于多个目录。比如团队目录里有个code-review你个人目录里也有一个加载时可能加载了你不想要的那个。debug 日志里会显示实际加载的是哪个路径的文件对着看就能发现。还有一种情况是技能内容里有语法错误导致整个文件被跳过。superpowers 遇到解析失败通常会静默跳过不会报错。所以改完技能后最好用superpowers validate命令校验一下确保文件能被正确解析。5.5 我的独家避坑清单最后分享几条我踩坑踩出来的经验都是文档里不会写的技能名不要用保留字。我试过用help当技能名结果跟系统命令冲突一直出问题。避开help、init、config这类词。触发条件里别写太泛的词。“帮我”“看看”“处理一下”这种词几乎每句话都有写进去等于没写还会导致误触发。先写约束再写步骤。我现在的习惯是先想清楚“这个技能绝对不能做什么”把约束写好再补步骤。这样写出来的技能边界清晰AI 不容易跑偏。每个技能都要有反例。在examples里放一个“不该触发”的例子能显著降低误触发率。定期清理僵尸技能。用不上的技能及时删掉留着只会增加匹配干扰。我每个月清理一次保持技能库精简。技能文件加注释。Markdown 里可以用!-- --写注释给自己留点说明比如“这个条件是为了避开 XX 场景”。过两个月回来看你会感谢自己。这套东西我从零摸索到跑顺大概花了一个多月。现在团队里每个人都有自己的技能库AI 干活的规矩统一了返工率明显下降。如果你刚开始接触别想着一次写完美先写一个最简单的跑通感受到效果之后再慢慢加。技能这东西用起来比写起来重要得多。