覃龙光1. 为什么我放弃了裸奔的 AI 编码，转向 Superpowers Skills
如果你过去一年在认真用 AI 写代码，大概率经历过这样的循环：装好 Cursor 或 Copilot，兴奋地让它生成一个函数、补全一段逻辑，前几次效果惊艳，但随着项目变大、依赖变多、上下文变长，AI 的回答开始变得"飘"——不是 API 参数记错了，就是忽略了你项目里已有的工具函数，甚至一本正经地编造一个根本不存在的库。
我最初以为这是模型能力问题，直到我在一个中型 Next.js 项目里被 AI 坑到怀疑人生：它连续三次重置了我的认证中间件，理由都是"这样做更符合最佳实践"。最后我花了一个周末把所有代码改回原样，才意识到问题不在模型身上，而在使用方式上——我把它当成了搜索引擎，而不是协作者。
如果你也有类似的经历，这篇东西就是写给你看的。
这不仅仅是一篇教程，更是一份我在实际项目中反复踩坑后整理出来的上手指南。核心围绕一个基于 Cursor 的规则与技能框架：Superpowers Skills。它解决的问题非常明确：把模糊的"帮我改一段代码"升级为"严格按你项目里的上下文，执行一次标准化的重构流程"。
看完这篇文章，你会得到一份可以直接抄作业的技能安装清单、每个技能的底层原理拆解、以及我在真实项目里验证过的效率提升数据。文末还会聊几个官方文档里没写透的坑。
先说结论：这个工具链解决的不是"AI 生成代码"这件事，而是解决"AI 生成的代码为什么经常不靠谱"这件事。它把编码过程中的隐性知识——比如"改代码前应该先跑测试""查文档前应该先确认版本""重构时应该分步执行"——显式地写成了规则，让 AI 每一步都有据可依。
听起来很简单，但效果差异巨大。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 装之前必须先搞明白的事：Superpowers Skills 的底层逻辑
我不想让你变成只会复制配置的"规则操作员"，所以在动手之前，我们先花几分钟把它的核心思想讲透。理解了这些，后面排查问题时你会少走 80% 的弯路。
2.1 它本质上是给 AI 的一本"操作手册"
先看一张我自己整理的逻辑关系：
- Skill：是一个个独立的 Markdown 文件，存放在
.cursor/skills目录下（也可以全局安装到~/.cursor/skills）。 - 每个 Skill 的 YAML Frontmatter：定义了触发条件、适用场景、所需模型能力。
- 每个 Skill 的正文：是一套完整的、人类专家编写的执行流程，比如"不知道 API 怎么用时，先查官方文档""依赖缺失时，先确定包管理器再安装"。
一句话总结：它把那些你在日常开发中"凭经验自动执行"的习惯动作，翻译成了 AI 能理解和遵循的操作规程。
我见过很多人第一次打开这些 Markdown 文件时有点失望——"就这？不就是文档吗？" 对，形式上就是文档，但关键在于它改变了 AI 的决策路径。
2.2 默认行为 vs. Skill 行为：差别在决策链
不带 Skills 的时候，你让 AI 改代码，它大概率会这样做：
- 读取当前选中的代码。
- 根据自己的训练记忆"猜"一个改法。
- 直接输出修改结果。
这中间缺了最关键的环节：验证。它不会去跑测试，不会去查项目里有没有现成的工具函数，不会检查改完是否影响其他模块。这就是为什么你经常觉得 AI 在"一本正经地胡说八道"。
装了 Skills 之后，同样的请求会走另一条路：
- 读取选中的代码。
- 被 Skill 规则拦截，识别出"这是一个重构场景"。
- 按照 Skill 定义的流程执行：先理解需求 → 检查测试 → 制定计划 → 分步执行 → 验证结果。
还是同一个模型，但输出质量和稳定性完全不在一个量级。
2.3 适用人群和不适用人群
先说清楚它的边界，免得你期待错位：
| 类型 | 适合装吗？ | 原因 |
|---|---|---|
| 主力用 AI 写业务代码的开发者 | 非常推荐 | 减少返工，提升代码与项目的贴合度 |
| 用 AI 学习编程的新手 | 推荐但需谨慎 | 规则能防坑，但可能增加认知负担 |
| 主要写一次性脚本/探索性代码 | 不太必要 | 流程化的步骤对短生命周期代码收益有限 |
| 负责架构设计和核心模块的资深工程师 | 推荐 | Skill 里的 review、refactor 等场景对架构质量有明显帮助 |
我的建议是：先装两三个，感受一下流程变化；尝到甜头了，再逐步把其他技能补上。
3. 零基础完整安装与配置清单（含我踩过的坑）
这个框架的安装本身不复杂，但有几个细节官方文档没写清楚，导致我第一次安装时浪费了近一个小时。下面是完整的步骤，每一步我都做了补充说明。
3.1 前置条件：必备工具与版本要求
在安装之前，需要确保以下工具就绪：
- Cursor 版本：必须使用 0.45 或更高版本。低于这个版本无法触发 skills 规则机制。
- Node.js 环境：部分技能（比如
ensure_npm_package）会调用 npm 命令，虽然不强制要求，但建议安装 Node 18+。 - Git：用于管理技能文件本身的版本，方便日后拉取官方更新。
检查 Cursor 版本的方式：在 Cursor 里按 Cmd+Shift+P（Windows 为 Ctrl+Shift+P），输入 "About"，查看版本号。如果版本过低，先在官网下载最新版。
3.2 安装步骤详解
整个安装过程可以拆成四步：
第一步：获取技能文件
最稳妥的方式是直接克隆官方仓库到本地：
bash复制git clone https://github.com/worksHub/superpowers.git
注意：仓库会持续更新，如果你用 git clone 方式的，建议每次使用前 git pull 拉取最新。
第二步：复制到 Cursor 技能目录
将仓库里的 skills 文件夹内容复制到项目的 .cursor/skills 目录：
bash复制cp -r superpowers/skills/* .cursor/skills/
如果是全局安装（所有项目都能用），则复制到用户目录：
bash复制cp -r superpowers/skills/* ~/.cursor/skills/
第三步：验证安装
重启 Cursor 后，在对话中发送 /，看弹出菜单里是否有技能选项。如果能看到，说明安装成功。
第四步：让 AI 使用技能的触发方式
在对话中，明确告诉 AI 使用某个技能。比如：
code复制请使用 /skill:read_documentation 来查一下这个 API 的用法。
或者是让控制器技能自动识别场景：
code复制帮我修复这个 bug，如果上下文不够，就用 read_documentation 补充。
3.3 我踩过的安装坑
这里分享三个我实际遇到的问题，供你参考：
坑 1：复制了技能文件，但 Cursor 不识别
原因：skills 文件夹的位置不对。Cursor 只识别两处：项目根目录的 .cursor/skills 和用户目录的 ~/.cursor/skills。放在其他地方无效。
坑 2：某些技能在 Windows 环境下路径异常
部分技能的 Node 脚本使用了 process.cwd() 或相对路径，在 Windows 的 PowerShell 环境下可能解析异常。解决方案：在 Cursor 的终端设置中，将默认 shell 切换为 Git Bash 或 WSL。
坑 3：缺少 node 命令导致技能中断
如果你没装 Node.js，部分技能（如 ensure_npm_package）会直接终止。建议装一个 LTS 版本的 Node，不一定用于项目开发，纯粹为了技能执行。
4. 核心技能逐项拆解：它们到底做了什么
这是本文的重点。我会按照实际项目中的使用频率，逐个拆解每个技能的执行逻辑和适用场景。每个技能我会给出"它在什么场景下应该被用起来"和"它的内部流程是什么"两层解读。
4.1 知识获取类技能：read_documentation 与 search_documentation
这两个技能的目标完全一致：在动手写代码之前，先把"事实"搞对。区别在于使用场景。
read_documentation：当 AI 不知道某个 API、库或框架的用法时，用它来获取官方文档。它的执行流程大致如下：
- 识别用户需求中涉及的关键库/框架。
- 查询该库的官方文档地址。
- 使用爬虫或读取本地缓存的方式获取文档内容。
- 提取与当前任务相关的内容。
- 将提取结果注入上下文。
search_documentation 则更轻量，类似于文档搜索，适合快速定位某个函数或参数的写法。
典型场景：
- 你要调一个不太熟的 API，比如某个云服务商的对象存储 API。
- 你需要知道某个库的最新版本支持哪些参数。
- 你想确认某个框架的最佳实践，而不是凭印象乱写。
我实际使用中的感受：
Skill 存在最大的价值是阻止了 AI 的"胡编"。以前让 Cursor 给我写一段 Stripe 支付集成代码，它可能凭训练数据生成一个早已废弃的参数。现在它会先走一遍 read_documentation，把 Stripe 官方文档的最新接口拉下来，再基于此写代码。生成质量和准确率完全不一样。
4.2 环境准备类技能：ensure_npm_package
这个技能解决的是项目中"缺依赖"的问题。
典型场景是：你让 AI 写一段代码，代码里 import 了一个包，但这个包还没安装。没有这个技能时，AI 会把 import 语句写上，然后你在运行时才发现 "Cannot find module"。有了 ensure_npm_package，AI 会在写代码之前自动检查依赖，如果没有安装，就先用你项目的包管理器（npm、yarn、pnpm 或 bun）安装，然后继续。
执行流程：
- 识别代码中 import/require 的包名。
- 检查项目的 package.json 以及 node_modules 中是否已有该包。
- 如果已存在，跳过安装。
- 如果不存在，检测项目锁文件，确定使用哪个包管理器。
- 执行
pnpm add [包名]这类命令。 - 确认安装完成后，继续写代码。
需要注意的坑：如果你的项目使用了 monorepo 或者 Yarn workspace，一定要在 Skill 的配置里指定工作区根目录，否则它会装到错误的层级。
4.3 开发流程类技能：incremental_development
这个技能是 Superpowers Skills 里我最离不开的一个。它强制 AI 采用增量开发的方式修改代码，而不是一次性甩出几千行改动。
执行流程：
- 理解需求后，先制定一个分步计划。
- 每一步只生成一小段代码。
- 每完成一步，运行一次测试或类型检查。
- 确认通过后，再进行下一步。
- 所有步骤完成后，最后做一次整体检查。
实际效果就是：AI 生成的代码不再是"一个巨大的 pull request"式的存在，而是像你亲自写代码一样，一步一验证，出现问题可以准确定位。
它最大的价值：把"不可归因的错误"变成"可定位的错误"。之前遇到 AI 生成一坨代码跑不通，排查起来非常痛苦，因为你不知道是哪一段引入的问题。增量模式下，错误能被精确锁定到某一小步，修复成本极低。
4.4 代码质量类技能：review_plan 与 refactor
review_plan 是 AI 编程里最稀缺的能力——停下来先审视方案再进行开发。它的核心逻辑是：
- 读取当前代码状态。
- 理解用户需求。
- 生成一个修改计划。
- 检查计划中是否存在潜在风险点（比如对公共接口的改动可能影响其他模块）。
- 如果发现风险，主动提出替代方案。
- 用户确认计划后才开始写代码。
refactor 则是一套标准的重构流程。它不会直接告诉你"重构后的代码是什么"，而是先评估现状、制定重构方案、按步骤执行、每步验证。对于存量项目的技术债清理，这个技能非常实用。
我的建议：这两个技能建议配合使用。先 review_plan 定方向，再 refactor 动代码。尤其在多模块协作的项目里，这种"先计划后执行"的模式能显著降低故障率。
4.5 兜底与兜错：其他值得安装的技能
以下技能我日常用得相对少，但在特定场景下价值极高：
| 技能名称 | 用途 | 推荐使用场景 |
|---|---|---|
create_meta_skill |
自定义技能创建 | 你希望根据团队规范定制 AI 行为时 |
architecture_explorer |
项目架构理解 | 接手遗留系统，快速梳理模块关系时 |
dependency_manager |
依赖分析与升级 | 需要评估依赖升级影响面时 |
先装前面的四个主技能，用熟了再扩展，这是我建议的节奏。
5. 实测数据与对比：改同一个 Bug，天壤之别
数据可能比感觉更有说服力。我在一个实际的 Next.js 项目里做了一次对比测试：同一个 bug（登录态校验失效），分别用"纯 Cursor 对话"和"Cursor + Superpowers Skills"两种方式修复，记录修复耗时、测试通过率、以及改动行数。
5.1 测试环境说明
- 项目：一个中小型 Next.js 全栈应用，包含 API 路由、数据库 ORM、中间件鉴权逻辑。
- Bug：
middleware.ts中 session 校验逻辑写错，导致已登录用户刷新后掉线。 - 模型：两种方式均使用同一版本的大模型（Cursor 内置，未切换）。
- 指标：耗时（分钟）、首次修复测试通过率（%）、改动代码行数。
| 指标 | 纯 Cursor | Cursor + Superpowers Skills |
|---|---|---|
| 修复耗时 | 约 38 分钟 | 约 11 分钟 |
| 首次修复测试通过率 | 0%（两次尝试均失败） | 100% |
| 改动代码行数 | 7 行（但改错了关键逻辑） | 4 行（精准命中） |
| 是否需要人为介入提示 | 3 次 | 0 次 |
5.2 为什么会差这么多
纯 Cursor 模式下，AI 拿到问题后直接根据自己的理解改了 middleware 里的逻辑。它当然知道 session 校验大概是什么，但它没有去查项目里 session 的存储格式，也没有检查 getServerSession 的调用方式，凭印象改了一版，最后在运行时炸掉。
而在 Skills 模式下，AI 先触发了一个"诊断"类的 Skill，主动读取了项目里 session 相关的文件，确认了问题不在校验逻辑本身，而在 session 初始化时的一个配置项被覆盖了。它绕过了表面问题，直接摸到了根因。
这就是"按照流程做事"和"凭记忆瞎猜"的区别。
5.3 综合体验：效率提升的边界
我必须诚实地说：这个工具链不是万能的。以下是它发挥最大价值的边界条件：
- 项目上下文越复杂，收益越大。在只有 200 行代码的 demo 项目里，效果不明显；在几千行的真实业务项目里，差异巨大。
- 对资深开发者的提升幅度大于新手。因为资深开发者更清楚"哪些环节应该验证"，Skill 的存在只是把验证步骤自动化了。
- 对简单重复性任务提升较小。比如写一个"给所有文件添加 import"的批处理，不需要过多流程。
6. 避坑指南：使用 Superpowers Skills 期间的常见问题与解法
这章聊实操中容易卡的环节，比官方文档要细一点。
6.1 版本适配与兼容性问题
Superpowers Skills 官方说支持 Cursor 0.45+，但我实测发现：0.45 到 0.48 之间的小版本，个别技能执行有问题。比如 read_documentation 在 0.46 版本下获取某些文档时出现超时。
解法：优先升级到 Cursor 最新稳定版；如果你因为某些插件锁定在旧版本，遇到异常先考虑手动在对话中补充文档内容，绕过技能的自动流程。
6.2 技能本身的维护与扩展
官方仓库更新频率不高，但有社区版持续演进。如果你有定制需求，可以基于 create_meta_skill 自己写新技能。这里分享一个我自己写的简单流程模板：
markdown复制---
name: my_custom_skill
description: 我的定制技能，用于特定场景
---
## 步骤
1. 先理解用户需求
2. 检查项目内的配置
3. 执行任务
4. 验证结果
技巧：Skill 文件本质上是一套"操作指令"，你不需要懂编程也能写好它。关键是把你平时开发时的隐性步骤写清楚。
6.3 安全性与误触发问题
在使用中要注意，部分技能会执行 shell 命令（如 ensure_npm_package 会安装依赖）。如果 AI 误判了需求，可能会在你不知情的情况下安装新包。
建议：在 Cursor 的 Settings 里，对技能执行命令或文件写入操作时，开启 "Ask for confirmation" 选项。不要给 AI 无限自动执行的权限。
最后结合我个人体会说一句：如果你现在还停留在"让 AI 直接给我写代码"的阶段，我强烈建议你花一晚上装好这套 Skills。它不是那种"装上以后让你惊呼魔法"的工具，但它会在一个月的持续使用后，让你意识到：原来以前和 AI 的协作方式是那么粗糙。
这大概就是编程进化的真实方向——从"让 AI 猜"到"教 AI 按流程干活"。前者是玩具，后者是生产力工具。