我最近在捣鼓自己的 AI 辅助工作流时碰到了一个名字很张扬的工具——superpowers。它把自己定位成AI 助手的技能增强框架说白了就是一套能让 Claude、Gemini 这类模型长出更多手脚的技能管理方案。很多人第一次听到这名字会觉得是概念炒作但我自己把它的源码、文档和示例技能全过了一遍又实际在几个真实项目里跑通了之后可以负责任地说这玩意儿确实解决了一些很实在的问题而且安装和上手比我想象中要简单得多。如果你已经在用 AI 写代码、整理资料、做数据分析却总觉得它什么都懂但落地总差一口气那这篇就适合你。我会从它的核心设计出发讲清楚它到底帮你干了什么事、装完之后有哪些 skills 可用、怎么正确地引入新技能以及我在实战里踩过的坑。下面全部是实操记录照做就行。1. 为什么需要一个技能库superpowers 想解决的三个痛点单纯把模型接进工作流其实是不够的。我用过半年多的各类 AI 辅助工具最深的感受是模型本身的能力很强但它不会替你主动干活你得把怎么干的步骤一次次地讲给它听。这个重复劳动就是 superpowers 想干掉的东西。1.1 第一个痛点每次对话都要重新教一遍举个最常见的例子我经常需要把一段零散的会议记录整理成结构化的任务清单。以前的做法是在提示词里写一大堆规则请提取责任人和时间节点按优先级排序保留原始表述等等。第一次有效第二次就没那么准第三次我可能还得再改提示词。这本质上是在浪费模型的能力也浪费我的时间。superpowers 的思路是把这类流程固化成技能。一个技能就是一套带触发条件、执行步骤和输出格式的完整定义。当你需要整理会议记录时只需要告诉 superpowers用会议整理技能它就会自动按预设的规则执行不需要我重复描述需求。这个转变听着不大实际用起来差别很明显——就像从每次都得手把手教实习生变成直接给实习生发一份 SOP。1.2 第二个痛点技能代码散落各处无法复用如果你跟我一样遇到过在两三个不同的项目里写几乎相同的处理脚本那你应该能理解这个痛点。我以前的处理方式是把脚本存到一个common目录里用的时候复制粘贴。问题是每次复制都带着环境差异改来改去版本也会乱掉。superpowers 把技能做成了统一的可分发单元。每个技能有自己的定义文件、依赖声明和触发规则打包之后可以放进仓库里共享也可以直接从一个技能库引入。这意味着我不再需要在每个项目里重复维护同一套逻辑而只需要在配置里声明我要用这个技能剩下的交给框架去加载。1.3 第三个痛点触发机制不够聪明早期我自己写过一些自动化脚本但触发它们的过程很别扭。要么是靠手动跑命令要么是通过关键词匹配稍微复杂一点的场景就失灵了。比如我希望当用户上传 Excel 后自动做数据质量检查关键词匹配根本写不出这种复杂的条件。superpowers 的触发机制比我预期中要聪明它允许你给技能定义结构化的触发条件既有基于上下文的判断也有基于输入特征的匹配。你可以说当用户提到数据清洗时且上下文里存在表格文件路径就加载对应技能也可以说每当输出格式是 Markdown 时自动套用格式化流程。它是可编程的而不是死板的字符串匹配。这套设计看起来不起眼但解决的是技能可用性的根本问题。如果触发不准确技能再多也是摆设。superpowers 让我可以把路由逻辑写在明处调试的时候一目了然。这是我愿意继续用它最重要的原因。2. 安装 superpowers五步搭好技能基座安装这步其实没什么神秘的但有几个细节容易忽略。我把自己从零开始装到可用的完整过程写下来你照着做就行。2.1 环境检查与依赖确认superpowers 的运行时依赖并不多不过为避免后面卡壳建议先确认三样东西操作系统macOS 和 Linux 都测试过Windows 如果要跑建议配合 WSL 2 使用否则路径处理会出现不少问题。Node.js 版本建议 18 或更高因为框架的部分核心逻辑用到了较新的异步特性。低于 16 会有兼容性问题。bash 环境虽然它不强制依赖 bash但内置技能的很多示例是用 bash 写的缺了的话初始化脚本跑不顺畅。你可以先执行node -v确认版本。如果版本过旧不要急着装 superpowers先把 Node 升上去否则后边会遇到一堆方法不存在的报错。2.2 安装命令与目录结构安装本身用 npm 全局安装即可这个没什么争议npm install -g superpowers-cli装完之后你会得到一个sp命令。注意不是superpowers是缩写sp我第一次就输错了全名结果提示找不到命令。安装完成后默认的目录结构大概是这样~/.superpowers/ ├── config.yaml # 全局配置包括默认技能仓库 ├── skills/ # 已安装的技能都在这里 │ ├── web-summarizer # 具体的技能目录 │ │ ├── SKILL.md # 技能定义文件写触发条件和执行逻辑 │ │ └── scripts/ # 技能实际调用的脚本或提示词模板 │ └── ... └── logs/ # 运行日志这套目录设计的好处是所有东西都在一个地方备份和迁移很容易。我迁移机器的时候直接把这个目录打包拷走解压后重新指向一份配置就能用。2.3 初始化配置把技能仓库挂进来安装完之后需要跑一次初始化sp init它会在你的主目录生成~/.superpowers/config.yaml并提示你选择默认技能仓库。配置文件的几个关键项是默认仓库地址、技能最大执行时长、模型接入点。如果你是刚接触建议先保持默认等熟悉了再改。这一步很多人会跳过我建议不要。因为不跑 init 的话后边执行sp list会提示找不到配置文件你还要回头排查不如一开始就把基础打牢。2.4 验证安装是否成功跑一个最简单命令看能不能正常输出sp list如果能看到内置技能的列表说明安装没问题了。第一次跑这个命令会有一小段时间它需要去拉取技能索引。如果卡在这里不动大概率是网络问题可以检查一下代理设置或者手动把技能仓库地址配成一个可访问的镜像源。2.5 多环境并存的建议如果你同时有个人项目和公司项目建议给每个项目单独建一份配置用环境变量SUPERPOWERS_CONFIG指定不同的配置文件。这样切换项目的时候不用反复改配置也避免不同项目的技能互相污染。我一开始就是全局一套配置结果公司项目的技能和个人技能混在一起排查问题的时候非常痛苦。3. 内置 skills 全景开箱即用的能力清单装完之后最好奇的就是有哪些 skills 能用。我先把默认带的那批技能翻了个遍挑几个最有代表性的做个分类和点评你再按需选用。3.1 高频实用型网页解析、文件整理、批量重命名默认技能库里最常用的三件套是web-summarizer、file-organizer和batch-renamer。web-summarizer的功能是抓取一个 URL 并生成结构化摘要。它不只是简单地提取正文而是会按核心观点、关键数据、行动建议三个维度输出。我拿它处理过几篇长文和技术文档生成出来的摘要基本可以直接用不用大改。file-organizer解决的是目录变成垃圾场的问题。给它一个目录路径它会按文件类型、修改时间、命名特征自动分类归档。它有一个细节做得不错移动文件之前会先生成一份执行计划你需要确认后它才会执行。这个设计避免了不少误操作。batch-renamer专门处理批量重命名场景。它支持规则表达式也支持基于模板的命名最重要的是它有 dry-run 模式——先展示重命名前后的对照列表确认无误后再真正执行。这个安全机制我特别看重因为批量重命名一旦出错恢复成本很高。3.2 进阶分析型日志分析、代码审查、数据清洗如果你做开发或数据处理下面这三类技能会更对胃口。log-analyzer能读入一段日志文件自动提取错误级别、高频异常、时间分布并给出可能的原因推断。我用它处理过一次线上故障的日志几千行日志靠人眼看怎么也得半小时它几分钟就给了一份带时间线的异常汇总定位速度确实快了不少。code-reviewer的设计思路不是找 bug而是按维度审视代码质量。它会从可读性、边界处理、潜在性能问题、安全风险这几个维度给出评分和改进建议。它的输出不带情绪就是指出现象和给出建议实测下来比很多人的人工审查还要客观。>sp install web-summarizer这个命令会从默认仓库拉取技能文件放到本地的skills/目录下并自动更新索引。如果你不确定技能叫什么名字可以用sp search 关键词搜一下sp search 数据清洗搜索结果会列出技能名、简介、维护状态和最近更新时间。建议优先选维护状态是active的技能避免装了一堆没人维护的坑货。装完之后要特别注意它只是把技能文件放到了本地是否自动生效取决于你的触发配置。如果你希望某个技能始终可用可以在 config.yaml 里把它加进always_active列表如果希望按需触发则保持默认的按需加载即可。4.2 写一个最简单的自定义 skill从零到可用内置技能不够用的时候就得自己写了。我拿一个我实际写的技能举例把中文 PDF 转成 Markdown 笔记。它的核心需求其实就三块提取文本、处理目录层级、输出固定格式。写技能需要建一个目录结构是这样的my-pdf-note/ ├── SKILL.md └── scripts/ └── convert.pySKILL.md是核心它定义了技能的元信息和执行入口。一个最简版本的 SKILL.md 大概长这样--- name: pdf-to-note description: 将 PDF 文件转换为结构化 Markdown 笔记 trigger: 当用户提到 PDF 转笔记或提供 PDF 路径时 parameters: pdf_path: type: string description: PDF 文件路径 required: true entrypoint: scripts/convert.py output_format: markdown ---这里有几个字段需要注意。entrypoint指明实际执行的脚本路径它可以是 Python、Node.js 或 bash 脚本trigger是自然语言描述触发条件superpowers 会把它转换成路由规则。parameters定义了技能接收的输入参数结构化之后的好处是调用时可以精确传参。4.3 注册、测试、热加载让技能真正生效SKILL.md 写好后把整个目录放到~/.superpowers/skills/下然后执行注册sp register ./my-pdf-note注册之后先用sp test my-pdf-note --input /path/to/test.pdf做一次快速验证。如果输出不对是脚本的问题如果技能没被触发大概率是 trigger 字段写得太模糊。superpowers 支持热加载也就是说改了 SKILL.md 或脚本之后不需要重启服务下次触发时就会用最新版本。这个功能很好用但也容易踩坑——有些时候你以为改的是当前版本的技能实际上由于缓存跑的还是旧逻辑。遇到这种情况执行一下sp clear-cache就行。5. 具体使用拆解抓取一个网页并生成结构化摘要前面讲了很多概念和配置这一章我完整走一遍web-summarizer的使用过程让你看清楚技能从触发到输出到底经历了什么。5.1 场景描述与技能触发我拿了一个真实的场景抓取一篇三千字左右的技术博客生成摘要。操作很简单在 superpowers 的交互界面输入请用 web-summarizer 分析这个页面https://example.com/tech-blog这条指令会触发两件事。先是解析器识别出链接然后路由匹配到web-summarizer技能。如果你没有明确指定技能名它也会根据trigger字段自动匹配。实测下来大多数情况下它都能猜对但比较冷门的需求还是建议把技能名带上减少误触发的风险。5.2 实际运行过程与输出技能运行的时候会经历几个阶段拉取页面、去噪提取正文、按维度生成摘要、格式化输出。你可以通过sp run --verbose看到每个阶段的详细日志方便定位是哪个环节出的问题。最终输出结构大致是这样## 核心观点 - 文章认为 X 技术将在未来 12 个月内显著影响前端工程化方向 ## 关键数据 - 作者引用了 2024 年的一项调研80% 的受访团队已开始试点相关工具 ## 行动建议 - 建议从低风险项目开始试点周期控制在两周以内对比我自己手动阅读原文章花的时间这个技能五分钟内给出的摘要基本覆盖了我想知道的东西省掉了刷开页面后还要快速扫读的过程。5.3 效果对比手工操作 vs superpowers手工操作通常是打开浏览器 → 等待渲染 → 扫视标题 → 跳段阅读 → 打开笔记工具 → 复制关键句 → 整理成文。一套流程搞下来至少有七八步十分钟跑不掉而且中途很容易被其他事情打断。用 superpowers 之后一步到位剩下的时间用来看摘要本身。这两种工作方式的差别用从手动挡换成自动挡来形容一点也不夸张。当然摘要的准确率取决于网页结构和模型质量遇到反爬严格的站点还是会失败所以执行前最好确认目标页面可以被正常访问。5.4 技能输出如何对接下游我曾经以为摘要生成完就算结束了但后来发现它还可以和别的技能串联使用。比如把摘要结果直接传给file-organizer让它自动归档到指定目录或者传给code-reviewer如果你抓取的是技术方案文档。这种技能链的使用方式才是 superpowers 比较有想象力的地方——单个技能提升效率技能串联则能构建出一套个人自动化流水线。6. 实战中的坑与调优建议写到这我把自己在实际使用中遇到的几个典型问题集中说一下。很多问题不看日志想破头也想不到原因这里给你省点时间。6.1 目录权限与路径问题superpowers 的技能脚本默认会在你的用户目录下运行但如果你给它传了一个没有读权限的路径报错会很隐晦有时会显示成文件不存在。我一度以为是技能本身的问题排查到最后发现是权限。遇到类似问题先确认执行路径的权限再考虑其他可能。另外如果 Windows WSL 的环境路径分隔符建议用相对路径或者统一转换为 WSL 内的绝对路径。Windows 风格的C:\路径在 bash 脚本里容易出问题。6.2 技能冲突与优先级技能装多了之后会出现同名冲突或者触发条件重叠的情况。比如我装了>