其实最开始我对“给AI装技能”这件事是有点不屑的。我日常用的是Claude这类编码助手平时写代码、改Bug、做Code Review都已经很顺手为什么要额外折腾一套叫Superpowers的东西直到有段时间我连续被低效交互折磨每次开新会话都要重新交代一遍项目背景、编码规范、测试命令让它去查个官方文档它要么凭记忆瞎编要么告诉我没法访问外部网页明明上个月刚写好的自动化脚本这个月换个项目目录就完全想不起来。这种“每次从零开始”的感觉让我意识到问题不在AI的能力而在于我没有给它一套可复用的“工作记忆”。Superpowers解决的正是在于把那些高频使用的技能、流程和工作流固化成AI随时可以调用的模块一次安装、到处复用。这篇文章会把我的完整实操记录下来装前准备、核心概念、开箱技能盘点、一个Skill从创建到调用的全流程以及我踩过的几个真实坑。适合所有用AI辅助开发、但已经厌倦反复重复提示词的开发者。1. 先从“为什么需要给AI装技能”说起1.1 AI助手不是能力不够而是“记忆”太差我在团队里做过一个实验让Claude分别在新会话和旧会话里完成同一个任务——写一个带分页和搜索过滤的Python接口。旧会话里它记得我们约定好的项目结构、命名规范、错误处理方式写得又快又准新会话里它虽然也能写但总会问一堆基础问题甚至默认用上了跟现有代码风格完全不搭的写法。这个差异说明AI的核心瓶颈往往不是模型本身而是上下文和流程的可复用性。Superpowers这一类“技能框架”解决的问题就是把这个“可复用性”从会话中抽出来变成一个一个放在磁盘上的技能包。每个技能包含清晰的触发条件、依赖工具、执行步骤AI识别到对应场景后可以直接加载并执行。你不需要再把半页纸的Prompt复制粘贴进去只要告诉它“用某某技能处理”就行。1.2 Superpowers的核心思路把技能变成文件如果只记一句话那就是Superpowers把技能变成文件把工作流变成目录结构。它的安装和使用逻辑跟给编辑器装插件很像。你在自己的用户目录或项目目录下建好技能文件夹里面放一个Markdown形式的技能说明书再加上若干可供AI调用的脚本或工具剩下的事全部交给框架和AI来协调。这带来一个意外的好处技能可以跟着项目走也可以跟着人走。我自己的习惯是把通用的技能放在全局目录把跟具体项目强相关的技能放在项目根目录的.superpowers文件夹里项目成员拉下来代码之后技能也跟着一起复制过去了。1.3 它跟一份普通Prompt到底差在哪很多人会觉得“那我不就是把Prompt存成文件嘛有什么区别”区别大了。普通的Prompt是“一次性输入”而一个结构良好的Skill包含的是四个层次的内容触发场景明确说明这个技能在什么情况下应该被自动启动在什么情况下应该拒绝执行。前置条件列出执行前需要具备的环境、工具、依赖AI会主动检测。执行步骤把任务拆成可验证的中间步骤每一步都有产出和检查点。脚本与工具技能可以直接调用预设的Shell脚本、Python脚本而不只是生成文本。底层逻辑是Prompt是给AI看的“建议”Skill是给AI看的“作业指导书加工具箱”。所以同样一个“写单元测试”的需求用Prompt让它写它可能自由发挥用技能让它写它会先检查测试框架是否安装、再按项目的测试规范生成、最后自己跑一遍测试并汇报结果。2. 安装前的准备环境、版本与网络条件2.1 环境要求与版本检查Superpowers依赖Node.js运行时和对应的AI编程助手CLI工具。安装前建议先检查自己的基础环境避免装到一半才发现版本不对。我现在用的组合是Node.js 20.x Claude CodeBash环境这个组合下所有功能都能正常跑。打开终端先敲两行命令确认环境状态node -v # v20.11.0如果低于18建议先升级 npm -v # 10.2.4然后确认你的AI编程助手CLI已经登录并能正常对话。不同AI工具的命令略有差别但思路一样先让CLI能跑起来再谈装技能框架。我在macOS的终端里操作Windows的PowerShell用户需要注意后面会提到的路径差异。2.2 安装命令与网络注意事项确认环境无误后安装过程本身非常快。不同版本的Superpowers安装命令略有不同我这边用的方式是通过npm全局安装启动器npm install -g superpowers-cli装完之后在AI编程助手内部再执行初始化命令让它自动创建技能目录和默认技能包superpowers init这里有一个非常关键的网络问题。npm源、CLI下载依赖包、以及AI工具访问外部文档都需要一个相对稳定的网络环境。有些同学会在这里卡很久表现为npm install转几圈就超时或者init之后技能老是下载不完整。处理方法有两个方向一是把npm源切到国内镜像npm config set registry https://registry.npmmirror.com二是给AI工具配置好系统代理。我不展开讲代理细节只想说一句如果init阶段频繁失败大概率不是工具问题而是依赖下载被中断换一个网络环境再试往往就通了。2.3 装好后先跑一次验证安装完成后别急着写技能先跑一遍自带的健康检查。Superpowers一般会提供技能列表命令你可以在AI对话窗口里输入类似这样的指令显示所有已安装技能正常的话你会看到一组默认技能比如我这边默认就带着Web搜索、代码审查、Git工作流这几个基础包。如果列表是空的或者提示找不到技能目录那就需要检查一下初始化路径是否正确——这个坑我后面专门讲。验证还有一招直接让AI“用Web搜索技能查一下某个框架的最新版本”。如果它能正确调起技能、访问页面并返回带引用的结论说明整条链路已经通了。3. 核心概念Skill、Command和Agent的关系3.1 三种对象的定位差异刚开始接触Superpowers的人容易被三个概念绕晕Skill、Command和Agent。我花了不少时间才把它们彻底分清楚这里直接给出我的理解Command最简单的一类相当于一个“快捷指令”。它是一段预设好的PromptAI看到 命令名 就会按预填内容执行。适合固定话术比如“帮我把代码格式化成项目规范”。Skill可执行的工作流单元。除了Prompt还包含前置条件、环境依赖、可调用脚本它会有真正的“操作”比如读写文件、运行测试、搜索互联网。Agent由多个Skill组合成的角色化执行体。它更像一个虚拟成员比如“负责做技术调研的Agent”内部串联了搜索、阅读文档、写摘要、给建议等多个技能。日常开发中用到最多的还是Skill。Command适合一次性固定输入Agent适合复杂的多阶段任务而Skill是中间那个“既有弹性又能落地”的层面所以我的实践建议是优先从Skill入手等积累够了再组装自己的Agent。3.2 一个标准Skill的目录与文件组织每个Skill本质上是磁盘上的一个文件夹标准结构长这样my-skill/ ├── SKILL.md # 技能说明书AI首先读取这个文件 ├── scripts/ # 可执行脚本会被AI调用 │ └── check-env.sh └── assets/ # 附带资源比如模板、配置样例我最常忽略的是SKILL.md的命名。它必须全大写且精确为SKILL.md写成skill.md或Skill.md都可能让AI识别不到。这是一个非常容易踩的细节我有个同事把文件名写成小写排查了半天才发现问题出在这里。3.3 SKILL.md的frontmatter与正文写作SKILL.md是技能的灵魂。它的开头是一段YAML格式的元信息也就是frontmatter我通常会这样写--- name: web_search version: 1.0.0 description: 搜索指定关键词并返回带来源的摘要结果用于技术调研和资料核实。 triggers: - 搜索 - 查一下 - 找出最新资料 - find the latest allowed_tools: - shell - python ---triggers很关键。AI会拿用户输入跟这里的词条做匹配命中后优先加载这个技能。你写得不全就会出现“明明装了技能AI却完全没用它”的情况。我后期把所有自定义技能的triggers都重新过了一遍每个至少配了5个不同表达。正文部分我建议用清晰的步骤结构。AI读Markdown的效率很高按顺序列出步骤它基本能忠实执行。一个常见教训是不要在正文里写太多模棱两可的形容词比如“合理”“高质量”而要写可验证的标准比如“测试覆盖率不低于80%”“输出必须包含引用链接”。AI对量化目标的执行力远比对模糊目标的执行力强得多。4. 开箱即用的Skills盘点与应用场景4.1 我把技能分成四个门类安装Superpowers并初始化之后系统会自带一批技能。不同版本的默认包有差异但大体上会覆盖我常用到的几个方面。我个人习惯于把技能分成四个门类方便按场景取用门类代表技能典型场景信息获取类Web搜索、文档读取、PDF摘录查官方文档、调研竞品版本、读论文代码质量类Code Review、单元测试生成、重构建议提交代码前自动审查、补测试流程自动化类Git工作流、项目脚手架、README生成规范提交信息、快速生成项目模板领域特定类数据库Schema分析、日志排查、性能基线检查慢SQL定位、线上日志分析这个分类不是官方分类是我自己用着方便做的“知识管理”。你完全可以按项目需要调整重点在于知道默认技能池里有哪些货别临到用时才发现“原来它还能干这个”。4.2 高频技能详解我用得最多的几个技能值得单独拿出来说说。Web搜索这是解决“AI瞎编”的利器。过去让Claude回答“某个库最新版本是多少”它可能凭训练数据猜一个而现在它会先调起Web搜索技能打开搜索结果页面再返回带参考来源的答案。我实测过精度提升非常明显至少不会再把两年前的老版本当成最新版了。代码审查执行技能后AI会读取目标代码文件先检查语法和风格问题再做逻辑层面的潜在Bug分析最后会核对项目既有的测试覆盖情况。最妙的是它会输出一份“严重级别排序”的审查报告把高危问题列在最前面。我把这个技能接入到了提交前检查流程配合Githook一起使用效果很稳定。Git工作流这个技能解决的是“规范提交信息”的问题。它会先跑git diff和git status查看变更内容再结合项目约定的提交信息规范生成符合格式的commit message。我不用再费劲想动词前缀也不用担心风格不统一。项目脚手架输入一个项目描述技能会自动创建目录结构、生成初始代码文件、配置依赖清单甚至安装依赖并启动开发服务器。我最近用它搭了三个内部工具的前端项目整个过程从半小时缩短到五分钟。4.3 按场景选技能的搭配建议单个技能好理解但真正提升效率的是“技能组合拳”。我自己会按项目阶段做搭配新建项目项目脚手架 Git工作流 README生成。日常开发Web搜索 代码审查 单元测试生成。排查线上问题日志排查 数据库Schema分析 性能基线检查。提交发布前代码审查 Git工作流 变更日志生成。当你发现自己把多个技能轮流调用时就可以考虑定制一个组合Agent了。这个进阶玩法等你自己跑顺手之后再去尝试初期不建议一上来就搞复杂的Agent编排。5. 实操让一个Skill从安装到调用走完整链路5.1 第一步看板与技能列表先学会“看货”。在AI对话窗口里直接输入查看技能列表的指令每次我拿到新环境第一件事就是先看默认技能池。界面会返回一个带说明的技能清单每个技能的名称、描述、触发方式一目了然。看到某个技能想要试用不需要额外安装直接在对话里给出触发词即可。比如技能描述里写了“搜索”你就正常说“用搜索技能查一下Vite的最新版本”AI会自动匹配并执行。整个过程不需要背命令自然语言就是调用接口。5.2 第二步写一个属于自己的Skill看懂结构之后真正好玩的开始——自己写一个。我建议从解决自己最痛的场景入手。我写的第一个自定义技能是“生成周报”因为每周写周报实在太烦了。先在项目的.superpowers/skills目录下新建一个weekly-report文件夹然后创建SKILL.md--- name: weekly_report description: 根据本周的Git提交记录和TODO清单生成一份结构化周报。 triggers: - 周报 - weekly report - 总结本周工作 --- # 步骤 1. 运行 git log --since7 days ago --prettyformat:%h %s (%an) 获取本周提交记录。 2. 检查项目根目录是否存在 TODO.md如有则读取未完成项。 3. 按照本周完成 / 本周进展 / 下周计划 / 风险与阻塞四个部分组织内容。 4. 输出时保留具体数据提交次数、解决的问题、模块名称不要写泛泛而谈的套话。第一版跑起来之后我发现它有个问题只会拿git log的数据但很多工作是不体现在commit里的比如开会、评审、排查问题。于是我在第二步又加了一个输入参数让它允许我补充非代码类的工作内容。迭代后的技能明显更实用了。5.3 第三步在对话里调用并验收效果写完之后不用重启任何东西直接在对话里说“生成这周的周报”。AI会自动匹配到weekly_report技能然后按步骤执行。当时它跑出来的周报让我很惊喜不仅准确提取了commit信息还把“升级了构建脚本来减少三分之一的打包耗时”这种我早就忘记的细节重新挖掘出来了。验收技能有一个笨办法故意给一个不完整的需求看它是否会主动走前置检查。比如我会说“帮我生成昨天到今天的周报”正常应有技能启动并指出可用数据范围有限会给出建议比如扩大时间范围。如果它什么都没做就直接编内容说明技能的约束没有生效需要回头检查SKILL.md里的步骤描述是否足够具体。5.4 第四步迭代与版本管理技能不是一次写好的我自己每个技能平均改了三遍。建议把技能目录纳入Git版本管理改动之后提交方便回滚。对技能做版本更新时注意同步更新SKILL.md里的version字段这样即时多人在同一台机器上操作也知道当前跑的是哪个版本。我一度偷懒省略了这一步结果后来出了个诡异问题——同一份技能我本地跑的结果和同事跑的结果完全不同。最后发现是我改了SKILL.md但没更新版本号我这边已经是v2逻辑同事缓存里还是v1的步骤。从那以后我更新技能的固定动作就是改内容 改版本号 提交Git。6. 排错实录与避坑经验6.1 安装在用户目录却在项目里找不到技能这是我第一次安装时遇到的第一个坑。superpowers init默认把全局技能装到了~/.superpowers目录而我的项目自己在本地建了一个.superpowers文件夹两边内容不一致导致项目里能看到一部分技能、又缺失一部分技能特困惑。后来我才想明白Superpowers在读取技能时是有优先级的项目目录的.superpowers高于用户级目录的~/.superpowers。同名技能会以项目目录为准。这个机制本身合理但它意味着你在全局更新了技能项目里如果存在同名文件跑的还是旧版本。我的建议是做一个明确约定——全局目录放通用技能项目目录放项目专属技能同名覆盖要有意识不要靠巧合。6.2 Skill一直不生效问题出在缓存有一次我改了一个技能的前置条件明明文件改对了但每次让它执行还是走旧逻辑。一开始怀疑是文件名问题检查了路径也对最后才想到缓存。Superpowers为了提升加载速度会有技能索引缓存修改SKILL.md后不一定会立刻重建索引。解决方法很简单两步先看有没有类似的刷新命令不同版本叫法不同常见是/skills refresh如果没有就重启AI会话。我当时重启会话立即就好了。后来问了下群里的朋友他们也遇到过这个情况甚至有人把一级缓存和二级缓存都列出来了大意是“改了技能就下意识刷新别浪费十分钟在这上面”。现在我已经把“刷新技能索引”变成了肌肉记忆。6.3 权限、路径与Node版本带来的连锁问题如果技能内部要调用Shell脚本记得检查执行权限。我写过一个技能每次运行都报“Permission denied”明明手动执行脚本没问题。排查后发现是文件没有chmod x权限位AI调起脚本时以独立进程运行不继承我终端会话的便利条件权限检查比人严格。还有一个很容易踩的是路径问题。技能脚本里的相对路径是相对当前工作目录而不是相对SKILL.md所在目录。这意味着同一个技能在项目根目录运行和在子目录运行表现可能完全不同。解决方法是涉及文件读写的地方一律用绝对路径或基于项目根目录的路径不要偷懒写相对路径。Node版本的问题则更隐蔽。我之前在Node 18环境跑得正常升级到Node 22之后某个技能开始报“ERR_STREAM_WRITE_AFTER_END”排查发现是技能内嵌的一个依赖包用了旧版本的stream API。你不需要太理解底层细节记住一件事就行当技能突然不工作而且更新缓存也无效检查Node版本是否被动更新了。6.4 关于安全和边界的一点提醒技能框架给了AI调用Shell、读写文件、访问网络的能力这个能力是一把双刃剑。我强烈建议你在使用第三方Skill时先通读一下对方的SKILL.md和里面脚本代码尤其是脚本部分。注意看几点脚本是否会往外部服务器发送数据是否包含可疑的下载加执行链是否有超出描述范围的敏感操作我的安全底线是自己写的技能也不给最高权限。比如我不会在技能里写入rm -rf类的命令即使是在清理目录也会先列出来确认。AI对命令的理解是字面量的它不知道“这个目录真的很重要”在技能出错时一个有保护意识的脚本能避免很多灾难。我在实践中的最大体会是Superpowers这类工具真正的价值不是“装了就变强”而是逼着你把工作方式想清楚。每写一个技能都需要把隐性经验显性化这个任务到底有哪些前置条件执行步骤能不能拆成机器可理解的指令质量标准怎么量化这套思考过程本身就是一种效率提升。等你积累了十几个自己的技能再回头看那些“每次都从零开始”的日子你会发现自己的AI助手终于有点像资深员工的干活方式了。