1. 从“超能力”到可复用技能superpowers 到底在解决什么问题第一次听到 “superpowers” 这个词很多人会以为是某个游戏里的技能系统或者某个超级英雄题材的项目。但如果你最近在开发者社区、效率工具圈或者 AI 编程助手的讨论里频繁看到它那你大概率已经意识到这里的 superpowers 指的是一套让 AI 编程助手“长出技能”的机制——它把原本散落在提示词、文档、个人经验里的操作流程封装成一个个可被调用、可被组合、可被复用的技能模块。我最初接触 superpowers 的时候最直观的感受是它不像一个传统意义上的软件库更像一套“给 AI 助手装配工作流”的规范。你告诉 AI 助手“我有这些技能”它就能在合适的场景下自动调用对应的技能而不是每次都靠你从头写一大段提示词。这个思路解决的核心痛点非常明确——重复性指令的浪费。比如你每次让 AI 帮你写单元测试都要重复交代“用 pytest、覆盖边界条件、mock 外部依赖、命名要清晰”这些内容完全可以固化成一个技能需要的时候直接触发。从热搜词来看大家最关心的几个问题集中在“superpowers 具体怎么用”、“它到底有哪些 skills”、“怎么把这些技能引入到自己的工作流里”、“安装 superpowers 的步骤是什么”。这几个问题其实构成了一个完整的链路先理解它是什么再知道它有什么然后学会怎么装、怎么引、怎么用。这篇文章我就按照这个链路把我在实际使用中踩过的坑、总结出来的操作细节尽量完整地分享出来。需要先说明一点superpowers 本身并不是一个孤立的应用程序它更像是一层“技能描述与调度”的约定。你可以把它理解成给 AI 助手准备的一本“操作手册目录”手册里的每一条就是一个 skill。AI 助手在接到任务时会先看目录里有没有匹配的技能有就直接按技能里定义的步骤执行。这个机制的好处是技能可以被版本化管理、可以被团队共享、可以被不断迭代而不是锁死在某个人的聊天记录里。适合谁来参考这篇文章如果你已经在用 AI 编程助手处理日常开发任务并且开始觉得“每次都要重复交代同样的要求”很烦那 superpowers 这套思路对你价值最大。如果你只是偶尔用 AI 聊聊天、查查资料那这篇文章里的很多细节可能暂时用不上但了解“技能化”这个方向对以后提升效率也有帮助。接下来我会从整体设计思路开始拆然后逐层深入到具体技能、引入方式、安装步骤和常见问题。2. 整体设计思路拆解为什么要把能力拆成“技能”2.1 从“一次性提示”到“可复用技能”的转变逻辑传统使用 AI 助手的方式基本是“一次性提示”你有一个任务你写一段提示词AI 给你一个结果任务结束。下次遇到类似任务你再写一遍提示词可能写得更好也可能写得更差。这种模式的问题在于经验无法沉淀。你今天调好了一个很满意的提示词明天换一个对话窗口一切归零。superpowers 的设计思路本质上是把“提示词”升级成“技能”。技能和提示词的区别在于提示词是面向单次任务的技能是面向一类任务的。一个技能里通常包含几个要素技能名称、适用场景描述、执行步骤、注意事项、输出格式要求。当 AI 助手识别到当前任务匹配某个技能的适用场景时就会按照技能里定义的步骤去执行。这个转变带来的直接好处是一致性。团队里每个人用同一个技能产出的代码风格、测试结构、文档格式都会趋于一致。我试过在一个小团队里推行这种模式最明显的改善是代码评审时关于“格式和结构”的争论少了很多因为大家调用的技能里已经把规范写死了。另一个好处是可迭代。技能文件是纯文本可以放进版本控制。今天发现某个步骤有问题改一下技能文件明天所有人调用到的就是新版本。这比在聊天记录里翻找“上次那个提示词是怎么写的”要高效得多。2.2 技能与普通提示词模板的本质区别很多人会问这不就是提示词模板吗我建一个文档存一堆模板用的时候复制粘贴不也一样表面上看确实相似但有几个关键区别。第一触发方式不同。提示词模板需要你主动去找到它、复制它、粘贴它。技能是可以被 AI 助手自动识别的——你只需要描述任务助手会判断该用哪个技能。这减少了“找模板”这个动作尤其在任务紧急的时候少一步操作就是少一分打断。第二结构化程度不同。提示词模板通常是一段自由文本而技能有相对固定的结构。结构化的好处是 AI 助手更容易解析也更容易在技能之间做组合。比如一个“写测试”的技能可以调用一个“生成 mock 数据”的技能这种组合在自由文本模板里很难稳定实现。第三可维护性不同。技能可以像代码一样做 diff、做 review、做回滚。提示词模板如果只是存在某个文档里改了什么、谁改的、为什么改往往说不清楚。我在实际使用中会把技能文件放在项目仓库的一个专门目录里每次修改都走正常的代码评审流程这样技能的质量是有保障的。2.3 技能化方案适合哪些场景不适合哪些场景技能化不是万能的。根据我的经验它最适合的场景是重复性高、步骤明确、对一致性有要求的任务。比如生成单元测试、生成 API 文档、做代码格式化检查、生成数据库迁移脚本、写提交信息。这些任务每次的输入不同但处理流程基本固定非常适合做成技能。不太适合的场景是高度探索性、每次都需要不同思路的任务。比如“帮我设计一个系统架构”这种任务每次的约束条件、业务背景都不一样硬做成技能反而会限制 AI 的发挥。我的做法是对于这类任务只把其中稳定的部分比如“架构文档的输出格式”做成技能探索性的部分仍然靠自由对话。还有一个不适合的场景是技能数量过多。我见过有人一口气建了几十个技能结果 AI 助手在匹配时反而容易选错。技能库需要克制宁可少而精不要多而杂。一般来说一个项目里维护五到十个核心技能覆盖最高频的任务就已经能带来明显的效率提升。3. 核心技能盘点superpowers 里到底有哪些 skills3.1 开发流程类技能从写代码到提交的完整链路开发流程类技能是 superpowers 里最实用的一类因为它覆盖了日常开发中最高频的动作。我整理了一下我实际在用的几个核心技能以及它们各自解决什么问题。代码生成技能这个技能的核心不是“让 AI 写代码”而是“让 AI 按照项目约定写代码”。技能里会定义项目的目录结构、命名规范、错误处理方式、日志格式等。调用这个技能时AI 生成的代码会直接符合项目规范省去了大量后期调整。我试过对比不用技能时AI 生成的代码大概有六成需要手动调整格式用了技能之后这个比例降到了两成左右。单元测试技能这个技能定义测试框架、断言风格、mock 策略、覆盖率要求。我特别在技能里加了一条“必须覆盖边界条件和异常分支”因为 AI 默认生成的测试往往只覆盖正常路径。加上这条之后测试的完整性明显提升。代码评审技能这个技能让 AI 以评审者的视角检查代码输出问题列表和改进建议。技能里会定义评审的维度可读性、性能、安全性、可测试性。每个维度下还有具体的检查点。这个技能我通常在提交代码前跑一遍能提前发现不少低级问题。提交信息生成技能这个技能看起来简单但很实用。它定义了提交信息的格式比如约定式提交、语言中文还是英文、详细程度。调用之后AI 会根据代码变更自动生成符合规范的提交信息省去了手动组织语言的时间。下面这个表格是我对这几个开发流程类技能的对比总结方便你快速判断优先级技能名称解决的核心问题使用频率上手难度代码生成代码风格不一致极高低单元测试测试覆盖不完整高中代码评审低级问题漏检中低提交信息生成提交信息不规范高低3.2 文档与知识管理类技能让输出自动结构化文档类技能是我觉得被低估的一类。很多人只关注“写代码”的效率忽略了“写文档”同样消耗大量时间。superpowers 里的文档类技能核心思路是把文档结构固化把内容填充交给 AI。API 文档生成技能这个技能定义了文档的章节结构接口说明、请求参数、响应示例、错误码AI 会根据代码里的注释和类型定义自动填充内容。我试过在一个中型项目里用这个技能原本需要半天写的接口文档压缩到了一个小时以内而且格式统一不会出现“这个接口写了错误码那个接口忘了写”的情况。变更日志生成技能这个技能会根据提交记录自动生成变更日志按类型分组新增、修复、优化并且会过滤掉不重要的提交。技能里可以配置过滤规则比如“跳过以 chore 开头的提交”。这个技能在发版前特别有用省去了手动整理提交记录的时间。知识库整理技能这个技能用于把零散的笔记、讨论记录整理成结构化的知识条目。技能里定义了条目的格式标题、背景、结论、参考链接。我平时会把一些技术调研的碎片记录丢给这个技能让它整理成可以归档的文档。文档类技能的一个关键点是输出格式的稳定性。我在技能里会明确指定用 Markdown、标题层级怎么分、表格怎么用。这样生成出来的文档可以直接放进项目仓库不需要二次排版。3.3 调试与排查类技能把经验固化成可执行步骤调试类技能是我个人最看重的一类因为调试往往是最耗时的环节而且高度依赖经验。把调试经验做成技能相当于把老手的思路复制给了整个团队。错误日志分析技能这个技能定义了分析日志的步骤先看错误类型再看堆栈顶部然后定位到具体文件和行号最后给出可能的原因和验证方法。技能里还会要求 AI 输出“下一步排查建议”而不是直接给结论。这一点很重要因为 AI 给的结论不一定对但排查建议可以引导人继续往下查。性能问题排查技能这个技能针对的是“接口变慢”、“内存上涨”这类问题。技能里定义了排查顺序先看监控指标再看慢查询日志然后看代码里的循环和数据库调用。每一步都有具体的检查命令和判断标准。我试过用这个技能排查一个接口超时问题AI 按照技能步骤引导我一步步缩小范围最后定位到一个没加索引的查询整个过程比我平时凭感觉排查快了不少。依赖冲突排查技能这个技能用于处理“装了新库之后项目跑不起来”的情况。技能里定义了检查依赖树的命令、常见的冲突模式、以及解决策略升级、降级、排除传递依赖。这个技能在多人协作的项目里特别有用因为依赖冲突往往和具体环境相关有了技能之后排查步骤是统一的。调试类技能的一个注意事项是技能里要写清楚“什么情况下不要用这个技能”。比如错误日志分析技能如果日志本身不完整硬套步骤反而会浪费时间。我在技能里加了一条“如果日志缺少关键堆栈信息先补充日志再分析”避免误用。4. 怎么引入这些技能从零到跑通的完整操作4.1 引入前的准备工作环境与目录结构在引入技能之前需要先确认两件事你的 AI 助手支持哪种技能引入方式以及你打算把技能文件放在哪里。不同助手的引入机制不一样有的支持读取本地目录有的需要把技能内容粘贴到配置里有的支持从远程仓库拉取。我建议先查一下你所用助手的文档确认它支持的引入方式。目录结构方面我习惯在项目根目录下建一个skills文件夹里面每个技能一个子目录子目录里放一个SKILL.md文件。这种结构的好处是清晰、可版本化、容易分享。如果你有多个项目也可以建一个全局的技能目录然后在各个项目里通过软链接或者配置引用。# 推荐的目录结构 project-root/ skills/ code-gen/ SKILL.md unit-test/ SKILL.md code-review/ SKILL.md每个SKILL.md文件里我通常会包含这几个部分技能名称、适用场景、执行步骤、注意事项、输出格式。这个结构不是强制的但保持统一会让 AI 助手更容易解析。4.2 技能文件的编写规范与字段说明技能文件写得好不好直接决定了技能能不能被正确触发、能不能稳定执行。我总结了几条编写规范都是实际踩坑之后总结出来的。技能名称要具体。不要叫“测试技能”要叫“Python 单元测试生成技能”。名称越具体AI 助手匹配时越不容易选错。适用场景要写清楚“什么时候用”和“什么时候不用”。只写“什么时候用”是不够的因为 AI 助手可能会在不合适的场景下强行调用。加上“什么时候不用”可以显著减少误触发。执行步骤要可操作。不要写“检查代码质量”要写“检查代码里是否有未处理的异常、是否有硬编码的配置、是否有超过三层的嵌套”。步骤越具体执行结果越稳定。注意事项要写“坑”。比如“生成测试时不要 mock 被测函数本身”、“评审代码时不要修改代码只输出建议”。这些注意事项往往来自实际使用中的教训写进去能避免重复踩坑。下面是一个技能文件的示例结构你可以直接参考# 技能名称Python 单元测试生成 ## 适用场景 - 需要为 Python 函数或类生成单元测试时使用 - 不适用于集成测试和端到端测试 ## 执行步骤 1. 读取目标函数的签名和文档字符串 2. 识别输入参数的类型和取值范围 3. 为每个参数生成正常值、边界值、异常值 4. 使用 pytest 编写测试函数 5. 对涉及外部调用的部分使用 mock ## 注意事项 - 不要 mock 被测函数本身 - 测试函数命名要体现测试意图 - 每个测试函数只验证一个行为 ## 输出格式 - 输出完整的测试文件内容 - 使用 pytest 风格 - 包含必要的 import4.3 把技能接入 AI 助手的三种常见方式接入方式取决于你用的助手。我试过三种方式各有适用场景。第一种本地目录读取。如果助手支持读取本地文件直接把skills目录配置进去就行。这种方式最方便技能文件改了之后立即生效适合个人使用和小团队。第二种配置内嵌。有些助手需要把技能内容写在配置文件里。这种方式的好处是技能和助手配置在一起不容易丢失缺点是技能多了之后配置文件会很长维护起来麻烦。我的做法是只把最高频的两三个技能内嵌其他的用本地目录。第三种远程仓库拉取。如果团队多人使用可以把技能仓库放在远程助手启动时自动拉取。这种方式适合团队协作能保证所有人用的是同一版本。需要注意的是远程仓库的访问权限要配置好避免技能文件泄露。不管用哪种方式接入之后都要做一次验证随便描述一个任务看助手能不能正确识别并调用对应的技能。如果识别不到检查技能名称和适用场景的描述是否足够清晰。5. 安装 superpowers 的实操步骤与参数配置5.1 安装前的依赖检查与版本确认安装 superpowers 之前先确认你的环境满足基本要求。虽然不同实现方式的要求不一样但有几项是通用的AI 助手本身要能读取外部文件或配置运行环境要有文件读写权限如果涉及远程拉取还需要网络访问权限。我建议先做一次依赖检查把当前环境的版本信息记录下来。这样如果安装过程中出现问题排查时有参照。检查的内容包括助手版本、运行环境版本、文件系统权限。如果团队里多人安装最好统一版本避免因为版本差异导致技能行为不一致。提示安装前先备份现有的助手配置。技能引入可能会修改配置文件备份之后万一出问题可以快速回滚。5.2 分步安装流程与关键参数说明安装流程我拆成五步每一步都有需要确认的参数。第一步获取技能文件。可以从团队仓库拉取也可以自己编写。如果是拉取确认拉取的是最新版本。如果是自己编写先写一个最简单的技能做测试。第二步放置技能文件。按照前面说的目录结构把技能文件放到skills目录下。确认文件权限是可读的。第三步配置助手读取路径。在助手的配置里指定技能目录的路径。这里的关键参数是路径格式不同系统对路径的写法要求不一样Windows 用反斜杠Linux 和 macOS 用正斜杠。路径写错是安装失败最常见的原因。第四步重启或重载助手。大部分助手需要重启才能读取新配置。重启之后确认助手能识别到技能目录。第五步验证技能可用性。描述一个匹配技能场景的任务看助手是否调用对应技能。如果没调用检查技能名称和场景描述。{ skills: { directory: ./skills, autoLoad: true, refreshInterval: 300 } }上面是一个配置示例关键参数有三个directory指定技能目录autoLoad控制是否自动加载refreshInterval控制刷新间隔。refreshInterval的单位是秒设得太短会增加开销设得太长技能更新不及时我一般设 300 秒。5.3 安装后的验证方法与常见报错处理安装完成后不要急着投入正式使用先做一轮验证。验证的方法是准备三个不同类型的任务分别对应三个技能看助手能不能正确匹配。如果三个都能匹配说明安装基本成功。常见的报错有这么几类。路径错误助手提示找不到技能目录检查路径拼写和权限。格式错误技能文件解析失败检查 Markdown 格式是否规范特别是标题层级和列表缩进。匹配失败助手能读取技能但不会调用检查技能名称和适用场景是否足够具体。冲突错误多个技能同时匹配一个任务检查技能之间的场景描述是否有重叠。我遇到最多的是匹配失败原因通常是技能名称太宽泛。比如把技能命名为“代码技能”助手不知道什么时候该用。改成“Python 函数代码生成技能”之后匹配就准确多了。6. 常见问题与排查技巧实录6.1 技能不触发、触发错误、执行不完整怎么办技能不触发是最常见的问题。排查思路是先确认技能文件被正确加载再确认任务描述和技能场景是否匹配。如果技能文件加载了但任务描述不匹配可以试着在任务描述里加入技能名称里的关键词。比如技能叫“单元测试生成”任务描述里就带上“单元测试”这几个字。触发错误指的是助手调用了不相关的技能。这通常是因为技能之间的场景描述有重叠。解决方法是把每个技能的“不适用场景”写得更明确。比如“代码评审技能”里写明“不适用于生成新代码”这样助手在生成代码时就不会误调用评审技能。执行不完整指的是助手调用了技能但只执行了部分步骤。这往往是因为技能步骤写得太笼统或者步骤之间有依赖关系但没写清楚。我的做法是把步骤拆得更细并且在步骤之间加上“完成上一步后再执行下一步”的提示。6.2 技能冲突与优先级设置的实战经验当技能数量增多时冲突几乎不可避免。两个技能可能都声称适用于某个场景助手不知道该用哪个。解决冲突有两种思路一是调整场景描述让适用范围不重叠二是设置优先级让助手在冲突时优先选择高优先级技能。优先级设置我一般遵循两个原则具体技能优先于通用技能高频技能优先于低频技能。比如“Python 单元测试生成”比“通用测试生成”更具体应该优先。设置优先级的方式因助手而异有的支持在技能文件里写优先级字段有的需要在配置里指定。我试过在一个项目里同时维护十几个技能冲突很频繁。后来砍到六个核心技能冲突基本消失了。这让我意识到技能库的规模需要控制不是越多越好。6.3 技能库维护与迭代的注意事项技能库是需要维护的。我建议每隔一段时间做一次技能审查看看哪些技能还在用、哪些已经过时、哪些需要更新。审查的周期可以是一个月一次或者每个迭代周期一次。更新技能时要注意版本兼容。如果技能被多个项目引用更新之前要确认不会破坏现有项目。我的做法是给技能文件加版本号更新时先在小范围测试确认没问题再推广。还有一个容易被忽略的点是技能文档。技能文件本身是给助手读的但团队新人需要一份给人读的技能说明。我通常会在技能目录下放一个README.md说明每个技能的用途、适用场景、以及如何新增技能。这份文档不需要很详细但能显著降低新人的上手成本。常见问题可能原因排查方法解决方式技能不触发场景描述不匹配检查任务描述关键词补充关键词或调整场景描述触发错误技能技能场景重叠对比多个技能的适用场景明确不适用场景或设优先级执行不完整步骤太笼统检查技能步骤是否可操作拆细步骤并加依赖提示安装后无反应路径或权限问题检查配置和文件权限修正路径或调整权限7. 我个人的使用体会与后续扩展方向用了一段时间 superpowers 这套机制之后我最大的体会是技能化的价值不在于让 AI 更聪明而在于让 AI 更稳定。AI 本身的能力已经很强了但它的输出质量波动很大同样的任务今天做得好明天可能就做得差。技能的作用是把“好的做法”固化下来让每次执行都尽量靠近那个好的标准。另一个体会是技能库需要“养”。一开始不要追求大而全先做两三个最高频的技能用起来在用的过程中发现问题、迭代改进。我最早做的“单元测试生成”技能前后改了七八版每一版都是因为实际使用中发现了新的问题。这种迭代是必要的不要指望一次写出完美的技能。后续扩展方向我目前在尝试的是技能之间的组合调用。比如“代码生成”技能生成代码后自动调用“单元测试生成”技能为生成的代码写测试再调用“代码评审”技能做一次检查。这种组合能进一步减少手动操作。不过组合调用对技能之间的接口定义要求更高我还在摸索阶段。最后分享一个小技巧技能文件里的“注意事项”部分尽量写你实际踩过的坑而不是从文档里抄来的通用建议。因为通用建议 AI 本来就知道只有那些具体的、反直觉的坑才真正需要写进技能里。比如“生成测试时不要 mock 被测函数本身”这条就是我在实际使用中发现 AI 经常犯的错误写进技能之后这个问题基本没再出现过。