Superpowers技能框架实战：从零构建可组合的AI工作流

1. 从“superpowers”这个标题说起它到底是什么第一次看到“superpowers”这个词很多人脑子里蹦出来的可能是超级英雄电影或者某个游戏里的技能系统。但如果你最近在开发者社区、效率工具圈或者AI工作流相关的讨论里频繁刷到它那它指的其实是另一回事——一套围绕“技能skills”组织起来的个人能力扩展框架。简单说它想解决的问题是你手头有一堆零散的工具、脚本、提示词、操作流程平时散落在各个文件夹和笔记里用的时候找不到找到了又记不住怎么用。superpowers 试图把这些东西统一成一种可引入、可调用、可组合的“技能”单元。我最初接触这个概念的时候第一反应是“又一个花哨的命名”。但实际用下来发现它的核心思路确实有可取之处。它不绑定某个特定平台也不要求你写多复杂的代码更多是在做一件事把“你会做的事”变成“随时能调出来的能力”。这个定位对独立开发者、内容创作者、自动化流程爱好者来说吸引力很直接。你不需要成为某个领域的专家只要能把重复操作整理成技能就能在需要的时候一键触发。适合读这篇内容的人大概有三类。第一类是平时用各种效率工具比较多、但总觉得“工具之间是割裂的”的人第二类是对AI辅助工作流感兴趣、想把自己的提示词和操作习惯沉淀下来的人第三类就是单纯看到“superpowers”这个词被反复提及、想知道它到底怎么用、值不值得花时间折腾的人。不管你是哪一类下面我会从整体设计思路、核心细节、实操过程到常见问题一层层拆开讲。2. 整体设计思路为什么是“技能”而不是“工具”2.1 技能与工具的本质区别很多人会把 superpowers 理解成一个工具箱但更准确的说法是“技能库”。工具是静态的你打开它、用它、关掉它技能是动态的它包含触发条件、执行步骤、上下文依赖和输出结果。举个例子你有一个批量重命名文件的脚本那是一个工具但如果你把它包装成“整理下载文件夹”这个技能里面可能包含检查文件类型、按日期分类、重命名规则、异常处理、执行后清理空文件夹。这一整套动作才叫技能。superpowers 的设计逻辑就是围绕这个区别展开的。它不关心你用什么语言写脚本也不关心你是在本地还是远程执行它关心的是这个能力能不能被描述清楚、能不能被稳定触发、能不能在需要的时候被组合进更大的流程里。这个思路的好处是你不需要把所有东西都塞进一个巨型工具里而是可以按需拼装。坏处也很明显如果你没有整理习惯技能库会变得很乱最后跟散落的脚本没区别。2.2 为什么选择“引入”而不是“安装”热词里有个说法叫“想要安装superpowers”但更准确的动词是“引入”。安装通常意味着一个独立的软件包装完就有完整界面和固定功能引入则更像把一套规则和结构接入你现有的工作环境。superpowers 本身不是一个可执行文件它更像一套约定技能怎么命名、怎么存放、怎么被调用、怎么组合。你可以在不同的编辑器、不同的自动化平台、甚至不同的AI助手环境里引入同一套技能定义。这个选择背后的考量很实际。如果做成独立软件它就得自己实现所有底层能力比如文件操作、网络请求、文本处理那它就变成了另一个臃肿的工具。而做成“引入式”的框架它可以复用你已有的环境能力只负责组织和调度。对使用者来说学习成本更低因为你不需要学一套全新的操作界面只需要按它的结构整理你本来就会的东西。2.3 技能的组织方式与命名逻辑我见过不少人引入 superpowers 之后第一件事就是建一个叫“skills”的文件夹然后往里扔各种脚本。这样做不是不行但很快就会遇到问题技能多了之后你根本记不住哪个技能叫什么、干什么用。所以它的组织方式其实有讲究。通常建议按“领域动作”来命名比如file-batch-rename、text-summarize、image-compress。领域在前动作在后这样你在列表里扫一眼就能定位。更深一层的是技能之间的依赖关系。有些技能是独立的比如“压缩图片”有些技能是组合的比如“发布文章”可能依赖“压缩图片”“生成摘要”“上传文件”三个子技能。superpowers 允许你在技能定义里声明依赖这样调用上层技能时底层技能会自动按顺序执行。这个机制听起来简单但实际用起来能省很多事。你不需要每次手动跑一遍流程只要把流程拆成技能然后组合一次以后就能重复用。3. 核心细节解析技能到底长什么样3.1 一个技能的基本结构不管你在哪个环境里引入 superpowers一个技能通常包含几个固定部分名称、描述、触发条件、执行步骤、输入参数、输出结果。名称和描述是给人看的触发条件是给系统看的执行步骤是实际逻辑输入输出是接口定义。我拿一个实际例子来说明。假设你要做一个“把Markdown转成带样式的HTML”的技能它的结构大概是这样名称markdown-to-html描述将Markdown文本转换为带基础样式的HTML片段触发条件当输入内容以#或-开头且包含Markdown语法特征时输入参数content字符串、theme可选默认light执行步骤解析Markdown、应用样式模板、输出HTML输出结果HTML字符串这个结构看起来有点繁琐但它的价值在于“可预测”。当你把几十个技能都按这个格式整理好之后你或者你的协作方在调用时不需要猜看描述就知道怎么用。而且很多自动化平台和AI助手可以直接读取这种结构化定义自动帮你匹配技能。3.2 触发条件的设置技巧触发条件是整个技能定义里最容易出问题的地方。设得太宽技能会被频繁误触发设得太窄你又得手动指定失去了自动化的意义。我的经验是触发条件尽量用“输入特征”而不是“时间”或“位置”。比如“当输入内容包含‘总结’且长度超过500字时触发摘要技能”这比“每天下午三点触发摘要技能”要可靠得多。因为时间是固定的但你的需求不是固定的。另外触发条件最好支持组合。比如“当文件扩展名是.jpg且文件大小超过2MB时触发压缩技能”。这种组合条件能过滤掉大量不需要处理的情况。superpowers 的技能定义里通常支持逻辑与、或、非你可以根据实际场景灵活搭配。我自己的习惯是每个技能最多设两个条件再多就容易互相干扰。3.3 输入输出的标准化输入输出标准化是很多人忽略的一步。你写一个技能如果输入格式每次都不一样那这个技能就没法复用。比如一个“发送通知”的技能输入可能是纯文本、可能是JSON、可能是Markdown那执行步骤里就得写一堆判断逻辑。更好的做法是在技能定义里明确输入类型比如message必须是字符串priority必须是high、medium、low之一。这样调用方就知道该怎么传参执行方也不用做太多容错。输出也一样。如果技能返回的结果格式不统一组合技能的时候就会很痛苦。我一般要求所有技能的输出要么是纯文本要么是结构化对象不要混着来。纯文本适合直接展示结构化对象适合传给下一个技能。这个约定一旦定下来后面组合技能会顺畅很多。4. 实操过程从零引入一套自己的技能4.1 环境准备与目录结构不管你用什么编辑器或自动化平台第一步都是建目录。我建议的目录结构是这样的superpowers/ skills/ file/ batch-rename.md compress-image.md text/ summarize.md translate.md workflow/ publish-article.md config/ settings.json logs/skills下面按领域分文件夹每个技能一个文件。文件格式可以是Markdown加YAML头也可以是纯JSON看你的环境支持什么。config放全局设置比如默认主题、超时时间、日志级别。logs放执行记录方便排查问题。这个结构不复杂但能让你在技能数量增长到几十个的时候依然保持清晰。4.2 编写第一个技能文件批量重命名我拿“文件批量重命名”这个技能来演示完整流程。首先在skills/file/下新建batch-rename.md内容大概是这样--- name: batch-rename description: 按规则批量重命名指定目录下的文件 trigger: - type: manual input: directory: string pattern: string replacement: string output: renamed_count: number errors: array ---然后下面是执行步骤的说明。实际执行逻辑可以写在同一个文件里也可以引用外部脚本。如果你的环境支持直接执行代码那就把逻辑写清楚如果不支持就写清楚调用哪个脚本、传什么参数。我自己的做法是技能文件只负责定义和说明实际逻辑放在独立的脚本文件里技能文件里用路径引用。这样技能定义和实现分离改逻辑的时候不用动定义。4.3 引入技能到工作环境定义写好了下一步是让环境知道这些技能存在。不同环境的引入方式不一样但核心逻辑都是“注册”。比如在某个支持技能加载的编辑器里你需要在配置文件里加一行skills_path: ./superpowers/skills然后重启或重新加载。在自动化平台里可能是通过一个注册接口把技能列表传进去。在AI助手环境里可能是把技能描述作为上下文注入。这里有个坑要注意引入之后一定要做一次“技能发现”测试。就是随便调用一个技能看系统能不能正确识别名称、参数和触发条件。我遇到过好几次技能文件写得好好的但引入之后系统读不到最后发现是文件编码问题或者YAML格式缩进错了。所以引入之后别急着用先跑一个最简单的技能验证链路通不通。4.4 组合技能把多个技能串成工作流单个技能能用之后就可以组合了。比如“发布文章”这个工作流可以拆成三个子技能text-summarize、image-compress、file-upload。在workflow/publish-article.md里你只需要声明依赖顺序--- name: publish-article description: 将文章摘要、压缩图片并上传 steps: - skill: text-summarize input: ${article_content} - skill: image-compress input: ${article_images} - skill: file-upload input: ${summarized_text}, ${compressed_images} ---这样调用publish-article的时候系统会自动按顺序执行三个子技能并把前一个的输出传给后一个。这个机制的好处是你不需要写复杂的编排代码只需要声明依赖关系。坏处是如果某个子技能失败了整个工作流会中断你需要额外处理错误恢复。我的做法是在每个子技能里加一个retry参数失败自动重试两次还不行就记录日志并跳过。5. 常见问题与排查技巧实录5.1 技能不触发或误触发这是最常见的问题。技能不触发通常是因为触发条件写得太死。比如你写“当输入内容等于‘总结’时触发”那用户输入“帮我总结一下”就不会触发。解决办法是把条件放宽用“包含”而不是“等于”。误触发则相反条件太宽比如“当输入内容包含‘文件’时触发”那几乎每句话都会触发。解决办法是加长度限制或组合条件比如“包含‘文件’且长度小于50字”。5.2 技能执行超时或卡死技能执行超时一般是底层操作耗时太长比如网络请求、大文件处理。superpowers 本身不限制执行时间但你的环境可能有超时设置。我的经验是在技能定义里加一个timeout字段默认30秒特殊技能单独设。比如图片压缩可以设60秒文本摘要设10秒。另外执行步骤里尽量加进度日志这样卡住的时候你知道卡在哪一步。5.3 技能之间参数传递错误组合技能的时候参数传递最容易出错。比如前一个技能输出的是对象后一个技能期望的是字符串直接传就会报类型错误。解决办法是在技能定义里明确输入输出类型组合的时候做一次转换。我通常会在工作流定义里加一个transform步骤专门做格式转换。虽然多了一步但能避免很多莫名其妙的错误。5.4 技能库越来越乱怎么办技能多了之后命名冲突、功能重叠、废弃技能堆积这些问题都会出现。我的做法是每个月做一次“技能审计”列出所有技能标记使用频率低频的归档重复的合并废弃的删除。另外技能描述里加一个version字段每次修改递增这样你知道哪个版本是当前用的。这个习惯看起来麻烦但能让你在半年后依然能快速找到需要的技能。问题类型典型表现排查方向解决手段不触发输入后无反应触发条件是否过严放宽条件用包含替代等于误触发频繁自动执行触发条件是否过宽加长度限制或组合条件超时执行中途卡住底层操作耗时设timeout加进度日志参数错误类型不匹配报错输入输出类型不一致明确类型加转换步骤库混乱找不到技能命名和分类是否规范定期审计加版本号6. 我个人的使用体会与几个实用建议用了一段时间 superpowers 之后我最大的感受是它的价值不在于技能本身有多强大而在于“整理”这个动作。你被迫把自己会做的事情写清楚、拆细、定义好输入输出这个过程本身就会让你对自己的工作流有更清晰的认识。我以前很多操作都是凭记忆现在写成技能之后不仅自己能复用还能分享给别人。另外不要一开始就追求大而全。我见过有人一上来就想把几十个操作全做成技能结果定义写了一半就放弃了。更好的做法是从你每天重复三次以上的操作开始先做一个技能用顺了再加第二个。技能库是长出来的不是设计出来的。还有一个细节技能描述里尽量写“什么时候用”而不是“这个技能是什么”。比如“当你需要把长文章压缩成三句话时使用”比“文本摘要技能”更有指导性。因为调用的时候你脑子里想的是场景不是功能名称。最后如果你在团队里用建议把技能库放在共享目录里每个人都可以提交新技能但合并之前要经过一次“可执行性验证”。不然技能库会变成垃圾场谁都不想用。验证很简单让另一个人按技能描述操作一遍能跑通就合并跑不通就退回修改。这个规则虽然简单但能保证技能库的质量。