Superpowers技能包：模块化Prompt工程让AI助手高效执行专业任务

我原本只是在捣鼓自建的AI助理，想让它别整天说正确的废话。试过在system prompt里塞各种要求，结果不是太长被截断，就是换一个任务就得重新调一遍。后来在一个开源仓库里看到了superpowers这个项目，简单说它是一套给AI助手装配“专业技能”的工具包，用模块化技能的方式让AI在代码审查、写作润色、数据分析这些具体场景下迅速进入状态。如果你也是用API自建AI应用、每天要折腾大量prompt的人，这东西能帮你把零散的提示词系统化。这篇内容会把它的设计思路、技能清单和安装流程完整拆开讲清楚。

先直接回答大家最关心的几个问题：superpowers到底是什么、能干什么、适合谁。它本质上是一组可组合、可复用的skill模块，每个模块就是一个精心设计过的“岗位说明书”，AI读了之后能在特定任务上表现出远超裸奔状态的能力。你也完全不用被项目名字吓到，这不是什么“一键获得AGI”的黑魔法，而是一套经过工程化整理的提示词管理方案。后面我会带你从零把它装上，再手把手调出一个能直接用的技能组合。

1. 内容整体设计与思路拆解

1.1 superpowers到底解决什么问题

用聊天界面里的AI和用API自建AI，体验差距最明显的地方就是“角色切换”。在网页对话框里，你可以随手打一句“你现在是资深律师，帮我审这份合同”，模型基本能演到位。但放到产品里，面对几十上百个用户、每天换着花样提需求，总不能每次都把“角色设定+任务描述+输出约束”这三件套重新拼一遍。

superpowers对这个问题给出的方案是：把三类要素打包成独立技能。哪三类？第一，身份设定，告诉AI当前应该用什么视角看问题；第二，任务流程，规定它按什么顺序处理输入；第三，输出规范，约束回复的格式、长度和语气。每个技能就是一个文件，用的时候按需加载，用完即卸，不污染其他任务的上下文。

这个思路和“把prompt写在代码里”有本质区别。写在代码里，意味着每次需求调整都要发版、都要走流程；而技能文件是运行时加载的，改一行描述就能立刻生效。我实际用下来，迭代prompt的速度至少快了一倍。更关键的是，相同技能的prompt是全局统一的，不会出现“同样叫代码审查，A用户拿到的是中文输出，B用户拿到的是英文输出”这种不一致问题。

1.2 为什么是“技能包”模式而非超长指令

说实话，我一开始想过把几十条要求写进一个超长system prompt里，让AI自己判断该用哪部分。但现实很骨感。上下文窗口就这么大，你把两三千字的规则塞进去，留给真实对话内容的token就少了，模型反而更容易遗忘前面的指令。而且超长prompt内部常常自相矛盾，比如既要求“简洁”又要求“全面”，AI基本会选一个折中结果，两头不讨好。

superpowers的模块化思路和写代码的习惯很像：单一职责、高内聚低耦合。每个技能只做一件事，比如doc-writer只负责结构化输出文档，code-reviewer只负责审查代码。用的时候把它们装进对话，一个负责理解输入，一个负责生成输出，各有分工，互不干扰。这种“组合优于继承”的设计，在prompt工程里同样成立。

还有一个容易忽略的优点，就是可测试性。单独一个技能，你可以分别验证它的效果，出了问题方便定位。我见过不少团队把几段prompt粘在一起，最后模型回复扯淡了，根本分不清是哪段提示词在捣乱。技能包里一个文件对应一个场景，出毛病直接换文件，排查成本极低。

1.3 方案选型背后的三个核心考量

选择用superpowers这套模式而不是其他prompt管理工具，我主要看中三点。

