superpowers 这个单词在软件开发圈子里有两层意思一层是心理学里的“心流状态”另一层是这两年冒出来的 VS Code 技能插件。我这里要聊的是后者。先说结论它是一套能把 AI 编程助手从“聊天机器人”变成“能动手干活的小弟”的技能插件核心卖点就是让模型读你本地的技能文件自己决定什么时候调用终端、怎么写文件、怎么查 git 状态。我用了大概三周后就彻底离不开了因为以前要手打的复制粘贴、跑脚本、查日志这些琐事现在一句话就有 AI 帮我去做而且做成了一套可以复用的技能库。这篇文章我会把 superpowers 常见的 skills、引入方式和完整使用流程都拆开来讲适合刚接触 AI 编程辅助工具的人也适合已经用了一阵子、但觉得 AI 总在“嘴上跑火车”的使用者。1. 整体设计与思路拆解1.1 核心需求解析搜索“superpowers”的人往往已经在一款 AI 编程工具里见过它的名字但不知道它到底能带来什么。从热词看最集中的疑问是“有哪些 skills”“怎么引入这些技能”“想要安装 superpowers”。这说明需求分了明显三层第一层是认知需求想知道这个插件值不值得装第二层是安装配置需求想知道装完之后怎么挂到自己的环境里第三层是使用需求想知道技能触发逻辑让 AI 真的按自己的意图执行操作。我当初也是从这三个疑问开始折腾的这篇就按这个顺序把三个问题讲清楚。说白了你在没有 superpowers 的时候和 AI 协作基本是“你下指令AI 给方案”的模式。它告诉你该跑什么命令但还是得你自己去终端里敲它告诉你该改哪个文件还是得你自己打开编辑器改。这种对话式协作最大的问题就是“动嘴不动手”而 superpowers 恰恰补上了“动手”这层模型可以直接调用你本地的工具链去完成操作再回来汇报结果。理解了这个需求你自然就能明白围绕着它的所有疑问本质上都在问同一件事怎么让 AI 在我的电脑上真正干活。1.2 设计思路与方案选型superpowers 的设计核心不是给你一堆现成的按钮而是提供一套“技能文件”的规范。每个技能就是一个文件夹里面有一个 SKILL.md用来描述这个技能是干什么的、什么时候调用、需要什么参数。AI 编程助手在对话过程中读到用户需求后会先从本地的技能库里搜索匹配的描述找到之后读取对应的 SKILL.md然后按里面的指令执行。这和传统的提示词工程相比最大的优势是可复用提示词写一次就丢在聊天记录里技能文件却可以长期保存在磁盘上甚至可以放进 Git 仓库跟着项目走。比起 MCP 服务它又轻量得多不需要起额外的服务进程就是一个文件约定。这其实是刻意把复杂度放在文件结构上做文章。目录一摊开全局技能放~/.superpowers项目技能放项目根目录的.superpowers两边互不污染优先级也清楚。项目级技能可以让团队每个人都共享同一套操作约定全局技能则放你个人习惯的工具链。实测下来把技能定义成 Markdown 外加可选的可执行脚本比传统的插件 API 要友好很多你不用学插件的内部接口只要会写 Markdown 和 shell 脚本就能自定义一个新技能。举个例子如果团队里经常要初始化一个新前端组件传统做法是每个人手打一遍模板或者装脚手架。用 superpowers 的思路只需要在项目.superpowers下建一个create-component技能SKILL.md 里写明“当用户要求创建组件时按模板生成文件并写入 src/components”描述里带上一句“user wants to create a component”AI 每次看到类似需求就会触发它。这就是技能引入的实际价值把重复劳动沉淀为团队规范而不是每次重新描述。同时要注意一个容易被忽视的点技能不是万能的。它本质上依赖大模型的理解能力触发判断靠的是描述文本与用户需求的语义匹配所以描述写得越贴近真实业务场景触发就越准。你写“创建组件”四个字作为描述和写“当用户希望新建一个 Vue 单文件组件包含 template、script、style 三个区块”的效果完全不同后者能让模型在模糊需求下也能准确命中。这部分我会在实操章节里用一个完整例子展开讲。2. 核心细节解析与实操要点2.1 安装与引入方式安装 superpowers 有两条路线看你习惯哪种。路线 AVS Code 扩展市场安装。直接在扩展面板里搜 “superpowers”认准官方图标点安装即可不需要额外配置。装完之后扩展会自动在用户目录下创建~/.superpowers目录里面预置了一批常见技能。这个方法对新手最友好不用手动管理文件。路线 BGit 仓库克隆。如果你已经有自己的 dotfiles 管理方案比如用 chezmoi 或者直接 symlink克隆官方仓库到~/.superpowers然后手动拉取更新也可以。好处是技能库的版本可以自己控制坏处是官方仓库更新时你需要自己 merge。我建议刚开始折腾的人先用路线 A等真正理解了目录结构再换路线 B。装完之后的重头戏是“引入”也就是让 AI 编程助手知道去哪里找这些技能。不同的助手配置位置不一样以目前主流的 AI 编程插件为例通常是在设置里配置技能目录路径填入~/.superpowers再加上项目里的.superpowers。这里的细节是路径分隔符和尾部斜杠一定要写对很多人栽在 Windows 上反斜杠和正斜杠混用。你在配置里统一用正斜杠全平台兼容。配置完成后重启 VS Code 窗口让配置重新加载。然后随便打开一个项目在对话里输入一句跟某个技能相关的需求比如“检查一下项目有没有过期依赖”如果 AI 回了一句类似“我将使用 npm-check-updates 技能”并开始执行说明技能引入成功。如果它只是泛泛而谈没有实际调用技能多半是技能目录没被读到或者描述文本匹配不上。2.2 有哪些核心 skills 与触发场景预置技能我梳理了一下大概分四类项目管理、代码操作、流程辅助、信息检索。npm-check-updates扫描 package.json找出过期依赖并生成升级建议。触发描述一般包含 “check dependencies”“upgrade packages” 这样的关键词。git-status查看当前分支、未提交改动、冲突文件列表。触发词是 “git status”“看看改了什么”。git-diff展示某个文件或整个工作区的差异详情。和 git-status 配合使用先看状态后看 diff。terminal在 AI 助手所在环境里执行任意 shell 命令本质上是个安全阀允许模型调用底层终端。这个技能使用频率很高我会在常见问题里特别提醒权限风险。write-file、create-dir写文件和创建目录通常被别的技能间接调用不需要你主动触发。search-web联网搜索资料适合需要查文档、查 API 用法的场景。brainstorm头脑风暴式需求拆解AI 会先列出候选方案再和你确认适合需求还比较模糊的阶段。next-actions分析当前任务上下文生成下一步操作清单适合任务做到一半被打断的情况。verify按预置的验证流程检查产出是否合格比如确认文件是否生成、依赖是否安装成功。start项目初始化一键完成依赖安装、环境检查和基础配置。我把常用技能整理成一张表方便你对照自己的需求选技能名核心用途典型触发描述npm-check-updates检查过期依赖并生成升级建议“check dependencies”“看看依赖要不要升”git-status查看分支与工作区状态“git status”“当前改了什么”git-diff查看具体改动内容“打开 diff 看看”“这两个文件有什么区别”terminal执行 shell 命令“跑一下 npm run build”“执行 node -v”write-file写入文件内容“把这个文件保存为 x”“更新 README”create-dir创建目录结构“新建 src/views 目录”search-web联网搜索信息“查一下 XX 的最新文档”brainstorm需求拆解与方案设计“帮我理一下这个需求”next-actions生成下一步操作清单“接下来该做什么”verify验证产出是否符合预期“帮我确认文件都生成对了吗”start初始化项目环境“一键初始化项目环境”触发逻辑是核心。AI 每轮对话都会先拿你的输入去匹配技能描述匹配度够高就会点开那个技能的 SKILL.md按里面的步骤走。所以技能描述里的触发词写得越符合日常口语模型越容易命中。比如你写“when the user asks for checking outdated npm packages”和“when user says ‘依赖要升一下’”后者的口语化描述在实战中触发率更高因为真实用户不会用标准英文句式说话。这是我在调技能描述时反复试出来的经验。2.3 技能文件的结构与调用机制剥开一个技能目录核心文件只有两个SKILL.md和可选的技能脚本。SKILL.md 里用 YAML frontmatter 写元信息主要包括 name技能名、description给模型看的触发指引正文部分写具体的操作步骤、注意事项、依赖要求。模型读取文件后把步骤当成交付清单逐一执行。可选的技能脚本一般用 Node.js 或 shell 写负责真正干活比如更新 package.json、跑测试命令、调用外部 API。SKILL.md 里会写明什么时候运行哪个脚本以及怎么把用户需求转成脚本参数。这个设计跟函数调用很像SKILL.md 是函数的注释文档脚本是函数体描述文本是函数签名。理解了这个类比你就知道为什么技能可以组合一个技能执行完可以在 SKILL.md 里写明“完成后调用 verify 技能检查结果”这样就形成了一条完整的调用链。3. 实操过程与核心环节实现3.1 从安装到第一次调用我这里以一个真实项目为例完整走一遍流程。假设我在做一个 Node.js 服务想用 superpowers 来完成一次“依赖检查 升级”的操作。第一步确认运行环境。superpowers 的预置脚本大多依赖 Node.js 和 npm所以先跑node -v和npm -v确保版本在 16 以上。第二步在 VS Code 扩展面板搜索 superpowers 并安装重启窗口。第三步打开项目按 CtrlShiftP 打开命令面板输入 Superpowers 相关的命令比如 Show Skills确认技能目录是否正确加载。如果目录里能看到 npm-check-updates 这个技能说明加载没问题。第四步在 AI 助手对话面板里输入“检查一下项目依赖是不是都过时了把需要升级的列出来。”然后观察 AI 的行为。如果它说“正在使用 npm-check-updates 技能”并调用 terminal 跑了一个脚本像npm outdated或者自定义的检查命令那就是正常触发。我实测下来这个技能第一个跑出来的就是 package.json 的依赖对比表接着会给你升级建议甚至会直接改 package.json 并执行 npm install全程不需要你碰终端。这里要插一句第一次跑的时候AI 可能会问你“是否允许终端执行命令”这是助手的安全机制。我建议你自己评估一下项目的信任程度本地开发项目一般直接允许涉及生产环境或需要特殊权限的操作要谨慎。这个选择说白了就是你自己对终端权限的把握没有人能替你决定但技术层面没有任何问题路径和权限都配好就能跑。等首次执行成功之后你可以留意一下技能的调用速度。我试过在一个几百个依赖的项目里跑依赖检查整个过程大约十几秒大部分时间花在 npm registry 的响应上AI 本体的判断和文件操作几乎是瞬间完成。这种体感差异非常重要它会改变你写代码的节奏以前你切窗口、开终端、敲命令、等结果一套操作下来小一分钟现在直接一句话让 AI 去跑你继续看代码就行。3.2 自定义新技能从设计到落地看完默认技能我猜你已经想自己做点东西了。这里我给一个自定义技能的标准流程以“创建 Vue 单文件组件”为例。第一步建目录。在项目根目录下创建.superpowers/create-vue-component文件夹。注意文件夹名就是技能名用连字符分隔不要有空格。第二步写 SKILL.md内容结构如下--- name: create-vue-component description: Use this skill when the user wants to create a new Vue single file component. The user might say new component, 创建组件, or 帮我新建一个 Vue 组件. when to use: User asks to create a Vue component --- ## Steps 1. Determine the component name from the users request. If not specified, ask for it. 2. Convert the component name to PascalCase. 3. Create the component file at src/components/ComponentName.vue. 4. Write the SFC template with template, script setup, style scoped blocks. 5. If a .superpowers/components/$NAME.js file exists, use it to extend the template. 6. Confirm the file was created by listing the output. ## Notes - Always use script setup syntax. - Keep the style block scoped. - If the project uses TypeScript, add langts to the script tag.第三步写可选脚本。上面第五步里提到的组件扩展点是很有用的机制比如根据项目类型扩展不同的模板片段。你可以写一个简单脚本读用户输入的组件名把它替换进模板。这一步不是必须的但对复杂需求很有用能让技能输出更贴合项目实际。我自己就把常用的按钮、表单、弹窗三套模板写进了扩展脚本里AI 生成新组件时直接按项目风格走。第四步测试。回到对话面板输入“帮我创建一个用户登录组件”看看 AI 是否读取了技能文件并按步骤生成文件。我实测时发现描述文本里那一串“new component / 创建组件 / 帮我新建一个 Vue 组件”的示例非常关键相当于给模型下了锚点模糊需求也能命中的概率大幅上升。这个技巧想要极端一点可以把触发词写得更生活化比如“把项目经理说的那个页面做出来”但这样容易误伤建议还是稳一点围绕组件相关的说法来写。3.3 执行流程与参数设计细节自定义技能时最容易被忽略的是执行流程的参数传递。上一个例子里的组件名、TypeScript 开关、样式前缀这些都是参数。设计原则是痛点参数放 SKILL.md 中让 AI 推理操作参数放脚本里用环境变量或命令行参数传入。比如组件名你让 AI 从用户对话里提取存成环境变量COMPONENT_NAME而是否用 TypeScript则让 AI 看项目里有没有 tsconfig.json 自己判断不需要跟用户确认。这样技能既灵活又不用每次问来问去。我建议你参考一个执行模型描述匹配 - 读取 SKILL.md - 解析用户请求填充参数 - 运行脚本 - 根据脚本输出决定下一步。整个链路里模型是决策者脚本是执行者SKILL.md 是两者之间的协议。把协议写清楚技能就稳定协议写含糊模型就开始自由发挥输出质量急剧下降。这是我调了二十多个技能之后最深的感受。再补充一个关于日志输出的细节。技能脚本通常会在终端里打出不少内容但模型上下文窗口是有限的几百行日志往那一塞后面对话质量直线下降。我习惯在脚本末尾加一行汇总输出比如“已创建文件 src/components/UserLogin.vue共 3 个区块”然后让 SKILL.md 里写明“只参考汇总信息不要读完整日志”。这种约定看着不起眼但对长时间会话的稳定性帮助极大。4. 常见问题与排查技巧实录4.1 技能没生效的排查顺序我遇到的第一个坑是技能目录加载不出来。装完扩展、也配置了路径AI 就是不调用技能。排查顺序我给你一条线先看 VS Code 扩展日志里有没有报错确认技能目录路径权限是否正确再确认 AI 助手配置里技能目录路径的写法是不是绝对路径然后检查 SKILL.md 首行的---分隔符是不是丢了YAML frontmatter 格式错了模型根本读不到元信息最后再检查描述文本看触发词和用户输入是不是完全搭不上边。大部分问题都集中在这四个环节。我把典型问题整理成一张速查表方便你以后对着排查问题现象可能原因解决办法AI 完全不提调用技能技能目录路径没配置或配置错误确认绝对路径重新加载窗口技能偶尔触发、经常不触发描述文本写得过于书面化在描述里加入口语化触发词示例技能读到了但执行报错脚本依赖缺失或 Node 版本过低检查脚本 require 的包是否安装升级 NodeSKILL.md 读取乱码Windows 路径分隔符问题统一使用正斜杠避免反斜杠混用脚本没有执行权限文件权限位不正确chmod x 技能脚本Linux/macOS技能间互相覆盖项目级技能名与全局技能名冲突项目技能用项目前缀命名如 company-create-component还有一个坑是技能目录的大小写。比如你把文件夹命名成了Create-Vue-Component而 SKILL.md 里的 name 写的是create-vue-component某些环境会把它们当成两个不同的技能结果就是描述匹配到了但文件路径对不上。我后来统一约定目录名、SKILL.md 的 name 字段、文件名里的技能名三者完全一致全部小写加连字符避免任何潜在的大小写差异。这个约定看着苛刻但能省掉大量莫名其妙的排障时间。4.2 实战避坑技巧最后分享几个真实踩过的坑算不上多深但每个都影响过我的使用效率。第一SKILL.md 里头不要放花哨的复杂格式。我试过在文件里画 ASCII 流程图、放超长表格模型的解析稳定性会下降尤其是表格多列时经常乱读。后来我把步骤全部改成一、二、三的简单列表触发率立刻稳定很多。记住这个文件是给模型看的协议不是给人看的文档越简单越好。如果你确实有复杂的决策逻辑要表达宁可拆成多个技能也不要硬塞进一个 SKILL.md。第二技能脚本要写得幂等。也就是说不管跑多少次结果都应该一样。比如创建目录前先判断是否已存在写文件前先备份或确认覆盖。AI 在对话中可能反复调用同一个技能如果脚本每次都把文件重新生成一遍很容易覆盖你手改的内容。这个细节在 write-file、create-dir 这类高频技能里尤其重要我见过有人一个技能跑了三次把三份不同的代码轮流覆盖了一遍场面相当混乱。第三上下文窗口不是无穷的。技能描述、脚本内容、终端输出都会占用模型上下文。如果技能一上来就把几百行日志塞给模型它很快会被无关信息淹没后续对话质量直线下降。我通常会在脚本里做一层输出裁剪只保留关键结果比如“更新了 3 个依赖升级后版本为 x.y.z”而不是把整个 npm install 的日志原样打出来。这就像跟同事汇报工作一样说重点就够没有人想听你终端里滚过的每一行。第四不要把什么都交给 terminal 技能。它虽然是 superpowers 里最强大的一个也最容易出事故。要么在技能文件里预先定义好允许执行的命令白名单要么在环境配置里禁用某些高风险命令。毕竟 AI 只是按描述执行它没有你那种对生产环境的敬畏心该加的保险还是得加。我自己的方案是高危操作单独放在一个 called-after-approval 技能里SKILL.md 明确写着“执行前必须向用户再次确认”等于多了一道人工审核闸门。踩过几次坑之后我现在新项目的套路已经固定装扩展、配技能目录、把常用脚本一个个转成技能文件剩下的事情就交给 AI 去循环执行。这个收益是滚雪球式的技能越多重复劳动越少。想入门的朋友不用一口吃个胖子先挑依赖检查和 git 状态查看这两个高频技能跑起来用顺了再往组件生成、提交规范这些方向扩展。等你发现某件事已经第三次重复做了那就是该给它建一个技能的时候了。