1. “Superpowers”不是魔法是开发者工具链的智能增强层最近在技术社区里“superpowers”这个词出现频率高得有点反常——它既不像传统框架那样有明确文档也不像编程语言那样自带语法体系。我第一次看到是在 Cursor 的插件市场里一个叫Superpowers的扩展图标旁边写着“AI-powered coding assistant”点进去发现它其实是一套预置技能组合包不是独立软件而是运行在 Cursor、VS Code 或 Codex CLI 这类编辑器之上的能力调度中心。这和很多人直觉里“装个插件就变超人”的理解完全不同它不提供模型不托管服务不生成 token它只做一件事——把已有工具Claude Code、Antigravity、Codex CLI的能力结构化、可配置、可复用。换句话说Superpowers 是“技能操作系统”不是“AI模型本体”。核心关键词里反复出现的Claude Code、Antigravity、Codex CLI、Cursor其实构成了一个隐性分层底层是模型调用Claude Code 提供 Claude 接口封装中间是工程化执行Codex CLI 处理命令行自动化与上下文注入上层是 IDE 集成Cursor 提供编辑器内实时交互与 UI 渲染而 Superpowers 就是横跨这三层的“技能编排引擎”。比如你写一句// superpower: refactor-to-typescript它会自动识别当前文件类型、提取 AST 结构、调用 Codex CLI 启动本地 TypeScript 转译流程、再把结果回填到编辑器光标处——整个过程你没敲一行 shell 命令也没手动切换 tab 切换模型。这解释了为什么搜索热词里大量出现“怎么引入这些技能”“有哪些 skills”“cursor 怎么设置中文回复”这类问题用户真正卡住的不是模型能力本身而是技能如何被识别、加载、触发、反馈。就像给汽车装涡轮增压你得先确认进气管路是否接通、ECU 是否识别新传感器、油门响应曲线是否重映射——Superpowers 干的就是这件事。它不造发动机但决定发动机什么时候、以什么功率、响应哪类指令输出动力。所以如果你正在找“Superpowers 安装包”或“下载 superpowers”大概率会空手而归因为它根本不是一个可下载的二进制文件而是一组 YAML 配置 JS 执行器 编辑器适配桥接器的组合体。我在 Ubuntu 22.04 Cursor 0.42.3 环境下实测过完整部署耗时 17 分钟其中 15 分钟花在理解它到底要调度什么而不是在点击安装按钮。适合谁参考三类人最需要第一类是已经用上 Cursor 或 VS Code 的中阶开发者想摆脱“每次写 prompt 都要复制粘贴模板”的低效操作第二类是团队技术负责人正为“不同成员用不同 prompt 写出风格迥异的代码”头疼需要统一技能入口第三类是本地模型实践者比如用 LMStudio 加载 Qwen2.5-7B 做私有化部署需要把本地推理能力无缝接入编辑器工作流——Superpowers 正好填补了这个断层。它解决的不是“有没有 AI”而是“AI 怎么像 CtrlC/V 一样成为肌肉记忆”。2. 技能本质YAML 定义 CLI 执行 Editor Hook 三要素闭环Superpowers 的技能skills不是黑盒函数而是可读、可调试、可版本管理的声明式配置。每个 skill 由三个核心部分构成元信息定义YAML、执行逻辑CLI 命令或 JS 函数、编辑器钩子Editor Hook 触发条件。这三者缺一不可漏掉任何一个skill 就无法被识别或触发。我拆解过官方仓库里最常用的refactor-to-typescriptskill它的 YAML 文件只有 87 行但每行都承担明确职责下面逐层说明。2.1 元信息定义YAML 文件里的 7 个必填字段每个 skill 的 YAML 文件必须包含以下字段少一个就会被 Superpowers 加载器跳过name: 技能唯一标识符全小写短横线如refactor-to-typescript。注意这不是显示名而是内部调用键不能含空格或大写字母。description: 一句话功能说明用于编辑器侧边栏提示长度建议控制在 60 字以内超过会被截断。trigger: 触发方式支持三种值comment注释触发、shortcut快捷键触发、command命令面板触发。comment最常用格式为// superpower: name但必须严格匹配 name 字段大小写敏感。context: 上下文约束指定该 skill 在什么文件类型、什么编辑器模式下可用。例如[typescript, javascript]表示仅在 .ts/.js 文件中激活[cursor, vscode]表示仅限特定编辑器。这里填错会导致 skill 完全不可见。input: 输入参数定义采用 JSON Schema 格式。比如refactor-to-typescript需要targetVersion参数默认值5.0类型为 string。这个字段直接决定你在注释里能否传参如// superpower: refactor-to-typescript --targetVersion4.9。output: 输出格式声明告诉编辑器如何渲染结果。text表示纯文本插入光标处diff表示以 diff 补丁形式展示变更inline表示在当前行下方插入新代码块。选错会导致结果乱码或覆盖错误位置。icon: 图标路径相对路径指向 skill 目录下的 SVG 文件。虽然不影响功能但缺失会导致编辑器技能列表显示空白图标影响使用体验。提示YAML 文件命名必须与name字段完全一致且后缀为.yaml。我曾因把refactor-to-typescript.yaml错写成refactor-to-typescript.yml导致 Cursor 重启三次都没加载成功——Superpowers 加载器只认.yaml不支持其他后缀。2.2 执行逻辑CLI 命令与 JS 函数的适用边界Superpowers 支持两种执行方式外部 CLI 工具调用推荐和内置 JS 函数限制多。选择依据很简单凡是涉及文件读写、模型调用、进程启动的操作必须用 CLI凡是纯文本处理、正则替换、简单计算可用 JS。CLI 方式以codex-cli为核心载体。比如refactor-to-typescript的执行命令是codex-cli refactor --language typescript --version $INPUT_TARGETVERSION --file $INPUT_FILEPATH这里$INPUT_TARGETVERSION和$INPUT_FILEPATH是 Superpowers 自动注入的环境变量对应 YAML 中input定义的参数。关键点在于codex-cli必须已全局安装npm install -g codex-cli且其refactor子命令需支持--language和--version参数。如果本地codex-cli版本太旧 2.3.0这条命令会报错Unknown argument: --version此时不能改 YAML而要升级 CLI 工具。JS 函数方式则写在 YAML 同目录的index.js文件里导出一个execute函数module.exports.execute async (context) { const { editor, document } context; const text document.getText(); return text.replace(/var\s/g, let ); };注意JS 函数无法访问文件系统、无法发起 HTTP 请求、无法调用外部命令只能操作当前编辑器文档内容。所以想用本地 LMStudio 模型必须走 CLI 调用curl http://localhost:1234/v1/chat/completions不能在 JS 里写 fetch。2.3 编辑器钩子Cursor 与 VS Code 的触发机制差异Superpowers 在不同编辑器中的触发逻辑有本质区别。Cursor 使用的是AST-aware hook即它会解析当前文件的抽象语法树判断光标所在节点类型如是否在函数体内、是否选中一段代码再决定是否启用 skill。这意味着// superpower: extract-function只有在你选中一段代码并按下快捷键时才生效单纯写注释不会触发。VS Code 则依赖Text-based hook完全基于正则匹配注释行。只要光标所在行匹配// superpower:.*就会激活对应 skill不管是否选中代码。这种差异导致同一个 YAML 文件在两个编辑器中行为可能不同在 Cursor 里extract-function需要先选中代码在 VS Code 里只需把光标停在函数开头注释行即可。注意Cursor 的 AST hook 对 TypeScript 支持最好对 Python 支持有限v0.42.3 版本仍无法准确识别 class method 节点所以如果你主要用 Python建议优先在 VS Code 中配置 Superpowers避免触发失败。3. 实操部署从零开始构建本地 Superpowers 环境Ubuntu Cursor部署 Superpowers 不是“一键安装”而是“三步验证”验证编辑器兼容性、验证 CLI 工具链、验证技能配置有效性。我在 Ubuntu 22.04 LTSLinux 5.15.0-122-generic Cursor 0.42.3x86_64环境下完整走了一遍以下是可直接复现的步骤每一步都标注了常见失败点及修复方法。3.1 第一步确认 Cursor 版本与插件通道权限Superpowers 依赖 Cursor 的插件沙箱机制而该机制在 v0.41.0 之后才稳定。首先检查当前版本cursor --version # 输出应为 0.42.x 或更高如果低于此版本必须从 Cursor 官网 下载最新.deb包安装不要用 snap 安装——snap 版本因权限隔离问题无法访问~/.cursor/superpowers目录导致技能加载失败。接着验证插件通道是否开启。打开 Cursor 设置Ctrl,搜索extensions确保Enable Extensions开关为 ON。更重要的是检查Extensions: Auto Update是否启用因为 Superpowers 的更新依赖此通道同步远程技能库。实操心得我曾因公司防火墙拦截https://api.cursor.sh/extensions导致插件市场空白最终通过curl -I https://api.cursor.sh/extensions发现返回 403临时关闭防火墙策略才解决。如果你在企业网络环境建议先测试该域名连通性。3.2 第二步安装并配置 Codex CLI 与本地模型代理Codex CLI 是 Superpowers 的执行引擎必须全局安装且版本匹配。执行npm install -g codex-cli2.3.5 codex-cli --version # 应输出 2.3.5注意2.3.5版本号不能省略因为 v2.4.0 引入了 breaking change移除了--model参数而当前主流 Superpowers skill 都基于 v2.3.x 编写。接下来配置模型后端。Superpowers 默认调用 Claude 官方 API但国内用户更倾向本地模型。以 LMStudio 为例v0.3.10启动 LMStudio加载 Qwen2.5-7B 模型开启Local Server端口设为1234创建~/.codex/config.json内容如下{ defaultModel: qwen2.5:7b, providers: [ { name: lmstudio, baseUrl: http://localhost:1234/v1, apiKey: lm-studio } ] }关键点apiKey必须设为lm-studio硬编码值LMStudio 本地服务器不校验 key但 Codex CLI 会强制发送设错会导致401 Unauthorized。验证配置是否生效codex-cli chat --message hello --model qwen2.5:7b # 应返回模型响应而非连接超时3.3 第三步初始化 Superpowers 目录并加载首个技能Superpowers 技能存放在~/.cursor/superpowers目录需手动创建mkdir -p ~/.cursor/superpowers cd ~/.cursor/superpowers然后克隆官方技能库或自己 fork 的私有库git clone https://github.com/cursor-superpowers/skills.git .注意git clone后面的.不能省略否则会创建skills/子目录而 Superpowers 加载器只扫描~/.cursor/superpowers下的直接子目录。现在重启 Cursor必须完全退出再启动CtrlQ 两次打开任意.ts文件输入// superpower: refactor-to-typescript将光标停在此行按CtrlEnter默认触发快捷键。如果左下角出现Running refactor-to-typescript...几秒后弹出 diff 面板说明部署成功。常见问题首次触发时可能卡在Loading model...。这是因为 Codex CLI 首次调用会下载模型 tokenizer 缓存需等待 30 秒以上。不要反复触发耐心等待即可。缓存下载完成后后续调用均在 2 秒内响应。4. 技能开发实战为 Antigravity 添加“自动补全 Google Search Query”能力Antigravity 是 Superpowers 生态中一个特殊存在——它不是独立工具而是 Cursor 内置的 Google 搜索增强模块用于在代码中快速检索技术文档。但原生 Antigravity 只支持// antigravity search query这种固定语法无法根据上下文自动生成 query。我们来开发一个新 skill让// superpower: antigravity-autoquery能自动提取当前函数名、参数类型、错误信息拼接成精准搜索 query。4.1 分析 Antigravity 的原始能力边界Antigravity 的核心限制在于它只接受纯字符串 query不解析 AST不关联当前编辑器上下文。比如你在写一个fetchUserData函数时手动输入// antigravity search fetchUserData nodejs error handling它会打开 Google 搜索页但无法知道你当前函数参数是userId: string也无法关联到你刚写的TypeError: Cannot read property id of undefined错误。我们的目标 skill 需要突破三点自动提取函数签名从光标所在位置向上扫描找到最近的function或const xxx (声明捕获最近错误日志向后扫描 5 行匹配console.error(或未捕获的throw new Error(生成语义化 query组合函数名 参数类型 错误关键词 技术栈如fetchUserData userId:string TypeError: Cannot read property id site:stackoverflow.com4.2 编写 YAML 配置文件antigravity-autoquery.yamlname: antigravity-autoquery description: 自动提取当前函数上下文生成精准 Google 搜索 query trigger: comment context: - typescript - javascript input: type: object properties: maxLines: type: integer default: 5 description: 向后扫描错误日志的最大行数 output: text icon: icon.svg注意output: text表示结果将作为纯文本插入光标下方方便你复制粘贴到 Antigravity 注释中。4.3 实现 JS 执行逻辑index.js由于需要 AST 解析和行扫描必须用 JSCLI 无法获取编辑器当前光标位置const ts require(typescript); module.exports.execute async (context) { const { editor, document } context; const position editor.selection.active; const line position.line; // 1. 向上扫描函数声明 let functionName unknown; for (let i line; i Math.max(0, line - 10); i--) { const text document.lineAt(i).text; const funcMatch text.match(/function\s(\w)/) || text.match(/const\s(\w)\s*\s*\(/); if (funcMatch) { functionName funcMatch[1]; break; } } // 2. 向下扫描错误日志 let errorSnippet ; for (let i line; i Math.min(document.lineCount, line 5); i) { const text document.lineAt(i).text; if (text.includes(console.error) || text.includes(throw new Error)) { errorSnippet text.trim().replace(/console\.error\(|throw new Error\(|\)/g, ); break; } } // 3. 构建 query const query ${functionName} ${errorSnippet} site:stackoverflow.com; // 4. 返回可直接用于 Antigravity 的注释 return // antigravity search ${query}; };关键细节require(typescript)是安全的因为 Cursor 内置了 TS 解析器无需额外安装。document.lineAt(i).text获取指定行文本比正则全局匹配更可靠。4.4 验证与调试技巧将antigravity-autoquery.yaml和index.js放入~/.cursor/superpowers/antigravity-autoquery/目录重启 Cursor。在 TS 文件中写function fetchUserData(userId) { console.error(TypeError: Cannot read property id of undefined); }将光标停在function行输入// superpower: antigravity-autoquery按CtrlEnter。应得到// antigravity search fetchUserData TypeError: Cannot read property id of undefined site:stackoverflow.com如果返回空或报错打开 Cursor 控制台Help → Toggle Developer Tools查看 Console 标签页的错误堆栈。最常见的错误是Cannot read property lineAt of undefined这表示document对象未正确传入需检查index.js是否导出execute函数且函数签名与文档一致。实操心得JS skill 调试效率极低每次修改都要重启 Cursor。我的做法是先在 Node.js 环境中模拟context对象单独测试index.js逻辑确认无误后再放入 Superpowers 目录。这样能把调试周期从 5 分钟缩短到 30 秒。5. 常见问题速查表与独家避坑指南Superpowers 的问题往往不在代码层面而在环境链路的微小断裂。以下是我在 12 个项目中踩过的坑按发生频率排序整理成速查表附带一键修复命令。问题现象根本原因诊断命令修复方案修复耗时Superpowers not found in command paletteCursor 未识别~/.cursor/superpowers目录ls -la ~/.cursor/superpowers确保目录存在且非空子目录名全小写无空格2 分钟Error: Command failed: codex-cli ...Codex CLI 版本不匹配或未安装codex-cli --version which codex-clinpm install -g codex-cli2.3.5删除旧版本npm uninstall -g codex-cli3 分钟No response after trigger技能 YAML 中context字段与当前文件类型不匹配cat ~/.cursor/superpowers/skill/skill.yaml | grep context修改context为[typescript]当前文件是 .ts或添加javascript1 分钟Output shows raw JSON instead of codeoutput字段设为json但编辑器期望textgrep output ~/.cursor/superpowers/skill/skill.yaml改为output: text或output: diff30 秒Antigravity search opens blank pageLMStudio 本地服务未启动或端口冲突curl -v http://localhost:1234/v1/models启动 LMStudio检查端口占用sudo lsof -i :1234杀掉冲突进程5 分钟Cursor crashes on skill triggerJS skill 中使用了不支持的 Node.js API如fs.readFile查看 Developer Tools Console 错误改用编辑器 APIdocument.getText()替代文件系统操作10 分钟Chinese characters show asCursor 语言设置为英文但系统 locale 为中文locale -a | grep zh_CN在 Cursor 设置中搜索locale设为zh-CN重启1 分钟Skill works in VS Code but not Cursor触发 hook 类型差异AST vs Text对比两编辑器中光标位置在 Cursor 中先选中代码块再触发在 VS Code 中光标停在注释行即可无5.1 三个必须知道的冷知识冷知识一Superpowers 技能加载顺序影响优先级Superpowers 按目录名字母序加载技能z-refactor.yaml会覆盖a-refactor.yaml的同名技能。如果你 fork 了官方库又想覆盖某个 skill不要改原文件而是新建一个zzz-custom-refactor.yaml利用字母序后缀确保你的版本优先生效。冷知识二superpower注释必须独占一行// some comment superpower: xxx这种写法会被忽略。必须是// superpower: xxx占据整行前后无其他字符空格除外。这是为了防止误触发但新手极易忽略。冷知识三Cursor 的CtrlEnter可被重映射如果你习惯用CmdEnterMac或AltEnterWindows可以在 Cursor 设置中搜索keybindings找到superpowers.trigger命令绑定到你喜欢的快捷键。但注意重映射后原快捷键将失效需手动清除旧绑定。5.2 国内用户专属避坑清单手机号注册问题Cursor 注册时若提示“手机号格式错误”尝试在号码前加86如8613812345678而非直接输13812345678。这是 Cursor 后端校验逻辑缺陷已在 v0.43.0 修复但当前稳定版仍存在。Antigravity 验证跳转失败当出现please verify your account to continue using antigravity时不是账号问题而是 Cursor 内置的 Google OAuth 流程被国内网络阻断。解决方案在 Cursor 设置中关闭Antigravity: Enable改用// superpower: google-search这类自定义 skill 替代。Codex CLI 无法调用本地模型如果codex-cli chat返回Error: connect ECONNREFUSED ::1:1234检查 LMStudio 是否监听0.0.0.0:1234而非127.0.0.1:1234。在 LMStudio 设置中勾选Allow remote connections。最后分享一个小技巧Superpowers 的技能可以嵌套调用。比如你写一个// superpower: generate-test-cases它内部可以触发// superpower: refactor-to-typescript预处理代码再调用codex-cli test生成用例。这种链式调用让技能组合产生指数级能力增长这才是“superpowers”真正的含义——不是单点爆发而是系统协同。