一是离线优先。所有技能都是本地文件，不依赖第三方平台，不担心哪天服务下线导致整套技能失效。只要你的AI模型不被替换，技能文件就能一直用。二是格式简单。每个技能用markdown书写，不懂编程也能看懂结构，团队协作时互审门槛低。三是生态开放。它不绑定特定模型，GPT、Claude、国产模型都通用，因为本质就是文本注入，模型能理解自然语言就能用技能。

当然，它也有代价。最明显的是“基本盘”依赖：技能质量取决于编写者的水平，如果你照着网上的模板乱改，效果可能还不如随便写一段提示词。另外，加载多个技能时token消耗会上升，这个也需要做取舍，后面我会展开步给大家算一笔账。

2. 核心细节解析与实操要点

2.1 有哪些skills：常用技能清单与适用场景

superpowers的技能库是开放的，任何人都能提交自己的技能文件。项目自带的基础技能目前覆盖了常见的生产力场景，我挑几个使用率高的列出来供参考。

每个技能可以直接独立使用，也可以链式组合。比如你让AI“先审查代码，再把审查结果整理成周报”，这一个请求其实触发了两个技能。superpowers内部有一套技能调度机制，当识别到链路关系后，会按依赖顺序依次加载。

2.2 技能包的内在机制：上下文注入与输出约束

很多人以为一个技能就是一段固定的话术，加载时塞给模型就完事了。实际没那么简单。superpowers对每个技能的处理分了四个阶段。

阶段一是解析触发词。每个技能文件头部都有一个metadata区域，写明了技能名称、描述、触发条件和优先级。主程序拿到用户消息后，先做一轮意图匹配，判断当前对话该激活哪些技能。匹配不上就采用默认的通用模式，不会强行加载。

阶段二是上下文组装。激活的技能会按照预设顺序，与用户的真实输入一起拼接进prompt。基础提示词在最前面声明身份和能力边界，中间是技能指令，最后是本次的具体任务。这个顺序有讲究，模型对靠前的内容注意力更强，所以身份声明放顶部，技能规则紧随其后，确保模型不会在“我是谁”上跑偏。

阶段三是行为注入。不只是把技能文本塞进去，还会注入与技能配套的执行步骤。比如code-reviewer内部定义了一套审查流程：先读代码结构，再检查潜在bug，下次评估性能风险，最后给改进建议。有了这套流程，模型就不再是“看完代码直接给结论”，而是“按流程一顿操作后给出结构化结论”，质量明显稳定。

阶段四是输出约束。这一层控制生成格式和token预算。技能文件中可以指定输出为JSON、Markdown、纯文本，也可以限制响应长度。我见过很多prompt翻车，不是模型不懂，而是限制条件太少，输出又长又空。superpowers把输出规范写进技能文件，等于给模型戴上缰绳。

2.3 安装时要避开的坑

安装步骤看起来简单，但有几个细节容易踩雷，我一开始就是没注意这些，白折腾了一个多小时。

第一个坑是路径编码问题。技能文件名如果用中文，在某些终端环境下会乱码，导致匹配失败。建议所有技能文件名只用英文小写加连字符，在技能内部metadata里再写中文描述即可。第二个坑是环境变量缺失。部分技能会调用外部配置（比如API密钥），加载时报错说找不到环境变量，但主程序启动时又没有自动检查。建议安装后先跑的验证命令是对所有技能做静态检查，而不是一上来就调对话接口。第三个坑是版本不兼容。有些第三方技能文件是按旧版API写的，字段名和当前主程序对不上，直接用会报Schema错误。遇到这种情况，看一下报错信息里的字段名，再对照metadata模板改正即可。

3. 实操过程与核心环节实现

3.1 环境准备与依赖安装

我推荐用Node.js环境来跑superpowers，因为它的技能解析器和调度器都是Node实现的，生态最成熟。先确认一下你本机的Node版本，建议16以上，太老的话某些语法会跑不动。

安装分三步：拉取代码库、安装依赖、初始化配置。直接看命令。

git clone https://github.com/你的仓库地址/superpowers.git cd superpowers npm install cp .env.example .env

