1. 从“超能力”到可落地技能superpowers 到底在解决什么问题第一次听到 “superpowers” 这个词很多人会以为是某个新出的游戏或者影视 IP。但在开发者圈子里它指的是一套围绕 AI 编程助手构建的技能增强体系——你可以把它理解成给 AI 助手装上一套“外挂工具箱”让它在写代码、调试、重构、写文档这些具体任务上表现得像一个有多年经验的工程师而不是一个只会背 API 的实习生。我自己是从去年开始接触这套东西的。当时最大的痛点很直接AI 助手写出来的代码单看每一行都没问题但拼在一起就是跑不通。要么是变量名对不上要么是漏了边界条件要么是引用的库版本根本不存在。你反复纠正它它反复道歉然后继续犯同样的错。这种“看起来很努力但就是不出活”的状态消耗了大量时间。superpowers 的核心思路就是把模糊的“帮我写个功能”拆解成结构化的技能调用。它不是一个具体的软件而是一套组织方式定义技能skills、引入技能、在合适的场景触发合适的技能。热搜里反复出现的“有哪些 skills”“怎么引入这些技能”“想要安装 superpowers”本质上都是在问同一件事——这套东西怎么用起来。适合读这篇内容的人我大致分三类。第一类是已经在用 AI 助手写代码但效率卡在“反复返工”阶段的开发者第二类是想把 AI 助手接入自己工作流但不知道从哪下手的技术负责人第三类是对“技能编排”这个概念感兴趣想看看别人怎么把提示词工程做成可复用模块的爱好者。不管你是哪一类接下来的内容都会从底层逻辑讲到具体操作尽量让你看完就能动手试。需要先说明一点superpowers 本身不是一个可以“一键安装”的独立软件包。网上很多“安装教程”把它描述得像装个 App 一样这是误导。它更像一套约定和文件结构你需要把它放到 AI 助手能读取的位置然后通过配置让它生效。理解了这一点后面的操作就不会走偏。2. 核心设计思路拆解为什么是“技能”而不是“提示词”2.1 从“一次性对话”到“可复用技能”的转变大多数人用 AI 助手的方式是“一次性对话”打开对话框输入需求拿到结果关掉。下次遇到类似问题重新描述一遍。这种方式的问题在于每次都要重新建立上下文而且你上一次踩过的坑下一次还会再踩。superpowers 的做法是把常见的任务模式固化成“技能”。一个技能本质上是一个结构化的指令集合包含这个技能解决什么问题、在什么条件下触发、执行步骤是什么、输出格式是什么、有哪些注意事项。你可以把它想象成给 AI 助手准备的一份“标准作业程序”SOP。举个例子。没有技能的时候你可能会说“帮我写一个读取 CSV 文件并计算每列平均值的 Python 函数。”AI 会给你一段代码但可能没有处理空值可能没有考虑大文件的内存问题可能没有加类型注解。有了技能之后你调用的是“数据处理”技能这个技能内部已经定义好了必须检查空值、必须考虑分块读取、必须加类型注解、必须给出使用示例。AI 助手按照这个框架来执行输出质量就稳定得多。这个转变的关键在于把“你脑子里的隐性要求”变成“技能文件里的显性规则”。你不需要每次都在对话里重复“记得处理空值”因为技能已经帮你记住了。2.2 技能分层基础技能、组合技能与场景技能在实际使用中技能不是平铺的一堆文件而是有层次的。我自己的习惯是分成三层基础技能是最小粒度的操作比如“读取文件”“执行命令”“搜索代码库”“格式化输出”。这些技能不解决具体业务问题但它们是其他技能的基础。就像乐高积木里的基础砖块单独看没什么用但组合起来能搭出任何东西。组合技能是把多个基础技能串起来解决一类问题。比如“调试技能”可能包含读取报错信息、定位相关代码、分析可能原因、提出修复方案、验证修复结果。这一整套流程被封装成一个技能你调用一次就能走完整个调试链路。场景技能是针对特定项目或特定技术栈定制的。比如你正在做一个 React 项目可以有一个“React 组件开发”技能里面规定了组件命名规范、状态管理方式、样式方案、测试要求。这个技能只在你这个项目里生效换一个项目就不适用了。这种分层的好处是复用性和灵活性的平衡。基础技能到处都能用组合技能跨项目通用场景技能针对性强。你不需要为每个项目重写所有东西只需要在基础层和组合层之上叠加项目特有的场景层。2.3 为什么这种设计能提升输出稳定性AI 助手输出不稳定的根本原因是每次对话的上下文都是新的。它不知道你上次是怎么做的不知道你的项目规范不知道你踩过哪些坑。你给它的信息越少它自由发挥的空间就越大输出就越不可控。技能机制本质上是在压缩不确定性。当你调用一个技能时你实际上是在告诉 AI 助手“按照这个框架来不要自由发挥。”技能文件里定义的步骤、约束、输出格式都是在缩小它的决策空间。决策空间越小输出越稳定。这就像你让一个新来的实习生做事。如果你只说“帮我整理一下数据”他可能给你十种不同的结果。但如果你给他一份详细的 SOP告诉他第一步做什么、第二步做什么、每步的输出格式是什么他交上来的东西就靠谱得多。技能就是给 AI 助手的 SOP。还有一个容易被忽略的好处技能是可以迭代的。你第一次写一个技能可能不够完善。用了几次之后发现某个步骤总是出问题你就可以去修改技能文件加上一条约束。下次再调用这个问题就不会再出现。这种“越用越好用”的特性是一次性对话模式不具备的。3. 技能体系里到底有哪些 skills一份可参考的分类清单3.1 开发流程类技能这类技能覆盖从需求到上线的完整链路是我用得最多的一类。具体包括需求拆解技能把一句模糊的需求描述拆成可执行的任务列表。比如“做一个用户登录功能”拆成“设计数据表结构”“实现注册接口”“实现登录接口”“实现密码加密”“实现会话管理”“编写测试用例”。这个技能的价值在于它强迫 AI 助手先想清楚再动手而不是上来就写代码。代码生成技能按照项目规范生成代码。这个技能里会定义命名规范、目录结构、注释要求、错误处理方式。我自己的配置里还加了一条生成的每个函数必须附带一个使用示例。代码审查技能对已有代码进行检查找出潜在问题。这个技能会从几个维度审查逻辑正确性、边界条件、性能隐患、安全漏洞、可读性。输出格式是问题列表加修复建议。重构技能在不改变外部行为的前提下改进代码结构。这个技能会先要求 AI 助手理解现有代码的意图然后提出重构方案最后执行重构并验证结果。文档生成技能根据代码自动生成 API 文档、README、变更日志。这个技能会规定文档的格式和必须包含的章节。这些技能不是孤立的它们可以串联使用。比如你先用需求拆解技能把任务拆开然后用代码生成技能逐个实现再用代码审查技能检查最后用文档生成技能输出文档。整条链路走下来效率比手动操作高很多。3.2 调试与排查类技能调试是 AI 助手最能发挥价值、也最容易翻车的场景。发挥价值是因为它能快速扫描大量代码翻车是因为它容易“猜”错误原因而不是“找”错误原因。调试类技能的设计重点就是强制它先找证据再下结论。我常用的调试技能包含这几个报错分析技能输入一段报错信息输出可能的原因列表按可能性排序并给出验证方法。关键是它必须给出“如何验证”这一步而不是直接说“应该是某某问题”。日志排查技能根据日志文件定位异常发生的时间点和相关代码路径。这个技能会要求 AI 助手先提取关键时间线再关联代码变更记录。性能分析技能识别代码中的性能瓶颈比如循环嵌套、重复计算、不必要的内存分配。输出是瓶颈列表加优化建议。回归排查技能当新代码导致旧功能失效时定位是哪次变更引入的问题。这个技能会对比变更前后的代码差异找出可疑改动。注意调试类技能最容易出现的问题是“过度自信”。AI 助手可能会给出一个看起来很合理的解释但实际上完全不对。所以我在技能文件里加了一条硬性要求任何结论必须附带“验证步骤”没有验证步骤的结论视为无效。3.3 项目协作类技能这类技能解决的是“多人协作”场景下的问题虽然 AI 助手本身不参与协作但它可以帮助你处理协作相关的任务。提交信息生成技能根据代码变更自动生成规范的提交信息。格式遵循约定式提交Conventional Commits包含变更类型、影响范围、简短描述。变更日志技能把一段时间内的提交记录整理成人类可读的变更日志按功能、修复、优化分类。代码冲突解决技能当合并冲突发生时分析冲突原因提出解决方案。这个技能会先理解两边的修改意图再给出合并建议。任务拆分技能把一个大的功能需求拆成多个可并行开发的小任务并标注依赖关系。这些技能的价值在于减少沟通成本。团队里每个人写提交信息的风格不一样有了这个技能输出格式就统一了。变更日志也不用手动整理调用一次技能就出来了。3.4 技能清单的维护策略技能不是越多越好。我一开始兴致勃勃地写了三十多个技能结果发现根本记不住哪个是哪个调用的时候还要翻文件。后来我做了减法把技能数量控制在十五个以内每个技能都经过实际使用验证。维护策略上我遵循几个原则一个技能只解决一类问题。如果一个技能里塞了太多不相关的内容调用的时候就会引入不必要的约束。技能文件保持短小。每个技能文件控制在两百行以内太长了 AI 助手读取和处理都会变慢。定期清理。三个月没用过的技能要么删掉要么合并到其他技能里。版本管理。技能文件也要纳入版本控制每次修改都记录变更原因。这样出问题的时候可以回滚。4. 怎么引入这些技能从零开始的配置流程4.1 理解技能的存放位置与加载机制引入技能的第一步是搞清楚 AI 助手从哪里读取技能文件。不同的助手实现方式不一样但大体上分两种模式文件系统模式技能以文件形式存放在某个目录下AI 助手在启动时扫描这个目录把技能加载到上下文里。这种模式的好处是直观你可以直接用编辑器修改技能文件。坏处是需要手动管理文件结构。配置注入模式技能内容写在配置文件里AI 助手读取配置后生效。这种模式的好处是集中管理坏处是修改起来不如文件方便。我自己的做法是混合使用基础技能和组合技能用文件系统模式方便迭代场景技能用配置注入模式因为场景技能通常比较稳定不需要频繁修改。具体到操作上你需要先确认你的 AI 助手支持哪种模式。大多数支持技能机制的助手都会在文档里说明技能目录的位置。如果找不到可以尝试在项目根目录下创建一个skills文件夹然后在助手的配置文件里指向这个路径。4.2 编写第一个技能文件的完整示例假设我们要写一个“生成 Python 函数”的技能。文件内容大致如下# 技能名称生成 Python 函数 ## 触发条件 当用户要求生成一个 Python 函数时触发。 ## 执行步骤 1. 确认函数的输入参数和返回值类型。 2. 检查是否需要处理边界条件空值、类型错误、越界。 3. 编写函数主体遵循 PEP 8 规范。 4. 添加类型注解。 5. 添加文档字符串说明参数和返回值。 6. 提供一个使用示例。 ## 输出格式 - 函数代码块 - 使用示例代码块 - 注意事项列表如果有 ## 约束 - 不允许使用未导入的库。 - 不允许忽略异常处理。 - 如果函数超过 50 行必须拆分成多个小函数。这个文件写好后放到技能目录下。下次你让 AI 助手生成 Python 函数时它就会按照这个框架来执行。你会发现输出质量明显提升因为那些你平时要反复提醒的点已经写进技能里了。4.3 技能引入后的验证方法技能引入后不能假设它一定生效了。我通常会做三个验证验证一触发测试。故意提出一个符合触发条件的需求看 AI 助手的输出是否符合技能定义的格式。比如上面那个技能如果输出里没有使用示例说明技能没生效或者没被正确读取。验证二约束测试。故意提出一个违反约束的需求看 AI 助手是否会拒绝或者提醒。比如要求生成一个不处理异常的函数如果技能生效了助手应该会指出这违反了约束。验证三边界测试。提出一个边界情况的需求看 AI 助手是否按照技能里的步骤处理。比如要求生成一个处理空列表的函数看它是否检查了空值。如果三个验证都通过说明技能引入成功。如果有任何一个失败就需要检查技能文件路径是否正确、格式是否符合要求、助手是否支持这种加载方式。4.4 多技能协同的配置要点当你引入多个技能后会遇到一个新问题技能之间可能冲突。比如“代码生成技能”要求函数不超过 50 行“性能优化技能”要求把循环展开展开后可能超过 50 行。这时候 AI 助手该听谁的我的处理方式是定义优先级。在配置文件里给每个技能标注优先级数字越小优先级越高。当冲突发生时高优先级技能覆盖低优先级技能。一般来说我会把“正确性”相关的技能设为最高优先级“性能”相关的设为中等“风格”相关的设为最低。另一个要点是技能组合。有些任务需要多个技能协同完成比如“重构一个函数”可能需要“代码审查技能”加“重构技能”加“测试生成技能”。我通常会在场景技能里定义这种组合关系调用场景技能时自动触发相关的基础技能。5. 实操过程与核心环节实现一次完整的技能调用记录5.1 场景设定与任务拆解为了让你更直观地理解整个流程我记录了一次真实的操作过程。任务背景是我负责的一个数据处理脚本需要增加一个功能读取多个 CSV 文件合并后计算每列的平均值并输出一份报告。按照传统方式我会直接跟 AI 助手说“帮我写个脚本”。但这次我走技能流程。第一步调用“需求拆解技能”。输入是“读取多个 CSV 文件合并后计算每列平均值输出报告。”技能输出如下任务列表确定 CSV 文件的目录结构和命名规则。实现文件发现逻辑找到所有符合条件的 CSV 文件。实现文件读取逻辑处理编码问题和表头不一致问题。实现数据合并逻辑处理列不匹配问题。实现平均值计算逻辑处理空值和非数值列。实现报告生成逻辑输出格式为 Markdown 表格。编写测试用例覆盖正常情况和边界情况。这个拆解结果比我预想的要细致尤其是第 3 步和第 4 步我自己一开始没想到表头不一致和列不匹配的问题。5.2 关键步骤的参数选择与计算过程接下来调用“代码生成技能”逐个实现任务。这里我重点说几个关键决策。文件发现逻辑我选择用pathlib而不是os因为pathlib的 API 更直观而且跨平台兼容性更好。具体参数上用glob(*.csv)匹配所有 CSV 文件用sorted()保证读取顺序一致。编码处理CSV 文件的编码是个坑。我一开始只用了utf-8结果遇到一个 GBK 编码的文件直接报错。后来改成先尝试utf-8失败后回退到gbk再失败就跳过并记录警告。这个逻辑写进了技能文件里以后所有涉及文件读取的任务都会自动处理编码问题。空值处理计算平均值时空值不能直接参与计算否则会得到NaN。我的处理方式是先统计每列的非空值数量如果数量为零平均值设为None否则用非空值的和除以非空值数量。这个逻辑也写进了技能文件。列不匹配处理不同 CSV 文件的列可能不一样。我的策略是取所有文件的列并集缺失的列用None填充。这样合并后的数据框列是完整的不会因为某个文件缺列而报错。这些决策看起来琐碎但每一个都是实际踩坑后总结出来的。技能的价值就在于这些经验被固化下来下次不用重新踩一遍。5.3 执行过程中的现场记录与调整代码生成后我调用“代码审查技能”进行检查。审查结果指出了三个问题第一个问题文件读取时没有限制单次读取的行数如果文件很大可能导致内存溢出。修复方案是加分块读取逻辑每块 10000 行。第二个问题平均值计算没有考虑数值精度问题浮点数累加可能产生误差。修复方案是使用decimal模块或者math.fsum。第三个问题报告生成时没有对列名进行转义如果列名包含 Markdown 特殊字符会导致格式错乱。修复方案是加转义处理。这三个问题里第一个和第三个是我自己没想到的。AI 助手在技能框架下确实能发现一些盲点。修复完成后调用“测试生成技能”生成测试用例。测试覆盖了空目录、单个文件、多个文件、列不一致、空值、非数值列、大文件分块读取。跑完测试全部通过。5.4 最终产出与效果对比最终产出的脚本大约 180 行包含完整的类型注解、文档字符串、错误处理和测试用例。从开始到完成总共花了大约 40 分钟。如果不用技能流程我估计需要 1.5 到 2 小时而且质量可能还不如这个。效果对比上最明显的差异是返工次数。以前用一次性对话模式平均要来回修改 5 到 8 次才能跑通。这次只修改了 2 次而且修改的都是审查阶段发现的问题不是运行时报错。这说明技能流程把问题提前暴露了而不是等到运行时才发现。另一个差异是代码一致性。因为所有代码都是按照同一套技能规范生成的命名风格、注释格式、错误处理方式都很统一。以前手动写或者用一次性对话生成不同部分的风格经常不一致后期维护很头疼。6. 常见问题与排查技巧实录6.1 技能不生效的排查路径这是最常见的问题。你明明写了技能文件但 AI 助手的输出跟以前没什么区别。排查路径如下排查项检查方法常见原因文件路径确认技能文件在助手配置的目录下路径写错或目录不存在文件格式确认文件扩展名和编码正确用了.txt而不是.md或者编码不是 UTF-8触发条件确认当前需求符合技能的触发条件触发条件写得太窄或太模糊加载机制确认助手是否需要重启才能加载新技能有些助手只在启动时扫描技能目录优先级冲突确认没有更高优先级的技能覆盖了当前技能多个技能定义了相同的触发条件我遇到最多的是路径问题。有一次我把技能文件放在了项目根目录的skills文件夹里但助手的配置指向的是用户目录下的skills文件夹。两个路径不一样助手自然读不到。后来我统一了路径问题就解决了。6.2 技能冲突与优先级处理技能冲突的表现是AI 助手的输出前后矛盾或者忽略了某个技能的要求。比如“代码生成技能”要求加类型注解“快速原型技能”要求省略类型注解以加快速度。两个技能同时触发时助手可能随机选一个执行。处理方式前面提过就是定义优先级。但优先级不是万能的有些冲突是设计层面的需要重新组织技能结构。我的经验是如果一个技能经常和其他技能冲突说明它的职责边界不清晰。这时候应该把它拆成更小的技能或者把它降级为基础技能只提供约束而不提供完整流程。还有一种冲突是“隐式冲突”两个技能没有直接矛盾但组合在一起会产生意外结果。比如“代码生成技能”要求函数不超过 50 行“日志记录技能”要求每个函数入口和出口都加日志。两个要求单独看都没问题但组合在一起一个 30 行的函数加上日志可能变成 45 行接近上限。这种冲突不容易发现需要在实际使用中观察。6.3 技能文件写得太长怎么办技能文件太长会导致两个问题一是 AI 助手读取和处理变慢二是你自己维护起来费劲。我的经验是单个技能文件不要超过 200 行。超过的话考虑拆分。拆分的原则是按执行阶段拆。比如一个“完整开发流程技能”可以拆成“需求分析技能”“代码实现技能”“测试生成技能”“文档输出技能”。每个技能只负责一个阶段组合起来完成整个流程。另一个原则是按技术栈拆。比如“前端开发技能”可以拆成“React 技能”“Vue 技能”“样式技能”。不同技术栈的约束不一样混在一起会互相干扰。拆分之后用场景技能来组合。场景技能本身很短只定义“先调用 A再调用 B最后调用 C”具体约束都在各自的技能文件里。6.4 如何判断一个技能是否值得保留我给自己定了一个简单的标准如果一个技能连续一个月没有被调用就删掉或者合并。技能的价值在于复用如果一个月都用不上说明它要么太冷门要么触发条件写得太窄。另一个标准是看它是否减少了返工次数。如果一个技能引入后相关任务的返工次数没有下降说明这个技能没有解决实际问题。这时候要么修改技能内容要么直接删掉。还有一个标准是看它是否增加了理解成本。有些技能写得太复杂调用的时候还要先读一遍技能文件才知道怎么用。这种技能即使有用维护成本也太高。我倾向于把复杂技能拆成几个简单技能每个技能只做一件事。6.5 独家避坑技巧汇总最后分享几个我踩坑后总结的技巧技能文件里不要写具体代码。写规则和约束不要写实现。具体代码让 AI 助手生成技能只负责告诉它“怎么做才对”。触发条件要写宽一点。写得太窄会导致技能经常不触发写得太宽会导致技能在不该触发的时候触发。我的经验是触发条件描述“任务类型”而不是“具体需求”。输出格式要明确。不要只说“输出报告”要说“输出 Markdown 表格包含列名、平均值、非空值数量三列”。格式越明确输出越稳定。定期回顾技能使用记录。我每个月会花半小时看一下哪些技能用得多、哪些用得少、哪些经常出问题。这个习惯帮我淘汰了将近一半的技能。不要追求一次写完美。技能是迭代出来的先写一个粗糙版本用几次之后再优化。一开始就追求完美往往写不出来。提示如果你刚开始接触这套东西建议先从一两个基础技能入手比如“代码生成”和“代码审查”。用顺了之后再逐步增加。一上来就写十几个技能大概率会因为维护不过来而放弃。7. 技能体系的扩展方向与个人实践体会7.1 从个人使用到团队共享个人使用技能体系最大的受益者是自已。但技能真正的价值是在团队层面。当团队里每个人都用同一套技能时输出质量会趋于一致代码审查的成本会大幅下降。我们团队的做法是把技能文件纳入代码仓库和项目代码一起版本管理。每个人都可以提交技能修改但需要经过审查。审查的标准是这个修改是否解决了实际问题、是否引入了新的冲突、是否增加了不必要的复杂度。团队共享还有一个好处是知识沉淀。以前老员工的经验只存在于他脑子里新人来了要慢慢学。现在这些经验被写进技能文件里新人只要调用技能就能按照老员工总结的最佳实践来做事。这比口头传授效率高得多。7.2 技能与自动化流程的结合技能体系可以和 CI/CD 流程结合。比如在代码提交时自动调用“代码审查技能”检查变更把审查结果作为评论发到合并请求上。或者在生成变更日志时自动调用“变更日志技能”把结果写入发布说明。这种结合的关键是让技能可以被程序调用而不仅仅是人工触发。大多数 AI 助手都提供了 API 接口你可以写一个脚本在特定事件发生时调用技能。这样技能就从“辅助工具”变成了“流程节点”。我自己的实践是在合并请求创建时自动触发代码审查技能审查结果作为评论。如果审查发现严重问题合并请求会被标记为需要修改。这个流程运行了几个月确实拦截了一些低级错误。7.3 我个人在实际操作中的体会用了大半年技能体系最大的体会是它改变了我跟 AI 助手协作的方式。以前是我告诉它做什么它做完我检查。现在是我定义规则它按照规则执行我只需要检查规则是否被遵守。角色的转变让我从“执行者”变成了“规则制定者”效率提升是其次更重要的是心态上的轻松。另一个体会是技能体系不是银弹。它解决的是“重复性任务的质量稳定性”问题不解决“创造性任务”的问题。如果你需要 AI 助手做一些全新的、没有先例的事情技能体系帮不上忙。这时候还是得靠一次性对话靠你的描述能力和 AI 的理解能力。还有一个体会是技能的质量取决于你对任务的理解深度。如果你自己对一个任务的理解就是模糊的写出来的技能也是模糊的AI 助手执行起来还是不稳定。写技能的过程其实也是逼自己把任务想清楚的过程。这个附加价值可能比技能本身还重要。最后分享一个小技巧我习惯在技能文件的开头写一句话说明这个技能是“为什么”存在的。比如“这个技能是为了解决 CSV 文件编码不一致导致读取失败的问题”。这句话看起来多余但在几个月后回头看的时候能帮你快速回忆起这个技能的背景。没有这句话你可能会对着一个技能文件发呆想不起来当初为什么要写它。