1. 从“超能力”到可复用技能superpowers 到底在解决什么问题第一次听到 “superpowers” 这个词很多人会以为是某个游戏里的技能系统或者某个超级英雄题材的项目。但如果你最近在开发者社区、效率工具圈或者 AI 编程助手的讨论里频繁看到它那它指的其实是另一件事一套把“能力”拆成可插拔技能模块的思路和工具集合。核心关键词 superpowers、superpowers 具体使用、有哪些 skills、怎么引入这些技能、想要安装 superpowers这几个搜索词基本勾勒出了大家最关心的问题——它是什么、里面有什么、怎么装、怎么用。我最早接触这个概念是在折腾 AI 编程助手的时候。当时遇到一个很典型的痛点每次让助手帮我做代码审查、写测试、生成文档都要重新描述一遍规则和流程换个会话就全忘了。后来发现 superpowers 这类方案的核心价值就是把“你希望助手具备的能力”从一次性对话里抽出来变成一个个独立、可命名、可复用的 skill技能。你可以把它理解成给助手装了一套“技能包”需要代码审查时调用审查技能需要写单元测试时调用测试技能需要整理提交信息时调用提交技能。每个技能内部封装了提示词、操作步骤、约束条件和输出格式调用一次就按既定流程走不用每次从零交代。这套东西适合谁我觉得有三类人特别值得关注。第一类是重度使用 AI 编程助手的开发者尤其是同时维护多个项目、需要频繁切换任务上下文的人第二类是团队里的技术负责人想把团队的编码规范、审查标准固化成可共享的技能让每个人调用的助手行为一致第三类是对效率工具感兴趣、喜欢自己折腾工作流的爱好者。哪怕你只是想让助手帮你把一段混乱的笔记整理成结构化文档一个写好的 skill 也能省下大量重复描述的时间。需要先说明一点superpowers 本身不是一个单一软件更像是一种组织能力的范式不同平台、不同工具链下都有对应的实现方式。所以下面讲的内容既有通用的设计思路也有基于常见实践的落地方法。你不需要把它当成必须严格照搬的标准而是当成一套可以按自己需求裁剪的框架来理解。接下来我会从整体设计、核心技能拆解、安装引入、实操流程到问题排查一层层把它讲透。2. 整体设计思路为什么要把能力拆成 skill2.1 从“一次性提示”到“可复用技能”的转变传统用 AI 助手的方式是“对话式”的你提一个需求助手回一段内容任务结束上下文清空。这种方式在单次、简单的任务上没问题但一旦任务变复杂、需要重复执行问题就暴露了。比如你要求助手“审查这段代码检查命名规范、边界条件、异常处理并按严重程度分级输出”第一次你可能写了一大段提示词效果不错。第二次换个文件你又得把那段提示词复制一遍。第三次、第四次……很快你就会发现真正有价值的不是某一次的输出而是那段被你反复使用的“指令模板”。superpowers 的设计思路正是从这里切入的把那段反复使用的指令模板连同它的执行步骤、检查清单、输出格式一起封装成一个有名字的 skill。这样你下次只需要说“用代码审查技能处理这个文件”助手就知道该做什么、按什么标准做、输出成什么样。这个转变看起来简单但它带来的连锁反应很大——能力变得可命名、可组合、可分享、可版本管理。我打个生活化的比方。一次性提示就像你每次做饭都临时想菜谱今天放多少盐、火候多大全靠临场发挥而 skill 就像把菜谱写下来贴在冰箱上下次照着做就行味道稳定还能传给家人。superpowers 做的就是帮你建这个“菜谱库”。2.2 技能模块化的三个核心收益把能力拆成 skill最直接的收益是一致性。同一个 skill 每次执行都遵循同样的步骤和标准不会因为今天心情好就多检查两项、明天赶时间就漏掉关键环节。对于团队协作来说这意味着不同人调用助手得到的结果是可预期的审查标准不会因人而异。第二个收益是可组合性。单个 skill 解决一个具体问题多个 skill 可以串起来形成工作流。比如“读取需求文档 → 生成任务拆解 → 编写代码 → 运行测试 → 生成提交信息”每一步都可以是一个独立 skill按顺序调用就完成了一条完整流水线。这种组合方式比写一个巨大的、什么都管的提示词要灵活得多因为你可以随时替换其中某个环节而不影响其他部分。第三个收益是可维护性。当规范变化时你只需要修改对应的 skill 文件所有调用它的地方自动生效。这比在几十个地方散落着复制粘贴的提示词要好维护太多。我在实际项目里就吃过这个亏早期把审查规则直接写在对话里后来团队规范调整了我得挨个翻历史记录去改效率极低。改成 skill 之后改一处就够了。2.3 方案选型自建还是用现成的围绕 superpowers 的落地通常有两条路。一条是使用社区或平台已经提供的技能集合直接安装引入另一条是根据自己的需求从零编写 skill。两条路并不互斥实际中更常见的是“先用现成的再按需改造”。如果你刚开始接触我建议先走第一条路把现成的技能装起来跑通感受一下调用流程和输出效果。等你对 skill 的结构、触发方式、参数传递有了直观认识再动手写自己的。直接上来就自建很容易因为不熟悉约定而卡在细节上挫败感比较强。选型时还要考虑你的使用场景。如果你主要在某个特定的 AI 编程环境里工作优先看这个环境官方或社区推荐的技能组织方式兼容性最好。如果你跨多个工具使用那就要关注 skill 的格式是否通用、能否方便地迁移。这一点我在后面讲安装引入时会具体展开。3. 核心技能拆解superpowers 里到底有哪些 skills3.1 常见技能分类与典型代表虽然不同实现下的技能清单不完全一样但从社区讨论和常见实践来看superpowers 类的技能大致可以分成几个大类。我把它们整理成一张表方便你对照理解。技能类别典型技能解决的问题适用场景代码质量类代码审查、重构建议、命名规范检查保证代码符合团队标准提交前自查、PR 审查测试类单元测试生成、边界用例设计、测试覆盖率分析提升测试覆盖与质量新功能开发、遗留代码补测文档类注释生成、README 编写、API 文档整理降低文档维护成本项目初始化、接口变更工作流类提交信息生成、任务拆解、变更日志整理规范协作流程日常提交、版本发布分析类依赖分析、性能瓶颈定位、日志解读快速定位问题排障、优化这张表不是固定不变的你可以把它当成一个起点。实际使用中很多人会根据自己的技术栈补充专属技能比如针对某个框架的最佳实践检查、针对某种数据格式的校验规则等。3.2 一个 skill 的内部结构长什么样要理解怎么引入和使用技能得先知道一个 skill 内部由哪些部分组成。虽然具体格式因平台而异但核心要素是相通的。一个完整的 skill 通常包含以下几个部分。名称与描述这是技能的标识也是触发它的关键。名称要简短好记描述要说清楚“这个技能做什么、什么时候用”。描述写得好不好直接影响助手能不能在合适的时机自动识别并调用它。触发条件定义什么情况下应该启用这个技能。有的技能是手动调用的你说“用 XX 技能”才触发有的支持自动触发助手根据当前任务判断是否匹配。自动触发对描述的准确性要求更高。执行步骤这是技能的核心把完成任务的过程拆成有序的步骤。步骤要具体到可执行避免“检查代码质量”这种模糊表述而要写成“检查变量命名是否符合驼峰规范、检查函数是否超过 50 行、检查是否有未处理的异常分支”这样可操作的条目。约束与禁忌明确哪些事不能做。比如“不要修改业务逻辑只提建议”“不要引入新的第三方依赖”。这些约束能防止助手在执行过程中越界减少返工。输出格式规定结果以什么形式呈现。是表格、列表还是分级报告是否要包含严重程度、修复建议、示例代码格式统一了后续处理起来才方便。我刚开始写 skill 的时候最容易忽略的是“约束与禁忌”这一块。结果助手在执行审查时顺手把代码改了虽然改得没错但超出了我的预期反而增加了核对成本。后来我把“只读不改”写进约束里就再没出现过这个问题。3.3 技能粒度怎么把握这是很多人纠结的问题一个 skill 应该做多少事做太少技能数量爆炸调用起来繁琐做太多又变成一个什么都管的巨型提示词失去了模块化的意义。我的经验是一个 skill 对应一个明确的、可独立验收的产出。比如“生成单元测试”是一个合适的粒度它的产出是一组测试文件可以独立判断好坏。而“提升代码质量”就太宽泛了它可能涉及重构、补测试、改命名、加注释产出不明确验收也困难。另一个判断标准是复用频率。如果某个能力你每周都要用好几次那它值得单独成为一个 skill。如果只是偶尔用一次直接写在对话里可能更省事。不要为了模块化而模块化工具是为人服务的。还有一个实用技巧先写粗粒度的 skill用一段时间后如果发现某个步骤总是被单独调用再把它拆出来。这种“先合后分”的方式比一开始就追求完美拆分要务实得多因为你对流程的真实使用模式往往要跑起来才看得清楚。4. 安装与引入想要安装 superpowers 该怎么操作4.1 安装前的环境确认在动手安装之前有几项环境信息需要先确认清楚否则很容易装到一半发现不兼容。首先要明确你使用的 AI 助手或开发环境是哪一个因为 superpowers 的引入方式高度依赖宿主环境。不同环境对技能文件的存放位置、格式要求、加载机制都不一样。其次要确认版本。技能系统本身可能随着宿主环境更新而变化旧版本的技能文件在新版本里未必能直接用。我建议在安装前先查一下当前环境的版本号并对照技能集合的说明文档确认兼容范围。这一步花不了几分钟但能避免很多后续麻烦。第三是确认权限。有些环境需要你在配置里显式开启技能加载功能或者把技能目录加入白名单。如果装完发现技能不生效先回头检查这一项十有八九是权限或开关没打开。提示安装前把当前配置备份一份。技能加载涉及配置文件修改万一改出问题有备份能快速回滚不至于影响正常使用。4.2 获取技能包的常见途径技能包的来源主要有几种。一种是官方或平台内置的技能市场直接在界面里搜索、点击安装最省事兼容性也最有保障。另一种是社区维护的技能仓库通常以文件目录的形式提供需要你手动下载并放到指定位置。还有一种是团队内部共享由技术负责人统一维护一套技能分发给成员使用。对于社区来源的技能包我建议先看它的更新时间和 issue 活跃度。一个长期不更新、问题没人回的技能包用起来风险比较高可能和新版本环境不兼容。另外要留意技能包里是否包含执行外部命令或访问网络的步骤涉及这类操作的技能要格外谨慎确认来源可靠再引入。4.3 引入技能的实操步骤下面以常见的“文件目录式”技能引入为例走一遍完整流程。不同环境细节会有差异但整体思路是通用的。第一步找到技能目录。大多数环境会有一个约定的技能存放路径通常在用户配置目录下。你可以在环境的设置里搜索“skills”或“技能”相关选项找到当前生效的路径。如果找不到查阅该环境的文档一般都会有说明。第二步把技能包放入目录。每个技能通常是独立的一个子目录或一个文件保持原有的目录结构放进去即可。注意不要随意改动技能内部的相对路径引用否则可能导致加载失败。第三步检查配置文件。有些环境需要在配置里注册技能目录或者声明启用哪些技能。打开配置文件按文档说明添加相应条目。这一步最容易出错建议对照示例配置逐项核对。第四步重启或重新加载。技能通常在环境启动时加载改完配置后需要重启环境或执行重新加载命令才能生效。别改完就急着测试先确认加载日志里没有报错。第五步验证技能是否可用。调用一个简单的技能看是否能正常触发并返回预期结果。如果没反应回到上一步看日志根据报错信息定位问题。# 以常见的目录结构为例查看技能目录内容 ls -la ~/.config/your-assistant/skills/ # 确认技能文件已就位 # 输出应包含你放入的技能目录或文件4.4 引入后的验证与调试技能装好只是第一步能不能稳定用起来还得验证。我一般会做三件事。第一件是逐个调用每个技能确认都能正常触发没有加载错误。第二件是检查自动触发是否准确也就是在不显式点名的情况下助手能否在合适的任务里自动选用正确的技能。第三件是观察输出格式是否符合预期有没有缺项或格式错乱。如果发现某个技能不触发先检查它的描述是否足够清晰。自动触发依赖描述和当前任务的匹配度描述写得太模糊助手就判断不出来。可以把描述改得更具体加上典型使用场景的关键词再测试一次。如果技能触发了但输出不对多半是执行步骤或输出格式的定义有问题。这时候把技能文件打开对照实际输出逐条检查看是哪一步的指令没被正确执行。必要时把步骤拆得更细减少歧义。5. 实操过程superpowers 具体使用流程拆解5.1 从零跑通一个代码审查技能光讲概念不够直观我拿一个最常用的场景——代码审查——把完整流程走一遍。假设你已经装好了一个代码审查技能现在要审查一段刚写完的函数。首先把待审查的代码提供给助手并明确调用审查技能。你可以直接说“用代码审查技能看一下这段代码”也可以让助手自动识别。如果技能描述写得清楚助手通常能判断出这是审查任务。接下来助手会按技能定义的步骤逐项检查。一个设计良好的审查技能检查项通常包括命名规范、函数长度、参数数量、异常处理、边界条件、注释完整性、潜在性能问题等。每一项都会给出具体的判断而不是笼统地说“代码质量不错”。然后输出会按约定的格式呈现。我比较推荐的格式是分级列表严重问题、建议改进、可选优化三档每条包含问题描述、所在位置、修改建议。这样你一眼就能看出哪些必须改、哪些可以缓一缓。最后根据审查结果决定后续动作。严重问题当场修建议改进排进待办可选优化看时间。整个流程走下来比你自己逐行读代码要快而且不容易漏项。5.2 技能组合形成工作流单个技能好用但真正的效率提升来自组合。我举一个我日常在用的工作流需求整理 → 任务拆解 → 编码 → 测试生成 → 提交信息生成。需求整理技能负责把零散的需求描述整理成结构化的条目明确输入、输出、边界。任务拆解技能把整理后的需求拆成可执行的小任务每个任务有明确的完成标准。编码阶段我一般自己写核心逻辑助手辅助补全样板代码。测试生成技能针对新写的函数生成单元测试覆盖正常路径和边界情况。提交信息生成技能根据本次改动的内容按约定格式生成提交说明。这条流水线跑顺之后我从接到需求到提交代码的时间明显缩短而且因为每一步都有技能兜底遗漏关键环节的概率大大降低。当然这套流程不是一开始就设计好的是我在实际使用中逐步摸索出来的。你也可以从两三个技能的组合开始用顺了再往上加。5.3 参数传递与上下文管理技能调用时经常需要传入参数比如文件路径、代码片段、规范名称等。参数传递的方式因环境而异有的通过对话自然语言传递有的支持结构化参数。不管哪种方式关键是把必要信息给全避免助手靠猜。上下文管理是另一个容易踩坑的地方。技能执行过程中会消耗上下文窗口如果一次调用涉及大量文件或很长的代码可能超出限制导致中途截断。我的做法是分批处理一次审查一个文件或一个模块而不是把整个项目一次性丢进去。这样既保证质量也避免上下文溢出。另外技能之间的上下文传递也要注意。前一个技能的输出作为后一个技能的输入时要确保格式兼容。比如任务拆解技能输出的是列表编码技能期望的是逐条任务描述中间可能需要一个格式转换的步骤。这个转换可以手动做也可以再写一个小技能专门处理。5.4 自定义技能的编写要点用了一段时间现成技能后你大概率会想写自己的。我把编写要点总结成几条。描述要具体不要写“帮助处理代码”而要写“审查 Python 函数的命名规范、异常处理和边界条件输出分级问题列表”。描述越具体触发越准确。步骤要可执行每一步都应该是能直接做的动作避免“评估代码质量”这种需要主观判断的表述。拆到“检查函数是否超过 50 行”这种程度执行起来才稳定。约束要明确把“不要做什么”写清楚比如“只提建议不修改代码”“不引入新依赖”。约束能显著减少意外行为。格式要固定输出格式定死用表格或固定字段的列表。格式统一了后续处理才方便自动化。先小后大从解决一个具体小问题的技能开始写跑通了再扩展。一上来就写复杂技能调试成本很高。6. 常见问题与排查技巧实录6.1 技能不触发怎么办这是最高频的问题。技能装好了调用时却没反应助手像没看见一样继续按普通对话处理。排查思路按顺序来先确认技能是否真的加载成功看启动日志有没有相关记录再检查技能描述是否足够清晰模糊的描述会导致匹配失败然后确认调用方式是否正确手动调用和自动触发的写法不一样最后看是否有多个技能描述重叠导致助手无法判断该用哪个。我遇到过一次两个技能描述都包含“代码”这个词结果助手在两个之间反复横跳最后哪个都没用。把描述改得更精确、区分开适用场景后就好了。所以技能之间描述要有区分度别让它们打架。6.2 输出格式不符合预期技能触发了但输出乱七八糟该用表格的地方用了大段文字该分级的没分级。这通常是输出格式定义不够严格导致的。解决办法是在技能里把格式模板写死给出一个具体的示例输出让助手照着填。示例比抽象描述有效得多。还有一种情况是输出被截断只给了一半就停了。这多半是上下文或输出长度限制导致的。把任务拆小或者让技能分批次输出能缓解这个问题。6.3 技能之间互相干扰当你装了很多技能后可能出现技能之间互相干扰的情况。比如审查技能执行到一半突然切换到文档技能的格式。这通常是触发条件定义得太宽泛导致助手在执行过程中误判。解决办法是收紧每个技能的触发条件明确边界必要时在技能里加上“执行本技能期间不要切换到其他技能”的约束。6.4 常见问题速查表问题现象可能原因排查方向解决建议技能完全不触发未加载/描述模糊/调用方式错查日志、看描述、确认写法重新加载、改描述、按文档调用触发但输出错乱格式定义不严检查输出格式部分加示例输出、固定模板输出被截断上下文或长度超限看任务规模拆小任务、分批处理技能互相干扰触发条件重叠对比各技能描述收紧条件、加互斥约束参数丢失传递方式不对检查调用时的参数补全信息、用结构化参数6.5 几个我踩过的坑第一个坑是技能装太多。刚开始觉得每个技能都有用一口气装了二十多个结果触发混乱反而降低了效率。后来精简到常用的七八个体验立刻好转。技能不在多在于精和准。第二个坑是忽略版本更新。宿主环境升级后旧技能文件格式变了加载报错。后来我养成了升级前先看变更说明、升级后先跑一遍技能验证的习惯。第三个坑是把技能当成万能药。有些任务其实直接对话更高效硬套技能反而绕远路。技能适合重复性高、标准明确的任务一次性的、探索性的任务直接聊更合适。判断标准很简单这个任务你做过三次以上吗是的话值得做成技能。7. 技能体系的长期维护与扩展思路7.1 版本管理与团队共享当技能从个人使用扩展到团队共享管理方式就要升级了。最基础的做法是把技能目录纳入版本控制每次修改都有记录出问题能追溯。再进一步可以给技能加版本号在描述里标注适用环境和依赖方便成员判断兼容性。团队共享时我建议指定一个人负责技能库的维护统一审核新增和修改。否则每个人都往里加很快就乱了。审核的重点是描述是否清晰、步骤是否可执行、约束是否合理、有没有安全风险。7.2 根据使用反馈迭代技能技能不是写完就完事了要根据实际使用反馈持续迭代。我一般会记录每次技能执行中出现的偏差攒到一定数量就集中改一次。常见的迭代方向包括补充遗漏的检查项、细化模糊的步骤、调整输出格式、收紧触发条件。迭代时注意保留旧版本万一新版本效果变差可以回退。技能文件本身是文本用版本控制管理起来很方便每次改动都有 diff 可查。7.3 技能体系的扩展方向跑通基础技能后可以向几个方向扩展。一个是垂直深化针对你的技术栈写更专业的技能比如特定框架的最佳实践检查、特定数据库的查询优化建议。另一个是横向连接把技能和外部工具打通比如审查结果自动生成任务、测试结果自动汇总报告。还有一个是智能化让技能根据历史执行记录自动调整参数不过这需要一定的数据积累。我个人在实际操作中的体会是技能体系的价值不在于数量而在于它是否真正嵌入了你的日常工作流。一个每天都会用到的审查技能比十个装了却想不起来用的技能有价值得多。所以扩展之前先问自己这个技能我会经常用吗如果答案不确定先别急着写。最后再分享一个小技巧给每个技能写一句“一句话说明”放在描述最前面。这句话要能让未来的你或者你的同事在三秒内判断出这个技能是干什么的、要不要用。很多技能用不起来不是因为不好用而是因为没人记得它存在。一句清晰的一句话说明就是最好的入口。