如果你的网络环境访问GitHub比较吃力，也可以直接下载代码压缩包。项目本身没有太多第三方依赖，npm install中途报错的话，多半是源的问题，换个镜像源就顺了。

装完依赖之后，打开.env文件，填入你自己的模型API配置。superpowers本身不产出模型能力，它只负责把技能加载到上下文里，最终回复还是由底层大模型生成，所以你得准备一个可用的模型API密钥。用GPT、Claude或者国产模型都可以，只要在配置里把接口地址和模型名称指对就行。

3.2 引入技能：从零注册一个自定义技能

superpowers能用的技能大部分不用自己写，社区库里有现成的。但为了让你以后能自己扩展，我建议按官方模板走一遍注册流程，顺便也方便你验证主程序是否正常。

技能的存放目录叫skills，里面每个子目录就是一个独立技能。子目录里固定有一个SKILL.md文件，内容分两部分：YAML格式的metadata区块和Markdown格式的指令正文。看个简化示例。

--- name: doc-writer description: 根据对话内容生成结构化技术文档 trigger: 写文档、生成文档、doc priority: 80 version: 1.0.0 --- 你是一位资深技术文档工程师。接到任务后，按以下步骤处理： 1. 从对话中提取文档的关键信息，判断文档类型（API文档、使用指南、设计说明）。 2. 先输出文档目录，让用户确认后再写正文。 3. 正文部分需包含：概述、使用环境、步骤说明、参数表、示例、常见问题。 输出规范： - 使用Markdown格式，标题层级不超过四级。 - 每个章节至少包含一个具体示例。 - 如果输入信息不足，明确列出缺失项，不要编造内容。

保存好之后，在主程序的配置文件里注册一下这个技能。注册时主要写技能目录名、匹配方式和默认启用的会话类型。完成后跑一遍技能自检命令，能通过说明你的技能文件格式正确、解析无误。

这个流程走完，你就拥有第一个自定义技能了。实际上官方技能和自己写的技能，在supwerpowers内部没有任何身份差异，都只是“一个会加载的指令文件”。这也正是这套系统扩展性很强的原因——门槛低，谁都能往里加技能。

3.3 组合使用多个技能：一次搞定代码审查加周报

单一技能学会之后，最值得练习的是组合方案。我拿一个实际工作流来演示：同事让我帮忙审查一段代码，同时希望把审查结果放进本周周报。

常规做法是先让AI审查，拿到结果后重新开一个对话，把结果丢进去让它写周报。中间还得自己复制粘贴，麻烦不说，还可能因为上下文切换导致信息丢失。用superpowers，一个请求就能做完。

关键步骤在于配置一个自定义工作流：新增一个流程文件，声明它的步骤列表是step1=code-reviewer，step2=weekly-report。运行时，主程序先加载code-reviewer处理代码输入，产出结构化审查意见；接着把审查意见作为weekly-report技能的输入，让它生成包含“本周代码风险”区块的周报。整个链路在内存中完成，用户只提交一次请求就能收到成稿。

我在实际使用中发现，组合技能时最重要的事情是预设好中间产物格式。code-reviewer和weekly-report能顺畅衔接，就是因为前者的输出规范规定了必须包含“问题级别、问题描述、修改建议”三个字段，后者读了这些字段就能直接写入周报对应位置。如果你自己组合两个技能，也要确保前一个技能的output格式是后一个技能能直接消费的。

3.4 参数选择与token预算控制

聊到实操，token开销必须算清楚。我发现不少人装完superpowers后的第一个震惊是“回复怎么变贵了”，因为每个技能都吃token。以code-reviewer为例，技能指令文件的中文版大概500到800字，转换成token大约是700到1100；如果要完整加载完整的审查流程模板，可能还会多出400到600 token。也就是说，每激活一个技能，单次请求的输入token大约会增加1500左右。

