1. 从“superpowers”这个标题说起它到底指什么第一次看到“superpowers”这个词很多人脑子里蹦出来的可能是漫威电影里的超能力或者是某些游戏里的技能系统。但如果你是在技术社区、开发者论坛或者某个项目仓库里刷到这个标题那它大概率不是指超能力而是一个面向 AI 编程助手的技能扩展框架。我最早接触这个概念是在一个开源项目的讨论区当时有人发帖问“想要安装 superpowers有没有详细的步骤”底下跟了一堆回复有人说是插件有人说是提示词库还有人说是某种工作流引擎。实际上它更像是一套给 AI 编程助手“加装技能包”的机制——通过预定义的技能模块让 AI 在写代码、调试、重构、写文档等场景下表现得更像一个有经验的工程师而不是一个只会补全代码的机器。这个标题之所以能成为热词核心原因在于大家已经不再满足于 AI 只是“能写代码”而是希望它“会写代码”。这两者之间的差距就是 superpowers 这类项目要填的坑。你想想一个刚入行的程序员和一个干了十年的老手区别在哪不是谁敲键盘快而是老手知道什么时候该抽象、什么时候该偷懒、什么时候该写测试、什么时候该直接硬编码。superpowers 想做的就是把这些“老手的直觉”变成 AI 可以调用的技能模块。那这篇文章适合谁看如果你是正在用 AI 辅助编程的开发者或者你想给自己的 AI 工作流加一套可复用的技能体系再或者你只是好奇“给 AI 装技能”到底是怎么实现的那接下来的内容应该能让你少走不少弯路。我会从整体设计思路、核心细节、实操安装、常见问题四个维度把 superpowers 这个东西拆开揉碎讲清楚。文章里提到的具体命令和配置都是基于常见实践补全的你可以直接抄作业也可以根据自己的环境调整。2. 整体设计与思路拆解为什么是“技能包”而不是“大而全”2.1 核心思路把“编程经验”拆成可插拔的模块superpowers 最核心的设计哲学用一句话概括就是不要试图训练一个全知全能的 AI而是给它一套可以按需加载的技能包。这个思路其实和人类团队管理很像。你不会指望一个刚毕业的应届生同时精通前端、后端、运维、数据库、安全、性能优化但你可以给他一本《团队开发规范》里面分章节写了“提交代码前要跑哪些检查”“遇到内存泄漏怎么排查”“写 API 文档的模板是什么”。superpowers 做的就是这本规范只不过它的读者是 AI。具体来说它把常见的编程任务拆成了若干技能域比如代码生成类根据需求描述生成符合项目风格的代码片段调试排查类根据报错信息定位问题根因并给出修复建议重构优化类识别代码坏味道并执行安全的重构操作文档撰写类自动生成 README、API 文档、变更日志测试编写类根据函数签名和边界条件生成单元测试每个技能域下面又细分了具体的技能条目每个条目包含触发条件、执行步骤、输出格式、注意事项。这种结构的好处是AI 不需要一次性记住所有东西而是根据当前上下文动态加载相关技能。就像你打游戏时背包里有一堆技能书遇到不同敌人翻不同的书而不是把整本攻略背下来。2.2 为什么不用“一个大提示词”解决所有问题很多人可能会问我直接写一个超长的系统提示词把所有编程规范都塞进去不就行了我试过效果很差。原因有三个第一上下文窗口是有限的。你把所有规范都塞进去AI 在处理具体任务时反而抓不住重点就像你给一个实习生一本 500 页的手册他遇到问题还是不知道翻哪一页。第二不同任务需要的“人格”不一样。写代码时需要严谨、考虑边界写文档时需要清晰、面向读者调试时需要怀疑、善于假设。一个统一的提示词很难同时满足这些。第三维护成本高。项目规范会变今天用 React 18明天可能升级到 19你改一个巨型提示词很容易漏掉关联部分。而技能包是模块化的改一个技能不影响其他技能。superpowers 的解决方案是用元数据描述技能用加载器按需注入。每个技能文件里除了技能内容本身还有一段“触发描述”告诉 AI 在什么情况下应该加载这个技能。这就像给每个技能书贴了标签AI 看到当前任务的关键词就去书架上找对应的书。2.3 技能加载的优先级与冲突处理在实际使用中你可能会遇到多个技能同时被触发的情况。比如你让 AI “重构这个函数并补充测试”那“重构优化”和“测试编写”两个技能都会被激活。这时候就需要一套优先级规则。根据我的经验常见的处理方式是显式指令优先于隐式触发如果你在提示词里明确说了“用测试技能”那就优先加载测试技能。具体技能优先于通用技能比如“Python 单元测试”优先于“通用测试编写”。安全类技能最高优先级涉及代码安全、数据保护的技能应该覆盖其他技能的输出。这套规则不是 superpowers 独有的但它在设计文档里明确提出来了说明作者确实考虑过实际使用中的冲突场景。我在配置自己的技能包时也会在技能元数据里加一个priority字段数值越大优先级越高加载器按这个排序。2.4 与现有 AI 编程工具的集成方式superpowers 本身不是一个独立的 IDE 或编辑器它更像是一个中间层。你可以把它理解成 AI 编程助手和你的代码库之间的一个“技能路由器”。常见的集成方式有三种第一种是作为插件运行。比如在某些支持插件系统的 AI 编程环境里superpowers 作为一个插件被加载它拦截用户的请求根据请求内容决定注入哪些技能然后再把增强后的请求发给底层模型。第二种是作为提示词模板库。你手动把相关技能文件的内容复制到对话开头虽然麻烦但兼容性最好。第三种是作为本地服务。superpowers 跑在一个本地端口上AI 工具通过 API 调用它来获取技能内容。这种方式适合团队协作因为技能包可以集中管理、版本控制。我个人的选择是第二种和第三种结合日常快速任务用模板库团队项目用本地服务。这样既灵活又能保证一致性。3. 核心细节解析与实操要点技能文件到底长什么样3.1 技能文件的目录结构与命名规范一个典型的 superpowers 技能包目录结构是这样的superpowers/ ├── skills/ │ ├── code-generation/ │ │ ├── python-function.md │ │ ├── react-component.md │ │ └── sql-query.md │ ├── debugging/ │ │ ├── memory-leak.md │ │ ├── null-pointer.md │ │ └── async-race-condition.md │ ├── refactoring/ │ │ ├── extract-method.md │ │ └── replace-conditional.md │ └── documentation/ │ ├── readme-template.md │ └── api-doc.md ├── loaders/ │ ├── keyword-loader.js │ └── context-loader.js └── config/ └── priority.json这个结构不是强制的但遵循它有几个好处按领域分类方便查找扁平化文件避免嵌套过深加载器与技能分离便于替换实现。命名上我建议用小写字母加连字符比如memory-leak.md而不是MemoryLeak.md因为很多加载器对大小写敏感统一小写能减少跨平台问题。每个技能文件内部通常包含以下几部分--- name: python-function trigger: 当用户要求生成Python函数时 priority: 5 tags: [python, function, code-generation] --- ## 技能描述 生成符合PEP8规范的Python函数包含类型注解和文档字符串。 ## 执行步骤 1. 分析函数签名和参数类型 2. 生成函数体处理边界条件 3. 添加类型注解和docstring 4. 检查是否有明显的性能问题 ## 输出格式 直接输出代码块语言标记为python。 ## 注意事项 - 如果参数超过5个建议使用dataclass - 避免使用可变默认参数这个格式的关键在于YAML front matter它让加载器可以快速解析元数据而不需要读取整个文件。trigger字段是自然语言描述加载器可以用关键词匹配或语义相似度来判断是否激活。priority字段决定冲突时的优先级。tags用于更细粒度的过滤。3.2 触发条件的写法与常见坑写触发条件是最容易翻车的地方。我见过太多人把trigger写成“当用户需要时”这种描述等于没写因为 AI 根本不知道什么时候算“需要”。好的触发条件应该包含具体的动作、对象、场景。比如差“当用户写代码时”好“当用户要求生成、修改或解释 Python 函数时”差“当出现错误时”好“当用户粘贴报错信息并询问原因时”另一个坑是触发条件过于宽泛。比如你写“当用户提到函数时”那几乎每个编程对话都会触发这个技能导致技能被过度加载反而干扰 AI 的注意力。我的经验是触发条件里至少包含一个领域限定词如 Python、React、SQL和一个动作限定词如生成、调试、重构。还有一个细节触发条件应该用用户可能说的自然语言而不是技术术语。用户不会说“请执行代码生成技能”他会说“帮我写个函数”。所以触发条件里要包含这些口语化表达。你可以在技能文件里加一个aliases字段列出常见的同义说法加载器会一起匹配。3.3 技能内容的粒度控制多细才算合适技能粒度太粗一个技能包打天下那就退化成大提示词了粒度太细每个技能只处理一个具体问题加载器会频繁切换效率低。我的经验法则是一个技能应该对应一个“可独立交付的工作单元”。比如“生成 Python 函数”是一个合适的粒度因为它的输入输出很明确“处理所有 Python 代码问题”就太粗了“处理 Python 函数参数默认值”又太细了因为这种细节应该写在“生成 Python 函数”技能的注意事项里。另一个判断标准是复用频率。如果一个技能在多个不同任务中都会被用到那它值得单独成文件如果只在特定场景用一次那可以合并到相关技能里。比如“添加类型注解”这个操作在生成函数、重构函数、修复类型错误时都会用到那它就可以作为一个独立技能被其他技能引用。3.4 版本管理与团队协作的注意事项superpowers 技能包本质上是一堆 Markdown 文件所以它天然适合用 Git 管理。但有几个地方需要特别注意第一技能文件的变更应该走代码审查流程。因为技能内容直接影响 AI 的输出质量一个错误的技能描述可能导致 AI 生成有问题的代码。我们团队的做法是技能文件的修改必须至少一个人 review并且要在测试环境验证过。第二技能包应该按项目或团队分仓库。不要把所有项目的技能都塞在一个仓库里因为不同项目的技术栈、规范、偏好都不一样。可以有一个“基础技能包”仓库包含通用的编程技能然后每个项目有一个“项目技能包”仓库继承基础包并覆盖特定配置。第三技能文件里不要硬编码敏感信息。我见过有人在技能文件里写了数据库连接字符串作为示例这非常危险。技能文件应该只包含方法论和模板具体配置通过环境变量或配置文件注入。4. 实操过程与核心环节实现从零安装到跑通第一个技能4.1 环境准备与依赖检查在安装 superpowers 之前你需要确认几件事你的 AI 编程工具支持自定义提示词或插件机制。如果不支持那你只能手动复制技能内容到对话里体验会差很多。你有 Node.js 或 Python 环境。大多数 superpowers 加载器是用 JavaScript 或 Python 写的因为这两种语言生态里处理 Markdown 和 YAML 的库最成熟。你的项目有明确的代码规范。如果团队连基本的命名规范都没有那技能包写出来也是空的。我建议先用一个最小化环境测试新建一个空目录初始化 Git创建一个skills文件夹放一个最简单的技能文件然后写一个加载器脚本读取它。跑通这个流程后再往里面加更多技能。4.2 安装步骤以本地服务模式为例假设你选择本地服务模式下面是具体的安装步骤。首先克隆仓库如果你是从零开始就自己创建目录结构mkdir superpowers cd superpowers git init mkdir -p skills/code-generation loaders config然后创建第一个技能文件skills/code-generation/python-function.md内容参考上一节的模板。接着写一个简单的加载器loaders/keyword-loader.jsconst fs require(fs); const path require(path); const matter require(gray-matter); function loadSkills(skillsDir) { const skills []; const categories fs.readdirSync(skillsDir); for (const category of categories) { const categoryPath path.join(skillsDir, category); if (!fs.statSync(categoryPath).isDirectory()) continue; const files fs.readdirSync(categoryPath); for (const file of files) { if (!file.endsWith(.md)) continue; const content fs.readFileSync(path.join(categoryPath, file), utf-8); const { data, content: body } matter(content); skills.push({ name: data.name, trigger: data.trigger, priority: data.priority || 0, tags: data.tags || [], body }); } } return skills.sort((a, b) b.priority - a.priority); } function matchSkills(skills, userInput) { const input userInput.toLowerCase(); return skills.filter(skill { const triggerWords skill.trigger.toLowerCase().split(/[,、\s]/); return triggerWords.some(word word.length 1 input.includes(word)); }); } module.exports { loadSkills, matchSkills };这个加载器做了两件事读取所有技能文件解析元数据根据用户输入的关键词匹配技能。实际使用时你可以把它包装成一个 HTTP 服务const express require(express); const app express(); app.use(express.json()); const skills loadSkills(./skills); app.post(/match, (req, res) { const { input } req.body; const matched matchSkills(skills, input); res.json({ skills: matched }); }); app.listen(3456, () { console.log(Superpowers loader running on port 3456); });启动服务npm init -y npm install express gray-matter node loaders/server.js然后测试一下curl -X POST http://localhost:3456/match \ -H Content-Type: application/json \ -d {input: 帮我写一个Python函数计算斐波那契数列}如果返回了python-function技能的内容说明加载器工作正常。4.3 与 AI 编程工具的对接配置不同工具的对接方式不一样但核心逻辑都是在发送用户请求之前先调用 superpowers 的匹配接口把匹配到的技能内容拼接到系统提示词里。以常见的 API 调用为例import requests def ask_ai_with_superpowers(user_input): # 1. 匹配技能 match_resp requests.post(http://localhost:3456/match, json{input: user_input}) matched_skills match_resp.json()[skills] # 2. 拼接技能内容 skill_prompt \n\n.join([s[body] for s in matched_skills]) # 3. 构造完整提示词 full_prompt f你是一个资深编程助手。请根据以下技能指导完成任务。 {skill_prompt} 用户请求{user_input} # 4. 调用AI接口这里用伪代码表示 ai_response call_ai_api(full_prompt) return ai_response这个流程的关键点是技能内容要放在用户请求之前因为大多数模型对提示词开头的注意力更高。另外如果匹配到的技能太多要按优先级截断比如只取前三个避免提示词过长。4.4 参数计算与性能考量技能加载的性能主要取决于两个因素技能文件的数量和匹配算法的复杂度。假设你有 100 个技能文件每个文件平均 2KB全部加载到内存也就 200KB完全不是问题。匹配算法如果用简单的关键词包含判断100 个技能也就是 100 次字符串查找耗时在毫秒级。真正影响性能的是提示词长度。每个技能内容平均 500 字匹配 5 个技能就是 2500 字加上用户请求和系统提示总提示词可能超过 4000 字。对于上下文窗口较小的模型这会挤占生成空间。我的做法是技能内容尽量精简只保留执行步骤和注意事项去掉冗余解释设置匹配数量上限比如最多 3 个技能对于长技能只注入摘要版本完整版本放在文件里供人工查阅另外缓存匹配结果也能提升响应速度。如果用户连续问几个相似的问题没必要每次都重新匹配。可以用一个简单的 LRU 缓存把最近 100 个请求的匹配结果存起来。5. 常见问题与排查技巧实录5.1 技能不触发或触发错误这是最常见的问题。表现是你明明写了某个技能但 AI 就是不用或者你不想用某个技能它却总是跳出来。排查思路如下现象可能原因解决方法技能完全不触发触发条件关键词与用户输入不匹配在技能文件里增加aliases字段补充同义表达技能偶尔触发匹配算法过于严格改用模糊匹配或语义相似度多个技能同时触发触发条件过于宽泛增加领域限定词提高触发门槛高优先级技能被覆盖优先级配置错误检查priority字段确保安全类技能最高我踩过的一个坑是技能文件里的trigger写的是英文关键词但用户输入是中文导致匹配失败。后来我在加载器里加了一个简单的翻译映射把常见中文术语映射到英文关键词问题就解决了。5.2 技能内容被 AI 忽略有时候技能匹配到了也注入到提示词里了但 AI 生成的结果还是不符合技能要求。这通常是因为技能内容太长被模型“遗忘”了。大模型对提示词中间部分的内容注意力会下降这叫“中间遗忘”现象。解决办法把最重要的技能放在提示词最前面或最后面在技能内容开头加一句强指令比如“必须严格按照以下步骤执行”减少单次注入的技能数量宁可分多次对话另一个原因是技能内容与用户请求冲突。比如技能要求“所有函数必须写类型注解”但用户说“给我一个快速原型不用太规范”这时候 AI 会优先满足用户显式请求。你可以在技能里加一个override字段标记哪些技能是强制性的加载器会把这些技能放在最高优先级。5.3 加载器报错与调试方法加载器报错通常集中在文件解析阶段。常见错误包括YAML 格式错误front matter 里的冒号后面没加空格或者缩进不一致。用在线 YAML 校验工具检查一下。文件编码问题Windows 下保存的文件可能是 GBK 编码导致中文乱码。统一用 UTF-8。路径错误加载器的工作目录和技能目录不一致。在代码里用path.resolve(__dirname, ../skills)这种绝对路径。调试时我习惯在加载器里加日志console.log(Loading skill: ${file}); console.log(Trigger: ${data.trigger}); console.log(Priority: ${data.priority});这样能快速定位是哪个文件出了问题。5.4 技能包维护的长期策略技能包不是写完就完了它需要持续维护。我的经验是每月回顾一次技能使用情况哪些技能经常被触发哪些从来没触发过。没触发过的要么删掉要么修改触发条件。每季度更新一次技能内容技术栈在变规范也在变。比如 Python 3.12 出了新语法相关技能就要更新。建立技能贡献流程团队成员可以提交新技能但必须附带测试用例证明这个技能在什么输入下会被触发输出是否符合预期。还有一个容易被忽视的点技能包也要写文档。至少有一个 README 说明每个技能的作用、触发条件、维护人。不然新人来了根本不知道这些文件是干嘛的。5.5 安全与合规注意事项最后强调一点技能文件里绝对不要放敏感信息。我见过有人在技能里写了内部 API 的密钥作为示例这是严重的安全隐患。技能文件应该只包含方法论所有具体配置通过环境变量注入。另外技能内容要符合团队的安全规范比如不能教 AI 生成绕过安全检查的代码。如果你的技能包要开源还要注意不要泄露公司内部的业务逻辑。6. 我个人的实操体会与后续扩展思路用了一段时间 superpowers 之后我最大的感受是它把 AI 编程从“碰运气”变成了“可管理”。以前我让 AI 写代码每次都要在提示词里重复一堆要求现在这些要求都固化在技能包里我只需要说“帮我写个函数”AI 就知道该用什么规范。这种体验上的提升是实实在在的。后续我打算从两个方向扩展一是增加技能之间的依赖关系比如“生成 React 组件”技能可以自动引用“生成 TypeScript 类型”技能避免重复定义二是引入技能评分机制每次 AI 使用技能后我可以给输出打分低分技能自动降权高分技能提升优先级。这样技能包就能自我进化越用越顺手。如果你也在用类似的技能框架欢迎交流你的配置方案。踩过的坑越多填坑的经验就越值钱。