1. 从“superpowers”这个热词说起它到底指什么最近一段时间“superpowers”这个词在技术社区和效率工具圈子里被反复提起。很多人第一次看到它会以为是某个新出的超级英雄题材游戏或者某种硬件外设的代号。但真正在圈子里泡过一阵的人会告诉你它指的是一套围绕“技能skills”组织起来的个人能力扩展机制——你可以把它理解成一个能力插件系统核心思路是把零散的工具、脚本、提示词、工作流打包成一个个可复用的“技能单元”然后在需要的时候按需引入、组合调用。这个概念的吸引力在于它解决了一个非常现实的痛点大多数人在日常工作和学习中积累了大量碎片化的方法比如某个特别好用的文本处理脚本、一套调试接口的固定流程、一段反复粘贴的配置模板但这些资产散落在各个角落用的时候想不起来换台机器就丢了想分享给别人也说不清楚。superpowers 试图做的事情就是给这些碎片一个统一的容器和调用入口。我自己最早接触这个概念是因为团队里有个同事总能在几分钟内完成别人半小时的活。后来发现他并不是手速快而是手里攒了几十个“技能”每个技能对应一类具体任务需要的时候直接调出来用。这套东西的门槛其实不高但信息差很大——知道的人已经在享受复利不知道的人还在重复造轮子。这篇文章就是想把 superpowers 的来龙去脉、技能体系、引入方式和安装路径讲清楚让不同基础的人都能上手。需要先说明一点superpowers 本身不是一个单一的软件产品它更像是一种组织理念加上一套配套的目录结构和调用约定。不同的人、不同的团队会根据自己的需求做出不同的实现。所以下面讲的内容是基于社区里比较通行的实践总结出来的你在实际操作时可以根据自己的环境做调整。2. superpowers 的核心机制技能是怎么被组织和调用的2.1 技能单元的基本结构要理解 superpowers先要理解“技能”这个最小单元长什么样。一个技能通常包含三个部分元信息、执行逻辑和触发条件。元信息描述这个技能叫什么、干什么用、适合什么场景执行逻辑是真正干活的部分可以是一段脚本、一组命令、一个配置文件甚至是一段结构化的提示词触发条件则决定了这个技能在什么时候被激活可以是手动调用也可以是根据上下文自动匹配。这种结构和我们熟悉的函数封装很像但比函数更“厚”。函数通常只关心输入输出而技能还要关心“什么时候该用它”以及“用完之后怎么把结果交出去”。举个例子一个叫“整理会议纪要”的技能它的元信息会写明适用于“多人讨论后的文本整理”执行逻辑可能包含分段、提取待办、标注负责人这几步触发条件可能是检测到输入文本里有“会议”“讨论”“决议”这类关键词。社区里常见的技能目录结构大致是这样的skills/ meeting-notes/ skill.md process.py template.txt api-debug/ skill.md debug.sh config.json每个技能一个文件夹文件夹名就是技能标识里面的skill.md负责描述其他文件是具体实现。这种结构的优点是自包含复制一个文件夹就能把技能迁移到另一台机器上不依赖全局环境。2.2 技能是怎么被“引入”的“引入”这个词在 superpowers 的语境里有两层含义。第一层是物理引入就是把技能文件夹放到系统能识别的位置通常是某个约定的技能根目录。第二层是逻辑引入就是让系统知道在什么情况下该调用哪个技能。物理引入比较简单把文件夹拷过去就行。逻辑引入才是真正体现设计水平的地方。常见的做法有三种显式调用用户主动输入技能名或快捷指令系统直接执行对应技能。这种方式最可控适合那些需要明确意图才触发的操作。关键词匹配系统扫描输入内容如果命中技能元信息里定义的关键词就提示或自动执行。这种方式适合高频、低风险的任务。上下文推断根据当前所处的环境比如正在编辑的文件类型、正在访问的接口路径来推断该用哪个技能。这种方式最智能但也最容易误触发需要谨慎设计。我自己的经验是初期不要追求自动匹配先把显式调用跑通等技能库稳定了再逐步加自动触发规则。否则技能一多互相抢触发条件反而添乱。2.3 技能之间的组合与依赖单个技能能解决的问题有限真正体现威力的是技能组合。比如“抓取数据”技能负责从某个来源拉取原始内容“清洗数据”技能负责格式化“生成报告”技能负责输出最终文档三个技能串起来就是一条完整流水线。superpowers 里处理组合的方式通常是声明依赖。在技能的元信息里写明它依赖哪些其他技能系统在调用时会自动把依赖链上的技能都准备好。这有点像包管理里的依赖解析只不过解析的对象是技能而不是代码库。这里有个容易踩的坑依赖声明要尽量扁平避免出现 A 依赖 B、B 依赖 C、C 又依赖 A 的循环。一旦出现循环系统在解析时就会卡住或者报错。我在早期设计技能时没注意这一点结果两个技能互相引用排查了半天才发现是循环依赖。后来养成的习惯是画一张技能依赖图确保它是一棵有向无环图。3. 社区里常见的 skills 类型盘点3.1 文本处理类技能这是数量最多、使用频率最高的一类。典型代表包括会议纪要整理、长文摘要提取、多语言翻译、格式转换比如 Markdown 转 HTML、敏感词过滤、文本去重等。这类技能的共同特点是输入输出都是文本逻辑相对独立不依赖外部系统状态所以最容易开发和复用。以“长文摘要提取”为例一个设计良好的技能不会简单地把文本丢给模型然后返回结果而是会先做分段、再对每段做摘要、最后合并并去重。这样做的好处是可控性强即使某一段处理失败也不会影响整体输出。我在实际使用中发现分段长度控制在 800 到 1200 字之间效果比较稳太短了上下文不够太长了模型容易漏掉细节。3.2 开发辅助类技能这类技能主要面向写代码的场景比如代码格式化、接口调试、日志分析、依赖检查、提交信息生成等。它们的执行逻辑往往需要调用外部命令或访问本地文件系统所以对环境的依赖比文本处理类要强。一个比较实用的例子是“接口调试”技能输入一个接口地址和参数技能自动构造请求、发送、解析响应并把结果按固定格式输出。如果响应异常还会附带常见的排查建议。这种技能的价值在于把重复的调试动作标准化减少每次都要重新想“该怎么发请求”的认知负担。需要注意的是开发辅助类技能往往涉及凭证和权限设计时要考虑敏感信息怎么存放。我的做法是把凭证放在环境变量里技能只引用变量名不硬编码具体值。这样技能文件夹可以安全地分享给别人不会泄露个人配置。3.3 信息整理与检索类技能这类技能解决的是“信息太多找不到重点”的问题比如网页内容提取、文档索引、知识库检索、RSS 聚合等。它们的执行逻辑通常包含抓取、解析、存储、查询几个环节对稳定性的要求比较高。以“文档索引”技能为例它会扫描指定目录下的文档提取标题和关键段落建立一个本地索引文件。之后查询时直接查索引不用每次重新扫描。这个技能的关键在于索引的更新策略是全量重建还是增量更新全量重建简单但慢增量更新快但容易漏。我一般建议对变化不频繁的目录用全量对频繁变动的目录用增量加定期全量校准。3.4 流程自动化类技能这类技能把多个步骤串成一条自动执行的流水线比如“每日报告生成”“定时备份”“批量文件重命名”等。它们的执行逻辑往往包含条件判断和循环设计复杂度最高但一旦跑通节省的时间也最多。流程自动化类技能最需要注意的是失败处理。流水线里任何一步出错如果没有妥善处理可能导致后续步骤在错误的状态下继续执行产生更难排查的问题。我的习惯是在每个关键步骤后加检查点失败时记录现场并中止而不是硬着头皮往下跑。技能类型典型场景开发难度环境依赖复用性文本处理摘要、翻译、格式转换低低高开发辅助调试、格式化、日志分析中中中信息整理索引、检索、聚合中中中流程自动化报告、备份、批处理高高低这张表是我根据自己维护技能库的经验总结的不一定适用于所有人但可以作为一个参考框架。复用性高的技能值得多花时间打磨复用性低的技能够用就行不必过度设计。4. 把技能引入自己的工作流从零开始的完整路径4.1 先想清楚你要解决什么问题很多人一上来就问“怎么安装 superpowers”但更关键的问题是“你打算用它来干什么”。技能体系本身只是容器里面装什么取决于你的实际需求。我的建议是先花半天时间把自己日常工作中重复度最高的五到十个动作列出来按频率和耗时排序优先把排名靠前的做成技能。这个梳理过程不需要很正式拿张纸或者开个文档左边写“我经常要做的事”右边写“每次大概花多久”。列完之后你会发现真正值得做成技能的其实不多大部分琐事要么频率太低要么每次情况都不一样强行标准化反而别扭。4.2 搭建技能目录和基础配置确定要做的技能之后下一步是搭目录。找一个你习惯的位置建一个skills文件夹里面按技能名建子文件夹。每个子文件夹里至少放一个skill.md写明技能名称、用途、输入输出格式、依赖项。如果技能需要执行脚本再放对应的脚本文件。基础配置方面通常需要一个入口文件来告诉系统技能根目录在哪、怎么解析技能元信息。这个入口可以是一个简单的配置文件也可以是一段启动脚本。具体形式取决于你用的工具链但核心逻辑是一样的扫描目录、读取元信息、建立技能索引。提示技能目录不要放在系统临时目录或容易清理的位置否则某次清理之后技能就丢了。建议放在用户主目录下的固定路径并纳入版本管理。4.3 写第一个技能从最简单的开始第一个技能不要选太复杂的建议从纯文本处理类入手比如“把选中的文本整理成列表”。这个技能不需要外部依赖逻辑简单容易验证。写完之后手动调用几次确认输入输出符合预期再考虑加自动触发。写技能元信息时有几个字段值得认真填名称简短、唯一、见名知意避免用缩写。描述一句话说清楚这个技能做什么不要写“处理文本”这种模糊表述。适用场景列出两到三个典型使用场景帮助自己和别人判断什么时候该用它。输入格式明确输入是纯文本、文件路径还是结构化数据。输出格式明确输出是直接返回、写入文件还是打印到终端。这些字段看起来繁琐但等到技能多了之后你会发现它们是快速定位技能的关键。我自己的技能库有四十多个技能全靠元信息里的描述来检索如果当初偷懒没写清楚现在根本找不到。4.4 验证技能是否真正可用技能写完不等于能用。验证环节要检查三件事功能是否正确、边界情况是否处理、失败时是否有清晰提示。功能正确性靠实际跑几遍来确认最好用真实数据而不是构造的测试数据。边界情况包括空输入、超长输入、特殊字符输入等这些在真实使用中出现的概率比想象中高。失败提示则决定了出问题时你能不能快速定位一个好的失败提示应该包含“哪一步失败了”“可能的原因”“建议的下一步动作”。我踩过的一个坑是技能在正常输入下跑得很好但遇到空输入时直接抛了一个底层异常堆栈信息一大堆根本看不出是技能本身的问题。后来养成的习惯是每个技能入口处先做输入校验不合法就返回明确提示不让异常穿透到调用层。5. 安装 superpowers 时最容易卡住的几个环节5.1 目录权限与路径问题安装过程中最常见的问题就是路径不对或权限不足。技能目录如果放在系统保护的位置写入时会失败如果路径里包含空格或特殊字符某些工具解析时会出错。我的建议是路径尽量用纯英文、无空格、层级不要太深比如~/workspace/skills这种就很好。权限方面确保当前用户对技能目录有读写权限。在类 Unix 系统上可以用ls -la查看目录权限必要时用chmod调整。Windows 上则要注意文件夹是否被其他程序占用以及是否开启了只读属性。5.2 依赖缺失与版本冲突很多技能依赖外部工具或库安装时如果这些依赖没准备好技能调用就会失败。常见的缺失包括脚本解释器版本不对、某个命令行工具没装、某个库的版本太老或太新。处理这类问题的思路是先隔离再定位。先在一个干净的环境里单独跑这个技能看报什么错然后逐个补齐依赖。不要一上来就在主环境里乱装东西否则依赖冲突会越来越严重。我一般会为技能库单独建一个虚拟环境或容器把依赖装在里面和主系统隔离开。5.3 技能索引不更新有时候技能文件夹明明放进去了但系统就是识别不到。这种情况多半是索引没更新。大多数技能系统会在启动时扫描一次目录之后如果新增了技能需要手动触发重新扫描或者重启服务。排查这个问题的步骤很简单先确认技能文件夹确实在技能根目录下再确认文件夹里有合法的元信息文件最后检查系统是否需要手动刷新索引。如果这三步都没问题再看日志里有没有解析错误。元信息文件格式不对是导致索引失败的常见原因比如缺少必填字段、字段名拼写错误、文件编码不对等。5.4 调用时提示“技能不存在”这个提示通常意味着系统在索引里找不到对应技能。可能的原因包括技能名拼写错误、技能被放在了错误的目录层级、索引缓存过期。排查时先用ls确认文件夹存在再用系统提供的列表命令查看已识别的技能列表对比一下就能发现问题。还有一种情况是技能名大小写不一致。有些系统对大小写敏感MeetingNotes和meetingnotes会被当成两个不同的技能。建议统一用小写加连字符的命名风格比如meeting-notes避免这类问题。6. 让技能库真正产生复利的几个习惯6.1 定期清理和合并重复技能技能库用久了难免会出现功能重叠的情况。比如你可能先后写了“整理会议纪要”和“提取会议待办”两个技能后来发现它们其实可以合并成一个。定期花时间做一次清理把重复的合并、把过时的删掉能让技能库保持精简。我的做法是每个季度过一遍技能列表按使用频率排序三个月没用过的技能要么删掉要么标记为“待观察”。如果一个技能连续两个季度都没被调用基本可以确定它不值得保留。6.2 给技能写清楚“不适用场景”大多数人在写技能描述时只写“这个技能能做什么”但很少写“这个技能不适合什么情况”。后者其实同样重要甚至更重要。因为误用技能比不用技能更浪费时间。比如一个“自动生成周报”的技能如果输入的是日粒度的工作记录生成出来的周报会很碎如果输入的是季度总结又会太粗。在描述里写明“适用于日粒度到周粒度的工作记录不适用于季度及以上粒度”就能避免别人用错。6.3 建立技能版本管理技能是会迭代的。今天写的技能过两个月可能因为需求变化需要调整。如果没有版本管理改坏了想回退都回不去。最简单的做法是用 Git 管理技能目录每次修改都提交一次写清楚改了什么、为什么改。版本管理还有一个好处是方便分享。别人想要你的某个技能直接给一个仓库地址就行不用打包发文件。如果技能里有敏感信息记得用环境变量或配置文件分离不要把凭证提交到仓库里。6.4 把技能当成产品来打磨最后一个习惯可能有点反直觉不要只把技能当成“自己用的小工具”而是当成“要给其他人用的产品”来打磨。这个心态转变会直接影响你的设计决策——你会更在意命名是否清晰、描述是否准确、失败提示是否友好、边界情况是否处理。我自己的体会是当我开始把技能分享给团队其他人用之后技能的质量提升速度明显加快了。因为别人不会像自己那样容忍模糊和粗糙他们会直接告诉你哪里不好用。这些反馈是闭门造车得不到的。7. 关于技能引入方式的一点个人看法回到最开始的问题怎么引入这些技能我的答案是引入方式本身没有绝对的最优解关键是要和你的实际使用节奏匹配。如果你只是偶尔用一下显式调用就够了没必要搞自动触发如果你每天都在用同一批技能那值得花时间配置关键词匹配甚至上下文推断。我见过一些人一上来就追求全自动结果技能之间互相干扰反而降低了效率。也见过一些人坚持手动调用技能库攒了上百个但每次都要想“这个任务该用哪个技能”认知负担很重。比较稳妥的路径是先手动再半自动最后根据实际痛点决定要不要全自动。另外技能的数量不是越多越好。一个精心设计的技能如果能覆盖你 80% 的同类任务比十个各覆盖 20% 的技能更有价值。与其追求数量不如追求每个技能的完成度和可靠性。我现在维护的技能库稳定在三十个左右覆盖了日常工作中大部分重复性任务新增技能的速度已经明显放缓因为大部分需求已经被现有技能满足了。如果你刚开始接触 superpowers建议从一两个最简单的技能做起跑通整个流程感受到便利之后再逐步扩展。不要一开始就想着建一个大而全的技能库那样很容易在配置和调试阶段就耗尽耐心。先跑起来再优化这个顺序不能反。