这个数字看起来不小，但要注意这是一次性投入。如果不用技能，你可能要在prompt里反复描述同样的话，每次对话都花掉几百上千token；用技能之后，这部分开销其实是固定的，对话内容越多，摊薄下来越划算。在配置里还有一个参数叫max_skill_token，用来限制单个技能允许使用的最大token量，超出时自动截断技能指令的冗余部分。我建议设成1200左右，保证指令基本完整的同时，给对话内容多留空间。

另外，多个技能同时加载时，system prompt的总长度要控制。拿gpt-4o这样的模型来说，上下文窗口算大，但如果你一口气装七八个技能，每个1500 token，光技能指令就吃掉了超过1万token，聊天内容的空间就紧张了。我的经验是单个会话同时激活的技能尽量控制在3到5个，优先级低的让位给核心技能。

4. 常见问题与排查技巧实录

4.1 技能不生效：指令没进上下文

最典型的故障是用户发送消息后，模型回复看起来和没有装技能一个样，该结构化输出还是自由发挥。排查步骤要从技能匹配查起。先看主程序的日志，查找“skill matched”那一行。如果显示matched为空，说明触发条件不满足，去检查用户消息里是否包含技能metadata中定义的trigger关键词。很多技能对触发词有相似度要求，默认阈值是0.7，太口语化的表达可能匹配不上，可以把阈值调低到0.5，但误触发概率也会上升。

如果匹配到了技能但回复仍然不像样，那就是技能指令没被正确注入上下文。打开调试模式，把发给模型的完整prompt打印出来，直接搜索技能名称。搜索不到，说明主程序的prompt组装逻辑出了问题；搜得到但回复不听话，多半是技能指令中的边界约束写得太弱，模型觉得可以“自由发挥”。

4.2 多个技能相互干扰：优先级和隔离问题

同时加载三四个技能时，偶尔会出现模型“串台”，比如让它写代码审查周报，结果它先来一段代码解析，又跳到周报格式，最后输出四不像。这通常是因为技能之间的优先级和职责边界没定清楚。

解决办法是调整metadata中的priority值，数值越高的技能越早加载，占据更靠前的位置，对模型的影响也更强。比如在code-reviewer和weekly-report组合里，code-reviewer的优先级设为90，weekly-report设为70，模型会先按代码审查的视角处理输入，再把结果输出成周报格式。

还有一个技巧是给技能设置scope字段。比如code-reviewer的scope设置为“本轮对话”，weekly-report的scope设置为“整个会话”。这样第一个技能只在当前处理阶段生效，第二个技能能持续影响后续回复。如果你发现某个技能老在无关对话里刷存在感，多半是它的scope设得太宽了。

4.3 上下文溢出与token超限

技能装多了，最常见的异常是请求直接报错，提示token超限。这时候别盲目减技能数量，先看哪个技能是大头。主程序的运行日志每次都会记录各技能实际消耗的token数，拉出来排个序，优先裁剪最占内存的那一个。

如果单个技能的文件本身非常大，比如一些技能附带完整的示例库和大会话列表，可以把它拆成两个文件：瘦身版只保留核心指令，通过按需加载方式在需要深度处理时才启用。另外，还要注意tokens的“安全边际”。模型的最大输入token是硬上限，但在真实对话中，你还需要给生成输出留空间。比如模型总窗口是8000 token，建议把所有技能指令加起来控制在5000以内，剩下的留给对话历史和回复生成。

4.4 自定义技能开发中的常见报错

最频繁的自定义报错是metadata字段写错。SYAML头部少个空格、多一个冒号，解析阶段就会直接失败。官方模板里的metadata结构很简单，但很多人喜欢往里面塞自定义字段，比如author、tags，结果主程序不认识就开始报未知字段错误。如果你想加辅助信息，建议放在正文末尾，别往metadata里硬塞。

