从第一次看到“superpowers”这个项目名我就觉得它起得特别贴切——它不是给AI助手加一个功能而是把一堆能大幅提升AI干活效率的能力打包成可插拔的“技能包”。如果你玩过Claude Code、Cursor这类AI编程工具一定遇到过这种场景想让AI帮你写测试用例它写完是写了但风格和项目里已有的用例对不上想让它按团队规范生成提交信息每次都要把规范贴一遍。superpowers解决的问题就是把这类反复交代的“背景知识”和“操作流程”固化下来做成一个叫skill的东西需要的时候直接引入AI瞬间“觉醒”对应领域的经验。这篇文章适合正在重度使用AI编程助手、想进一步压榨AI效率的开发者也适合刚接触“AI技能化”这个概念、想系统了解怎么给智能体装“外挂”的人。我会从技能的原理、安装、现成技能清单、自定义写法到常见坑位完整走一遍最后附上我实际踩过的问题和排查思路。1. 为什么智能体需要一套“技能系统”1.1 裸用AI助手最大的痛点没有领域上下文先聊聊我自己的体会。早期用AI写代码我大概要花十分钟在提示词里交代“我们这个项目是Go写的”“数据库用的PostgreSQL”“错误处理统一返回JSON”“不要动公共接口”……交代完这些AI确实能干活了但换个任务这些上下文又得重新说一遍。更麻烦的是同一个项目的不同AI会话之间是相互隔离的这次教会的知识下次还得重教。这就是裸用AI助手的核心痛点大模型本身有很强的通用能力但它没有你项目的领域知识也没有你团队的工程规范。提示词工程能缓解一部分问题但提示词本身是“一次性”的没法像代码一样复用、维护、版本管理。你会发现真正拖慢效率的不是AI写代码的速度而是你“教会”AI的时间。1.2 技能的本质把“喂给AI的边际知识”固化下来superpowers这类工具的思路很直接把所有你希望AI具备的特定领域能力拆成一个一个独立的“技能”文件或目录。每个技能包含两部分一部分是给模型看的说明性内容比如工作流程、注意事项、代码风格、领域知识另一部分是可选的可执行逻辑比如解析文件、调用接口、运行测试的脚本。说得直白一点传统提示词工程像是“口传心授”每次靠你现场描述而技能像“武功秘籍”把招式写成册子AI需要用的时候直接翻到对应章节。你不需要每次说“你要注意项目规范”只要引入teamwork这个技能AI自动就知道要按规范来。1.3 对比三要素可复用、可组合、可分享为什么说这是一种架构上的升级而不是换了个提示词模板核心差异有三个可复用一次写好的技能可以在所有会话、所有项目中反复使用不用每次复制粘贴。可组合一个项目可以同时引入多个技能。比如写后端接口时同时挂上“项目规范技能”“数据库建模技能”“测试用例生成技能”AI就会综合这几方面的知识来输出结果。可分享技能以文件形式存在天然适合放进Git仓库。团队里有人写了一个高质量技能其他人拉下来就能用技能本身变成了团队资产。这三个特性加在一起意味着你不再和AI“单次对话”而是在给AI构建一套长期的知识体系。我自己的体验是引入技能系统后AI第一次输出的可用率显著提升返工率至少降了一半。2. 安装与基础配置把superpowers跑起来2.1 环境准备先确认你的AI工具版本先说前提。superpowers是给AI编程工具做技能扩展的框架所以你得先有一个支持技能机制或至少支持自定义指令的AI Coding工具比如较新版本的Claude Code、Continue等。不同工具的加载方式略有差异但总体思路一致把技能文件放到指定目录然后通过命令或配置引入。我以我惯用的环境为例共分三步。第一步是确认运行环境需要Node.js 18npm能正常用。这个项目本质上是一个命令行工具加一组约定目录结构对系统依赖很少macOS、Linux、Windows的WSL环境都能跑。2.2 安装命令与目录结构安装方式通常是拉取仓库然后链接全局命令或者直接用包管理器安装。以仓库安装为例git clone https://github.com/你的源/superpowers.git cd superpowers npm install npm link装完以后执行superpowers --version能看到版本号说明安装成功。然后初始化技能目录superpowers init这条命令会在你当前项目下生成一个.superpowers目录里面按类型分了几个子目录。.superpowers/ ├── skills/ # 存放技能包 │ ├── code-review/ # 代码审查技能 │ ├── test-writing/ # 测试编写技能 │ └── ... ├── config.json # 技能开关配置 └── logs/ # 运行日志提示建议把.superpowers目录纳入Git版本管理但把logs/加进.gitignore日志文件很容易膨胀没必要入库。2.3 引入技能的两种方式使用技能有两种路径对应两种使用习惯。第一种是全局引入用superpowers use命令把技能注册到当前AI会话的上下文中。比如想引入代码审查技能superpowers use code-review这条命令会把code-review技能的内容注入到AI的system prompt里之后这个会话里的AI就有了代码审查者的角色意识。全局引入适合你明确知道接下来要做哪类任务的情况。第二种是自动匹配很多技能带有关键词描述当你的指令中提到特定任务关键词时AI会自动联想并加载对应技能。比如你写“帮我审查一下这个PR”AI如果检测到code-review技能声明了相关触发词就会自动按技能里的流程工作。这种方式用起来最省心但依赖技能定义时的触发词写得好不好。我个人的建议是关键任务用显式引入日常小任务靠自动匹配两者搭配效率最高。2.4 验证安装是否成功装完别急着用先跑一次自检superpowers list这个命令会列出当前已加载的所有技能。如果是首次安装看到的应该是空的或只有内置的几个基础技能。接着用一个简单的技能做验证比如superpowers test hello-world如果终端输出了一组测试通过的日志说明整个链路是通的——技能目录能被找到、注入逻辑能执行、内容能正确传给AI。这一步排障很重要很多新手上来就写自定义技能结果发现AI根本没按技能工作最后排查了半天发现是目录路径配错了。3. 有哪些现成技能常用技能包清单与能力拆解3.1 技能目录里的“常备军”superpowers默认提供了一批针对开发场景的高频技能我按用途分成四类分别是代码类、文档类、分析类和流程类。代码类是我用得最多的。code-review技能会给AI一套审查标准先读改动、再找逻辑漏洞、最后按严重程度输出问题列表。test-writing技能则要求AI先理解被测函数的所有分支再按边界值和异常路径生成用例而不是简单生成几个Happy Path就交差。还有一个refactoring技能用于老代码改造它内置了“小步重构、每步保持测试绿”的原则。文档类里readme-generator负责写项目说明文档它会先扫描项目结构、读关键文件再按“项目简介、快速开始、API说明、常见问题”的结构输出。changelog技能可以从Git提交记录中整理变更日志并且会自动过滤掉“fix typo”这类噪音提交。分析类技能偏向于辅助决策。dependency-audit会检查依赖版本并给出升级建议它会对比主版本间的破坏性变更而不是简单告诉你“有更新”。perf-analysis技能用于代码性能分析它能让AI以性能工程师视角审视热点代码给出具体的优化建议。流程类技能解决的是“怎么干活”的问题。比如git-workflow技能封装了一整套Git协作流程先同步主干、再开分支、提交信息按Conventional Commits规范、最后发起PR。我引入这个技能之后团队的新人再也没交过乱七八糟的提交信息。3.2 技能的核心文件结构为什么一个技能能给AI注入“角色感”因为每个技能目录下都有一个SKILL.md文件这个文件就是整个技能的“大脑”。我拆开看一个典型技能的结构code-review/ ├── SKILL.md # 技能说明书告诉AI这个技能是什么、怎么用 ├── rules.md # 审查规则集按严重程度分级 ├── templates/ │ └── review.md # 审查报告输出模板 └── scripts/ └── diff-stats.sh # 辅助脚本统计改动范围SKILL.md里最关键的几个字段包括技能名称和一句话描述、适用场景、触发关键词、工作流程步骤、以及引用其他文件的指令。注意SKILL.md的编写质量直接决定AI会不会真的按这个技能干活。写得越具体AI的执行越稳定写得笼统AI大概率会忽略它。我见过不少人的技能文件只有一句“你是代码审查专家”这种基本等于没写。3.3 技能文件里的“角色设定”怎么写拿一个SKILL.md的实际片段来说明写清楚比写长更重要# Skill: code-review ## Description 以资深代码审查者身份审查变更代码发现逻辑漏洞、安全隐患和风格问题。 ## Trigger 当用户说“审查代码”“review PR”“帮我看看这段代码”时自动激活本技能。 ## Workflow 1. 先用 git diff 获取变更内容明确改动范围。 2. 逐个文件阅读重点关注错误处理、边界条件和资源释放。 3. 按 SeverityCritical/Major/Minor输出问题清单。 4. 每个问题必须给出问题位置、原因、修改建议。 5. 最后用模板 templates/review.md 输出完整报告。 ## Rules - 只审查当前变更不做全量代码评审。 - 不空泛地说“代码质量有待提升”每个结论必须有据可依。 - 如果发现问题直接给出修复后的代码片段。关键就在Workflow和Rules这两块。Workflow告诉AI“先做什么、后做什么、最终产出什么”Rules用来约束AI的行为边界避免它跑偏。技能之所以比提示词稳定就是因为它把工作流拆成了可验证的步骤。4. 具体使用实战技能在不同场景下怎么发挥价值4.1 场景一用代码审查技能做PR自检我在实际项目里用得最多的就是代码审查。以前提PR之前自己总得先过一遍代码但人看自己写的东西容易有惯性盲区。现在我的流程是superpowers use code-review然后让AI审查当前的改动分支。它会先调用git diff获取变更列表再按技能里定义的规则逐条核对。有一次我故意写了一个多余的空指针判断AI直接标了“Major冗余判断掩盖了上游数据校验缺失建议在入口统一校验”。这个结论质量已经接近我团队里资深同事的评审水准了。这里必须提醒一点技能内置的代码审查不是万能的它对跨文件的数据流分析仍然较弱。我的使用原则是用它做第一轮自检抓逻辑漏洞和低级错误细节的架构问题还得靠人工把关。4.2 场景二测试生成技能的实战效果团队一直要求新代码必须有单测但让AI直接写测试默认效果经常是“对着快乐路径一顿输出”。引入test-writing技能以后就不一样了。这个技能要求AI先列出被测函数的所有分支包括正常分支、异常分支、边界值、空值、超大值然后一个分支一个分支生成用例。实际跑下来测试覆盖率从原来的65%提到了89%。更重要的是AI会主动生成边界测试比如数组长度为0、字符串超大、接口超时这类情况这些恰恰是手动写测试时最容易遗漏的。4.3 场景三自定义工作流技能替代人工检查清单除了官方技能superpowers给人最大的想象力在于你可以把自己平时按部就班做的事固化成技能。举个我的例子每次发布版本之前我都要手动检查一堆事项现在写成了一个release-check技能检查版本号是否正确递增。检查CHANGELOG.md是否更新。检查依赖锁文件是否与package.json同步。检查CI配置是否改动过。输出检查报告标明每项的通过状态。每次发版前我只需要敲一句“执行发布检查”AI就按流程跑一遍。这个技能把团队里的隐性知识显性化了任何人接手发版工作都不会再漏步骤。4.4 技能组合多技能协同才是终极玩法单个技能解决单点问题组合起来才能发挥指数级效果。我现在做新功能的标准流程是先用spec-writer技能写技术方案然后挂上code-review技能边写边审写完用test-writing生成单测最后用changelog技能更新变更记录。技能之间基本没有冲突因为每个技能只负责自己的环节输出结果刚好是下一个技能的输入。这种流水线式的配合让AI从“单点工具”变成了“完整工作流执行者”这是我在引入superpowers之前完全没体验过的。5. 自定义技能编写从零开始做一个属于自己的技能5.1 确定技能边界别把技能写成万能药技能最容易犯的错是贪多。新手上来就想写一个“全栈开发技能”结果里面既包含代码规范、又包含部署流程、还包含数据库设计……最后AI什么都吸收一点什么都不精。我建议一个技能只解决一个明确问题比如“生成符合团队规范的提交信息”或“检查Dockerfile的安全性”。技能边界划得越清楚AI执行越稳定。如果一个技能里有超过七八条规则就应该考虑拆分成两个。5.2 动手写一个最小技能下面我带大家走一遍完整的创建流程目标技能功能是“为项目生成规范的README”。第一步创建目录和文件mkdir -p .superpowers/skills/readme-gen touch .superpowers/skills/readme-gen/SKILL.md第二步编写SKILL.md# Skill: readme-gen ## Description 根据项目代码自动生成结构化README文档。 ## Trigger 当用户说“写README”“生成项目文档”“补充readme”时自动激活。 ## Workflow 1. 扫描项目根目录读取 package.json 或 pyproject.toml 等配置文件。 2. 获取项目名称、依赖、脚本命令等元信息。 3. 遍历 src/ 或 lib/ 目录整理公开的API或模块。 4. 按固定模板输出README包括项目简介、功能特性、安装方式、快速开始、API列表、常见问题。 5. 若原有README存在则在原基础上补充缺失章节不重复生成。 ## Rules - 所有命令示例必须可执行不能凭空编造。 - 输出语言与项目注释语言保持一致。 - 遇到无法确定的内容标注“待补充”而不是猜测。第三步测试技能是否生效superpowers use readme-gen然后在AI对话框输入“帮这个项目写一份README”。此时AI应该按Workflow里的步骤先读配置文件再生成文档而不是直接凭感觉写。我把这一步叫“有流程的生成”它和裸用的最大区别在于输出的内容结构和信息密度是受控的。5.3 给技能加上辅助脚本有些技能光靠说明书不够还需要实际执行逻辑。比如dependency-audit要读取依赖锁定文件做版本对比这不是靠大模型“想象”能完成的它需要脚本实际跑一遍。技能目录里可以放scripts/子目录在SKILL.md里用相对路径引用脚本。AI可以执行脚本并把输出结果拿来做分析。这相当于给技能装上了“手”能真正操作环境而不只是“动嘴”。注意给技能配脚本时务必在SKILL.md里写明脚本的输入输出格式和运行环境否则AI调用时不知道传什么参数很容易报错。5.4 调试自定义技能的正确姿势写完技能不代表万事大吉。我自己调试技能时有一套标准动作先检查SKILL.md语法和引用路径确认引用的每个文件都存在。然后跑一次superpowers list看技能是否被正确加载。再用一个最小化指令测试比如只触发核心Workflow观察AI是否按步骤执行。最后逐步增加任务复杂度直到覆盖技能的完整流程。如果AI执行结果偏离预期大部分时候不是模型问题而是你的技能描述有歧义。把模糊的表述改具体再测一遍基本能解决。6. 常见问题与排查技巧实录6.1 五个高频问题速查表我把自己和身边人用过superpowers之后踩过的坑整理了一下做成一个速查表大家按图索骥问题现象可能原因解决办法执行superpowers命令提示找不到全局链接未生效重新执行npm link确认npm全局bin目录在PATH里list命令看不到新装的技能技能放在错误目录检查技能是否放在.superpowers/skills/下且目录内有SKILL.mdAI行为完全不像启用了技能技能没有被注入上下文用superpowers use 技能名显式引入再测试多个技能规则冲突两个技能对同类行为有相反要求检查rules.md里的约束条件拆分技能或加触发隔离技能执行时报脚本权限错误可执行权限缺失对scripts/下的脚本执行chmod x6.2 排查思路从日志找线索遇到问题别靠猜。superpowers会记录每次技能加载的日志在.superpowers/logs/目录下。当技能没有按预期生效时第一件事是打开对应时间段的日志看技能文件是否被成功解析、注入的指令是否包含SKILL.md的内容。我能找到的排查路径是先确认技能被list识别再确认日志里注入了内容最后才怀疑是模型执行的问题。按这个顺序排查90%的问题都能定位到前面两步。6.3 我踩过的三个坑你们别再踩了第一个坑是技能目录层级放错了。官方示例里技能是skills/技能名/SKILL.md我之前图省事直接放在skills/根目录下结果怎么加载都不生效。查了半天日志才发现是路径不对。第二个坑是触发词写得太泛。我给一个技能写了“代码”作为触发词结果AI看到任何和代码有关的任务都会尝试激活这个技能反而干扰了正常对话。后来我把触发词改成更精确的短语比如“按XX规范生成代码”问题立刻消失。第三个坑是技能规则太多导致AI“选择性遗忘”。早期我写技能总想把所有细节都写进去一个SKILL.md长到两千多字结果AI执行时经常忽略后半部分内容。后来我把长技能拆成“主技能子技能”主技能负责触发和工作流子技能承载具体规则执行稳定性明显提升了。6.4 技能维护定期清理和归档技能不是写完就完事了它们需要维护。我习惯每个月过一遍技能目录把不用的技能归档到skills_archive/把使用中产生的新规则合并回技能文件。这个过程和代码重构很相似目的都是保持技能库的健康度。一个常见判断标准是如果一个技能你连续两周没有触发过就该考虑是删除、归档还是调整触发词。技能库不是越壮越好保留的都是高频有用的才不会在加载时拖慢上下文、稀释有效指令。最后再分享一点我自己的体会用superpowers这段时间我最深的感受是它真正改变的不是AI的能力而是你组织知识的方式。以前我积累的工程经验散落在笔记、文档和聊天记录里现在它们变成了结构化的技能文件跟着项目走团队里每个人都能用。这种“把个人经验沉淀成团队资产”的过程带来的效率提升远超多写几段提示词。如果你刚上手我的建议是先别急着造轮子。装好工具把官方技能和社区技能跑一遍熟悉技能的工作机制再动手写自己的第一个技能。写的时候认准“一个技能解决一个问题”从简单的开始比如版本发布检查、提交信息生成这种流程固定、规则明确的场景最容易获得成就感。等你熟练了自然会琢磨出更多适合自己工作流的技能组合。说到底superpowers告诉我的道理其实很朴素AI再强也需要一套体系来组织和发挥这些能力。把知识固化、流程化、可复用这是工具带来的最大价值也是我们这些天天和AI打交道的人最值得投入的方向。