1. 从“superpowers”这个标题说起它到底是什么能解决什么问题第一次看到“superpowers”这个标题很多人会下意识联想到超级英雄电影里的超能力但在技术圈子里这个词最近被反复提起指向的其实是一套围绕 AI 编程助手构建的技能扩展体系。简单来说它让原本只会“聊天写代码”的 AI 助手变成能按固定流程、固定规范、固定输出格式干活的“熟练工”。你可以把它理解成给 AI 装上了一套“操作手册加工具箱”让它不再每次从零开始猜你想要什么而是直接调用预先定义好的技能模块来完成任务。这套东西解决的核心痛点非常具体AI 编程助手在真实项目里“不稳定”。同一个需求今天问它写出来的代码风格和昨天不一样让它做代码审查它可能漏掉关键的安全检查项让它生成接口文档格式每次都要手动调整。这些问题的根源在于AI 每次对话都是“即兴发挥”没有一套固定的行为约束。superpowers 的思路就是把这些“即兴发挥”变成“按剧本演出”——把常见的开发任务拆解成一个个独立的技能包每个技能包定义了明确的触发条件、执行步骤和输出规范。适合谁来参考这套东西三类人最值得花时间研究。第一类是日常重度使用 AI 编程助手的开发者如果你每天都要和 AI 来回对话几十轮来写代码、改 bug、写测试superpowers 能帮你把重复性的对话模板固化下来省掉大量“调教”时间。第二类是技术团队的负责人或架构师你需要让团队里不同的人用 AI 助手时产出一致的结果superpowers 提供了一种把团队规范“编码”进 AI 工作流的可能。第三类是对 AI 工程化感兴趣的技术爱好者想了解怎么把大模型的通用能力约束到具体场景里这套体系是一个很好的观察样本。需要提前说明的是superpowers 本身不是一个独立的软件或服务它更像是一套约定和配置的集合依附于你正在使用的 AI 编程助手环境。所以它的安装和使用方式和你选择的底层工具强相关。下面我会从整体设计思路开始拆解然后逐步深入到具体的安装配置、技能编写、实操流程和踩坑经验尽量把每个环节都讲透。2. 整体设计思路拆解为什么是“技能包”而不是“万能提示词”2.1 核心思路把“提示词工程”升级为“技能工程”大多数人用 AI 编程助手的方式是遇到问题临时想一段提示词粘贴进去看结果不满意再改提示词。这种方式在简单任务上够用但一旦任务复杂起来比如“帮我审查这个模块的代码并生成报告”提示词就会变得又长又乱而且每次都要重新组织。superpowers 的设计者显然意识到了这个问题他们的解法是把提示词从“一次性消耗品”变成“可复用的技能资产”。具体做法是每个技能被定义为一个独立的文件或配置块里面包含几个关键部分技能的名称和描述告诉 AI 什么时候该用这个技能、执行步骤告诉 AI 按什么顺序做什么事、输出格式要求告诉 AI 最终结果长什么样、以及可能的参数占位符让技能可以接受外部输入。当你在对话中触发某个技能时AI 助手会读取这个技能的定义然后严格按照里面的步骤来执行而不是自由发挥。这个思路的巧妙之处在于它把“怎么写好提示词”这个难题从每次对话中剥离出来变成了一个可以提前设计、反复打磨、团队共享的工程问题。你不需要每次都想“怎么问才能让 AI 写出规范的代码”只需要在技能文件里把规范写死之后每次调用都自动生效。2.2 方案选型背后的考量为什么不做成插件或独立工具你可能会问为什么不直接做一个 IDE 插件或者独立的命令行工具来实现这些功能非要依附于 AI 助手的对话环境这背后有几个现实考量。第一降低使用门槛。如果做成独立工具用户需要额外安装、配置、学习一套新的界面和命令而依附于现有的 AI 助手环境用户只需要在熟悉的对话框里输入触发词就能用学习成本几乎为零。第二利用 AI 的理解能力。技能定义里不需要把每一步都写成死板的脚本可以用自然语言描述步骤AI 会根据上下文灵活执行这比写死脚本要健壮得多。第三避免重复造轮子。AI 助手本身已经具备了代码生成、文件读写、命令执行等基础能力superpowers 只需要在这些能力之上加一层“行为约束”不需要重新实现底层功能。当然这种方案也有代价。它高度依赖底层 AI 助手的能力和稳定性如果助手本身对技能定义的理解出现偏差执行结果就会打折扣。另外不同助手对技能格式的支持程度不一样迁移起来可能需要调整。但总体来看对于“让 AI 按规范干活”这个目标技能包方案是当前性价比最高的选择。2.3 优势与边界它能做什么不能做什么superpowers 最明显的优势是一致性和可积累性。一致性体现在同一个技能无论调用多少次输出格式和检查项都是固定的不会因为对话上下文的变化而漂移。可积累性体现在你可以不断往技能库里添加新的技能今天加一个“生成单元测试”的技能明天加一个“检查 SQL 注入风险”的技能技能库越丰富AI 助手能覆盖的场景就越多。但它也有明确的边界。首先它不能替代人的判断。技能定义得再详细AI 执行时仍然可能遇到边界情况需要人来决策比如代码审查时发现一个模棱两可的设计问题最终拍板还得靠人。其次它不适合高度创造性的任务。如果你让 AI 从零设计一个全新架构技能包反而会限制它的发挥空间这种场景下自由对话可能效果更好。最后它需要持续维护。项目在演进规范在变化技能定义也要跟着更新否则过时的技能反而会误导 AI。3. 核心细节解析一个技能包里到底装了什么3.1 技能定义的基本结构虽然不同 AI 助手对技能格式的支持细节有差异但一个典型的技能定义通常包含以下几个字段。我用一个“代码审查”技能作为例子来说明。name: code-review description: 对指定代码文件进行系统性审查检查安全、性能、可读性和规范符合度 trigger: 当用户要求审查代码、检查代码质量、或提到 review 时触发 steps: - 读取目标文件内容 - 检查是否存在硬编码密钥、SQL注入风险、XSS风险 - 检查循环和递归是否有性能隐患 - 检查变量命名和函数长度是否符合规范 - 按严重程度分级列出问题 output_format: | ## 审查结果 ### 严重问题 - [文件:行号] 问题描述 ### 一般问题 - [文件:行号] 问题描述 ### 建议改进 - [文件:行号] 建议内容这个结构里name是技能的唯一标识description帮助 AI 判断什么时候该用这个技能trigger是更明确的触发条件steps是执行步骤清单output_format规定了最终输出的格式。有些实现还会支持parameters字段让技能可以接受文件路径、检查级别等参数。3.2 触发机制的设计细节触发机制是技能包能否被正确调用的关键。如果触发条件写得太宽泛AI 可能会在不该用的时候乱用技能写得太窄又可能该用的时候不触发。我的经验是用“用户意图”而不是“关键词”来定义触发条件。比如上面例子里的“当用户要求审查代码、检查代码质量、或提到 review 时触发”覆盖了多种表达方式比单纯写“触发词review”要健壮得多。另外多个技能之间的触发条件要避免重叠。如果你同时定义了“代码审查”和“安全检查”两个技能而安全检查的触发条件里也包含了“检查代码”那 AI 就不知道该用哪个。解决办法是在描述里明确区分场景比如安全检查技能描述为“当用户明确要求检查安全漏洞、或代码涉及用户输入处理时触发”把边界划清楚。3.3 输出格式的约束技巧输出格式的约束直接决定了技能好不好用。如果格式定义得太死AI 可能会为了凑格式而忽略内容质量定义得太松输出又会变得随意。我试过几种方式最后觉得**“结构化模板加灵活填充”**最实用。具体来说就是给出明确的章节标题和列表格式但每个章节内部的内容让 AI 根据实际情况填充。还有一个技巧是在输出格式里加入严重程度分级或优先级标记。比如代码审查技能里用“严重问题/一般问题/建议改进”三级分类AI 在审查时就会主动判断每个问题的严重程度而不是把所有问题混在一起列出来。这个小小的格式约束对最终输出的可用性提升非常明显。注意输出格式里不要用太复杂的嵌套结构比如表格里套列表再套代码块AI 在生成时容易出错。保持两层以内的结构最稳定。3.4 参数化与动态内容处理有些技能需要接受外部输入才能工作比如“生成单元测试”技能需要知道目标文件路径和测试框架类型。这时候就需要用到参数化。参数的定义方式通常是在技能描述里用占位符标记比如{{file_path}}和{{framework}}然后在调用时由用户或 AI 自动填充。参数化带来的一个问题是如果参数没有正确传入技能执行就会失败或产生错误结果。我的做法是在技能定义里加入参数校验步骤比如第一步就是“检查 file_path 是否为空如果为空则提示用户提供”。这样即使参数缺失AI 也能给出明确的提示而不是默默生成一堆无意义的内容。4. 实操过程从零搭建一套可用的技能库4.1 环境准备与安装位置选择superpowers 的安装方式取决于你使用的 AI 编程助手环境。常见的几种情况如果助手支持自定义指令文件比如某些编辑器里的规则文件你可以把技能定义写进对应的配置目录如果助手支持插件或扩展机制可能需要按照插件规范来组织技能文件如果助手只支持对话那可能需要把技能定义作为对话的初始上下文传入。我实测下来把技能文件放在项目根目录下的一个专用文件夹里比如.ai-skills/或.assistant/skills/是最稳妥的做法。这样做的好处是技能定义和项目代码一起版本控制团队成员拉取代码后自动获得相同的技能库不同项目可以有不同技能库互不干扰迁移项目时技能库跟着走不需要额外配置。安装步骤大致如下在项目根目录创建技能文件夹比如mkdir .ai-skills在文件夹里创建技能定义文件每个技能一个文件文件名用技能名比如code-review.yaml按照你使用的 AI 助手的规范在助手的配置里指定技能文件夹的路径重启助手或重新加载配置让技能生效在对话中测试触发技能检查是否按预期执行提示第一次配置时建议先只放一个最简单的技能比如“生成提交信息”确认整个链路通了之后再批量添加其他技能。这样出问题时排查范围小。4.2 编写第一个技能从“生成提交信息”开始“生成提交信息”是一个很好的入门技能因为它逻辑简单、触发场景明确、输出格式容易定义。下面是我实际使用的一个版本。name: commit-message description: 根据代码变更内容生成符合约定式提交规范的提交信息 trigger: 当用户要求生成提交信息、写 commit message、或提到提交时触发 steps: - 读取暂存区的变更文件列表和差异内容 - 判断变更类型新增功能(feat)、修复缺陷(fix)、重构(refactor)、文档(docs)、测试(test)、杂项(chore) - 提取变更的核心内容用一句话概括 - 如果变更涉及多个类型按主要类型归类 output_format: | type(scope): subject body footer parameters: - name: scope description: 影响范围可选默认为空 required: false这个技能定义里steps描述了 AI 需要执行的判断逻辑output_format给出了约定式提交的标准格式。实际使用时你只需要说“帮我生成提交信息”AI 就会读取变更内容判断类型然后按格式输出。我踩过的一个坑是AI 有时会把变更类型判断错比如把重构当成新功能。后来我在步骤里加了一条“如果不确定类型优先选择 fix 或 refactor避免误标为 feat”准确率明显提升。这个经验说明技能定义里的步骤不仅要描述“做什么”还要在容易出错的环节给出“兜底规则”。4.3 技能库的组织与分类策略当技能数量超过十个之后就需要考虑分类组织了。我的做法是按开发阶段分类把技能分成几组编码阶段生成代码、补全函数、重构、审查阶段代码审查、安全检查、性能检查、测试阶段生成测试、检查覆盖率、文档阶段生成注释、生成接口文档、生成变更日志、协作阶段生成提交信息、生成合并请求描述。分类的好处是在配置触发条件时可以按组设置优先级。比如审查阶段的技能优先级高于编码阶段因为审查通常是在编码完成后进行的。另外分类也方便团队分工维护不同的人负责不同组的技能更新。在文件组织上可以用子文件夹来体现分类.ai-skills/ coding/ generate-function.yaml refactor-code.yaml review/ code-review.yaml security-check.yaml testing/ generate-test.yaml docs/ generate-comment.yaml4.4 技能之间的协作与串联单个技能的能力有限但多个技能串联起来就能完成复杂任务。比如“代码审查”技能发现了一个安全问题可以自动触发“生成修复建议”技能修复完成后再触发“生成测试”技能来验证修复效果。这种串联可以通过在技能定义里加入“后续技能”字段来实现。name: security-check description: 检查代码中的安全漏洞 trigger: 当用户要求安全检查、或代码涉及用户输入处理时触发 steps: - 检查硬编码密钥 - 检查 SQL 注入风险 - 检查 XSS 风险 - 检查权限校验缺失 next_skill: generate-fix-suggestionnext_skill字段告诉 AI这个技能执行完后如果发现了问题可以接着调用“生成修复建议”技能。这样就把两个独立的技能串成了一条工作流。不过要注意串联层数不要超过三层。我试过串四五个技能结果 AI 在执行过程中容易丢失上下文后面的技能拿不到前面技能的输出结果。三层以内比较稳定再复杂的话建议拆成多轮对话来完成。5. 常见问题与排查技巧实录5.1 技能不触发或触发错误这是最常见的问题表现是你说了一句话AI 没有调用你期望的技能或者调用了错误的技能。排查思路如下。先检查触发条件是否匹配。把你实际说的话和技能定义里的trigger字段对比看是否有语义上的偏差。比如你说了“帮我看看这段代码有没有问题”而技能触发条件写的是“当用户要求审查代码时触发”AI 可能认为“看看有没有问题”不等于“审查”就不触发。解决办法是把触发条件写得更口语化、更宽泛。再检查技能之间是否有冲突。如果两个技能的触发条件都匹配了你当前说的话AI 可能会随机选一个或者选优先级更高的那个。这时候需要调整触发条件的边界让每个技能有明确的适用场景。还有一个容易被忽略的原因是技能文件没有被正确加载。检查助手配置里的技能路径是否正确文件格式是否符合要求比如 YAML 缩进是否正确文件名是否和技能名一致。我遇到过因为 YAML 里多了一个空格导致整个技能文件解析失败的情况排查了半天才发现。5.2 输出格式不符合预期AI 没有按照output_format里的格式输出可能的原因有几个。一是格式定义太复杂AI 理解不了。解决办法是简化格式去掉嵌套层级用最直白的标题和列表。二是格式定义里有歧义比如用了“可选”这样的词AI 可能理解为“可以省略”结果把关键部分省掉了。解决办法是用明确的“必须包含”和“禁止包含”来约束。三是 AI 在生成过程中“忘记”了格式要求。这种情况在长对话中尤其常见因为对话历史太长格式要求被淹没在大量文本里。解决办法是在技能定义里加入“输出前检查格式”的步骤让 AI 在生成完内容后自己核对一遍格式。5.3 技能执行结果不稳定同一个技能有时候执行得好有时候执行得差这种不稳定性最让人头疼。根据我的经验原因通常不在技能定义本身而在输入内容的差异。比如代码审查技能审查一个简单的工具函数和审查一个复杂的业务模块AI 的表现肯定不一样。对于复杂输入AI 可能只检查了前几个步骤就“累了”后面的步骤草草了事。应对办法是在技能定义里加入强制检查点。比如在代码审查技能的步骤里每一步后面都加一句“完成后输出当前步骤的检查结果”这样 AI 必须逐步输出不能跳步。另外对于特别复杂的任务可以拆成多个技能分多次调用每次只处理一个方面而不是试图用一个技能搞定所有事。5.4 常见问题速查表问题现象可能原因排查方法解决措施技能完全不触发触发条件不匹配对比用户输入和 trigger 字段放宽触发条件增加同义表达触发了错误的技能技能间触发条件重叠检查所有技能的 trigger 字段明确各技能边界调整优先级输出格式混乱格式定义太复杂或有歧义简化格式定义去掉嵌套用明确的是非指令替代模糊描述执行结果时好时坏输入复杂度差异大用不同复杂度的输入测试加入强制检查点拆分复杂任务技能串联失败上下文丢失检查 next_skill 链路串联不超过三层中间结果显式传递技能文件不生效路径或格式错误检查配置路径和文件语法用最小技能测试链路5.5 几个我踩过的坑和对应的经验第一个坑是技能命名太随意。一开始我用“check1”“helper2”这样的名字结果时间一长自己都忘了每个技能是干什么的更别说让 AI 正确调用了。后来改成用“动词名词”的命名方式比如“review-code”“generate-test”“check-security”一目了然。第二个坑是在技能定义里写太多“不要做什么”。比如“不要生成太长的代码”“不要忽略边界情况”这些否定式指令 AI 理解起来反而容易出错。后来我改成正面描述“生成的代码控制在 50 行以内”“必须包含空值和边界值处理”效果好了很多。第三个坑是技能库更新后没有通知团队。有一次我修改了一个代码审查技能增加了新的检查项但团队其他人不知道还在用旧的对话方式结果审查结果不一致。后来我们约定技能库的修改要像代码修改一样走合并请求流程确保所有人都知道变更内容。6. 进阶玩法把技能库变成团队资产6.1 技能库的版本管理与协作技能库既然是团队共享的资产就应该像代码一样管理。我的做法是把.ai-skills/目录纳入版本控制每次修改技能都提交一个独立的变更写清楚修改原因和影响范围。在合并请求里可以附上修改前后的技能执行对比让审查者直观看到变化。对于大型团队还可以考虑把技能库拆分成“基础技能”和“项目技能”两层。基础技能是所有项目通用的比如代码审查、生成提交信息项目技能是特定项目专用的比如某个项目的接口规范检查。基础技能放在一个独立的仓库里通过子模块或包管理工具引入到各个项目中这样更新基础技能时所有项目都能受益。6.2 根据项目特点定制技能不同技术栈的项目需要不同的技能。比如 Java 项目可能需要“检查空指针异常”的技能前端项目可能需要“检查组件命名规范”的技能数据项目可能需要“检查 SQL 性能”的技能。定制技能的关键是把项目里反复出现的检查项固化下来。我参与过一个 Java 后端项目团队经常在代码审查时发现“日志打印没有脱敏”的问题。后来我们写了一个“检查日志脱敏”的技能触发条件是“当代码中包含日志打印语句时触发”步骤是“检查日志参数是否包含手机号、身份证号、邮箱等敏感字段如果有则标记为严重问题”。这个技能上线后同类问题再也没在审查中漏掉过。6.3 技能效果的度量与优化技能库建好之后怎么知道它有没有效果我通常看两个指标问题发现率和返工率。问题发现率是指技能执行后发现的真实问题数量返工率是指技能输出被人工修改的比例。如果问题发现率高且返工率低说明技能定义得比较准确如果返工率高说明技能输出不符合实际需求需要调整。度量的方式可以很简单就是在技能输出后面加一个“人工确认”环节让使用者标记哪些输出被采纳了、哪些被修改了。积累一段时间的数据后就能看出哪些技能需要优化。我自己的经验是一个技能通常需要经过三到五轮迭代才能达到比较稳定的状态第一版不用追求完美先跑起来再改。6.4 技能库的扩展方向技能库的扩展没有上限但要有优先级。我的建议是优先扩展高频、高价值、高重复性的场景。高频是指每天都会用到的比如生成提交信息高价值是指能避免严重问题的比如安全检查高重复性是指每次做法都一样的比如生成接口文档。这三个条件满足得越多越值得做成技能。另外技能库也可以和项目的持续集成流程结合。比如在提交代码时自动触发代码审查技能把审查结果作为合并请求的评论附上。这样技能库就不只是个人效率工具而是团队质量保障体系的一部分。不过这种集成需要对 AI 助手的接口有比较深入的了解适合有一定工程能力的团队尝试。注意技能库扩展时要注意维护成本。每增加一个技能就多了一份需要维护的定义文件。如果某个技能半年都没人用可以考虑归档或删除避免技能库变得臃肿难维护。7. 一些个人体会和后续可以尝试的方向我在多个项目里用过 superpowers 这套技能包机制最大的感受是它把 AI 助手从“聪明的实习生”变成了“靠谱的同事”。实习生需要你每次交代任务都说清楚要求而靠谱的同事知道你的规范你只需要说“帮我审查一下这个模块”他就能按你期望的方式完成。技能包做的就是这件事把“说清楚要求”这个步骤提前固化下来。踩过几次坑之后我总结出一条原则技能定义要像写单元测试一样写。单元测试的特点是输入明确、预期输出明确、边界情况覆盖到位。技能定义也应该这样触发条件明确、执行步骤明确、输出格式明确、异常情况有兜底。按照这个标准写出来的技能稳定性会高很多。后续可以尝试的方向一个是把技能库和项目的代码规范检查工具打通让 AI 技能和传统静态检查工具互补AI 负责语义层面的检查静态工具负责语法层面的检查。另一个是探索技能之间的自动编排比如根据当前对话上下文自动推荐应该使用哪个技能而不是完全依赖用户手动触发。这些方向都还在早期但值得关注。最后分享一个小技巧定期回顾技能库的使用情况。我每个月会花十分钟看一下哪些技能调用最多、哪些几乎没被用过、哪些经常被人工修改。调用多的技能可以考虑进一步优化没被用过的技能要么删掉要么重新设计触发条件经常被修改的技能说明定义和实际需求有偏差需要调整。这个习惯让我的技能库始终保持精简和实用不会变成一堆没人维护的“僵尸技能”。