第二个高频报错是“skill not found”，明明skills目录里有这个文件夹，但主程序就是找不到。基本都是大小写不一致或者文件名带空格导致的，用驼峰命名或中文名都容易出问题。我统一建议改成小写加横线风格，比如my-custom-skill，从源头消灭这类低级问题。

第三个问题是触发词过于宽泛。很多新手喜欢把trigger设成“写作”，结果每次对话都同时触发三四个技能。触发词一定要和技能的核心特长强绑定，宁可窄一点、精确一点，也别追求一击命中。比如改代码技能的trigger，设“修改代码”“重构”“修复bug”，比设一个“代码”要精准得多。

4.5 性能调优：加载速度优化

如果你把superpowers集成到线上服务里，加载性能就要考虑。技能文件的读取和解析虽然快，但频繁IO还是会有损耗。项目支持把常用技能预热到内存缓存里，第二次调用时可以直接命中。我建议在服务启动时就把最常用的三五个技能加载好，其他技能用懒加载。启动耗时多了一两百毫秒完全能接受，换来的是平时响应时间大幅下降。

另外，技能指令如果涉及大量外部知识，比如法律条款或行业规范，这些内容要定期更新。superpowers提供了版本管理功能，每个技能的metadata里带version字段。建议你更新技能文件时同步改版本号，并把“上次更新日期”也写进去，维护起来心里有数。

5. 从“能用”到“好用”：围绕superpowers的进阶实践

5.1 用技能库沉淀团队prompt资产

superpowers给我带来最大的变化不单是个人效率提升，而是团队里零碎的prompt终于有了统一归档的地方。以前大家各写各的，谁有一套“好用的提示词”都是私藏，现在全部落盘到skills目录，新人进来直接看技能清单，就知道这个团队常用哪些AI能力。

我建议团队里安排一个prompt维护者，定期收集日常对话中效果好的要求，看能不能沉淀成技能文件。这么做有两个好处，一来优秀实践能共享，二来出问题时能追溯到具体技能文件，复盘效率高。

5.2 让技能文件适配不同模型

有个现象值得注意，同一套技能在GPT上效果好，换到开源模型上可能表现平平。原因在于，技能指令里默认模型具备某些推理能力，比如思维链、函数调用，但并非所有模型都支持得一样好。

我在使用中发现一个小技巧：在技能metadata里增加一个model字段，注明当前指令最适配的模型。主程序加载时看到model字段，会自动做“调整”：如果和当前模型不匹配，就切换成通用指令模式，避免硬套导致效果崩坏。这个字段不是必须的，但如果你经常在多个模型之间切换，强烈建议写上。

5.3 后续扩展方向

superpowers的技能机制本质上是一个“AI助手能力扩展框架”，它不限于文本处理。有人已经做了代码执行技能的集成，AI在输出代码的同时，可以附带执行参数，由外部沙箱组件接手运行。还有人把知识库检索技能加了进来，AI回答前先搜索本地文档，显著减少幻觉。

我自己的实践是把superpowers和自动化工作流工具连起来用。当周报技能生成文本后，再交给后续节点自动排版、发送到指定平台。整个过程不再需要人工复制粘贴，解放了不少重复劳动。

结尾

最后分享一点实实在在的体会。工具再强，也只是放大器——超级模型配上超级技能，效果可能好到超乎想象；但如果你只会机械地装一堆技能却不理解背后的原理，那AI生成的还是华丽但空洞的内容。superpowers真正的价值在于，它逼你把“AI的工作职责”想清楚：每个技能负责什么、边界在哪里、输出怎么和下游衔接。想明白了这套，哪怕离开这个工具，你写prompt的水平都已经上了一个台阶。

再补一个小技巧：给技能排优先级时，不要只看“完成度”，还要看“恢复度”。如果一个技能挂了，它对整个对话流程影响多大？核心流程里的技能，尽量保持精简，能一句话说清楚就别写三段。记住，superpowers的维护成本随着技能数量增长，定期清理没人用的技能，比什么功能都重要。