最近一直在折腾给 AI 助手“加技能”这件事圈子里讨论最多的就是 superpowers 这个项目。简单说它是一套开源技能框架核心思路不是让你写更多提示词而是通过结构化的 Markdown 技能文件把 AI 助手从“什么都会一点但不知道走什么流程”的通用工具变成真正懂项目规范、懂交付标准的得力搭档。这套东西最吸引我的地方在于技能文件是纯文本、可版本管理、可团队共享任何一个会写 Markdown 的人都能维护。这篇文章我会把安装、内置技能、自定义技能、踩坑记录整个过程完整梳理一遍如果你正准备引入这套体系可以直接照着操作。1. Superpowers 到底解决什么问题很多人第一次看到这个项目名第一反应是“超能力”。确实它的定位就是给 AI 助手装上各种技能包但这种“装技能”和我们平时理解的不太一样。它不是往系统里塞一个插件那么简单而是建立了一套“场景 流程 输出规范”的组合机制。我自己的理解是它本质上是一套用自然语言编写的“岗位操作手册”AI 在对话前先读取这些手册再按照手册里的步骤执行任务。为什么需要这样一套东西因为大模型本身的知识面很广但工作方式偏“自由发挥”。你让它写一个项目计划它可能写得很漂亮但未必符合你团队模板、未必覆盖风险项、也未必按你们约定俗成的流程来。superpowers 做的事情就是把老师傅积累的工作方法整理成一份 AI 能看懂的 SOP每次调用技能时它都先按 SOP 走一遍再输出结果。我把这个思路和传统的提示词工程做了对比。普通提示词是一次性的你每次都要把要求说清楚技能文件则是沉淀式的定义一次、反复使用而且可以像代码一样提交到 Git 仓库里审查、迭代。团队里任何一个人优化了技能文件其他人拉取更新后就能同步享受到改进成果。这是普通提示词做不到的。顺便说一下这个项目设计上有一个很聪明的点所有技能都放在项目目录下的固定路径里比如.ai/skills/。这样既不会污染项目根目录又方便 CI/CD 或者其他工具读取。而且技能文件完全开源你可以在别人定义的技能基础上改改就能用。下面我会一步步讲实际操作。1.1 技能文件的本质是“给 AI 的操作说明书”打开任意一个技能的目录你首先会看一个SKILL.md文件这就是技能的核心。它用 Markdown 写成开头有一段 YAML frontmatter里面声明了这个技能的 name、description后面正文则是具体的分步骤操作提示。AI 助手会在相关场景下自动读取这个文件然后按照里面的指令执行。这个文件本质上就是“操作说明书”但你写说明书的对象不是人而是大模型。所以语言表述要尽量精确、步骤要尽量原子化。我见过很多人写的技能文件最大的问题是太抽象比如“请对代码进行全面审查”这句话放进说明书的“执行步骤”里等于白写——模型根本不知道“全面审查”具体要查什么它只能按自己的理解自由发挥。好的技能文件应该像给实习生写的操作手册第一步做什么、第二步看什么、第三步把结果填到哪个模板里、最后输出什么格式的报告。模型读到这种级别的说明产出的质量就会非常稳定。我自己测试下来同样的代码审查任务用技能文件驱动和直接问 AI输出差异非常大——前者像专业团队的审查报告后者更像聊天式的随口点评。1.2 和普通提示词的区别在哪里有人会问我把这段说明写在系统提示词里不也一样吗区别很大。提示词会占用上下文窗口技能文件是按需加载的。AI 只在触发到对应场景时才去读取技能文件不触发就不占空间。这意味着你可以安装几十个技能而不必担心上下文被无关内容塞满。另一个区别是组织方式。提示词是线性排列的技能文件是树状分类的。你可以按照开发流程把技能分成规划、编码、审查、文档、调试等不同组别每组下再放具体技能。这种结构催生的使用方式不一样提示词是被动灌输技能文件是主动调用。2. 安装与初始化从零到“有超能力”安装本身不复杂但有几个前提条件需要确认。首先你的电脑上得装好 Node.js我用的是 18 以上的版本建议 20 LTS不然一些新依赖会有兼容性问题。其次这套框架需要配合支持 Skills 机制的 AI 助手使用比如 Claude Code 这类工具。如果你目前用的是普通聊天窗口那需要先去装一个对应的 CLI 工具再回来继续。下载项目的方式我推荐直接用git clone拉取官方仓库而不是手动下载 ZIP因为后续跟进更新时git pull比重新下载方便太多。仓库体积不大几十兆的样子拉取速度很快。拉下来后进入目录执行安装脚本这一步会把核心 CLI 工具链接到全局环境中。安装完成后最重要的初始化步骤是把技能目录注册到你的 AI 助手配置中。不同助手配置方式略有差异但基本思路一致告诉助手“你的技能在哪个目录下”。这一步千万别跳过我一开始就是在这踩了坑——装完 CLI 就以为完事了结果问 AI 它有哪些技能它一个都说不出来因为根本没给它指定目录。技能目录初始化之后去项目目录下执行superpowers list这类命令如果能看到输出技能清单说明框架已经装好了。这时候你可以先用简单指令测试比如“列出你目前已加载的所有技能”看 AI 能否准确回答。如果它能说出来说明整个链路已经通了。2.1 安装前的环境准备清单我整理了一份清单照着确认比看长篇教程更高效Node.js 版本18建议 20 LTSGit确认已加入系统环境变量磁盘空间预留 200MB 以上AI 助手 CLI已登录且能正常对话网络代理能访问 GitHub 即可无特殊要求如果你用的是公司内网环境还要确认 Git 能正常访问外部仓库。我见过有位同事装了半小时没反应最后发现是公司 Git 配置了内部镜像拉取外部仓库全部超时。这种情况建议直接配置一行 Git 代理或者临时切换仓库源具体方案搜索引擎上很多这里不展开。另外Windows 用户要注意 PowerShell 的执行策略。如果安装脚本无法运行大概率是权限问题直接用管理员身份运行或者调整执行策略即可。macOS 用户则要注意首次安装时的 Gatekeeper 拦截右键打开或者手动放行一下。2.2 三步初始化下载、安装、注册第一步选择合适目录。不要把 superpowers 仓库克隆到系统临时目录它后续要长期使用建议放到~/workspace或者你常用的工具目录下方便统一管理。cd ~/workspace git clone https://github.com/你的仓/uperpowers.git cd superpowers第二步执行安装。官方文档写的是一个命令但实际操作可能需要根据系统环境微调。以 npm 为例npm install -g .或者使用项目自带的安装脚本。这一步主要是把 CLI 命令暴露到全局后面用它来管理和加载技能。第三步注册技能目录到 AI 助手。这一步是核心具体方法是在 AI 助手的配置文件中添加一条指向.ai/skills的路径。也有版本支持直接在助手里执行/skills 目录路径这种斜杠命令完成注册两种方式任选。注册完成后我强烈建议你运行一下自检命令如果支持superpowers doctor类似命令的话直接一键检查环境。它会告诉你缺少哪些依赖、哪个路径配置不对比自己盲猜效率高很多。2.3 验证安装是否生效装完框架后别急着去问 AI 复杂问题先做两个最基础的验证。第一在命令行执行superpowers list确认技能文件能被 CLI 扫描到。如果这里就报错说明路径配置或者文件结构有问题先解决再说。第二回到 AI 对话界面直接问“你现在有哪些可用技能”观察它能否正确列出。我在验证阶段遇到过一个典型问题CLI 能列出技能但 AI 告诉我它看不到任何技能。后来发现是 AI 助手的上下文需要重启才生效配置加载是启动时一次性读取的。你改完配置后记得重启一下对话会话而不是在旧会话里反复追问。验证通过后可以尝试调用一个最简单的技能比如“请帮我用文档技能生成当前项目的 README”看看 AI 是否真的按照技能文件里的流程去执行。如果输出的格式和技能文件里定义的模板完全吻合说明整个链路已经全通了。3. 内置技能盘点它到底能干什么这套框架自带了不少开箱即用的技能下面把几个我用下来最有感的列出来。每个技能本质上是一份高度定制化的指令集覆盖了软件研发里最常见的几个场景规划、文档、编码、审查、调试。技能名称典型触发场景输出效果planning开始新项目或新功能前输出分阶段实施计划含风险列表和验收标准documentation生成项目文档、README、API 手册按照团队模板输出结构化文档code-review提交代码审查、合并请求前按检查清单逐项审查输出问题分级列表debugging追踪疑难 bug、定位崩溃根因按假设树逐步排查输出根因报告good-first-issues为开源项目筛选新手任务标注难度等级、涉及文件、入门指引这些技能的共同点是从“给出答案”变成“给出过程”。比如 debugging 技能不会直接告诉你“这段代码哪里错了”而是引导 AI 先建立几点假设逐一验证最后定位根因。这种输出方式在复杂 bug 场景下非常有用因为很多问题不是一眼能看穿的有一个系统化的排查步骤才能真正找到根源。代码审查技能是我日常工作里用得最多的。它内置的清单包括 API 兼容性、错误处理、性能隐患、安全问题、命名规范等多个维度。我把这个技能接入团队流程后最大的改变是人工评审精力被解放出来了——AI 先扫一遍常见问题人工只需要聚焦在架构设计层面。虽然 AI 审查结论不代表一切但它能保证低级问题不被漏掉。计划技能同样值得一试。以前让 AI 直接做计划它给的是通用的、看似合理但缺乏依据的方案现在通过规划技能它会先要求我补充项目背景、约束条件、里程碑信息然后再往下拆解任务制定阶段计划、设置里程碑、生成验收标准。这个流程的变化反映了一个核心思想好的输出不是模型一步到位的而是通过预设流程逼着它一步一步走。3.1 规划技能从一句需求到可执行路线图我专门用 planning 技能做过一次完整的新功能设计。当时的需求是“给现有应用增加一个多语言支持模块”直接问 AI 的话它能给出实现思路但经常停留在“引入 i18n 库、建立语言包”这种层层面面。通过规划技能AI 会先让我补充信息支持的语种、现有代码结构、构建流程、团队技术栈等等。信息补齐后它会输出一份包含五个阶段的计划需求确认 → 基础框架搭建 → 内容迁移 → 验证 → 发布。每个阶段下面都有明确产出和验收标准。最让我意外的是它还识别出了“字符串硬编码存量清理”这项风险并把它单独列为一个大阶段。这种输出质量的差异正是技能文件的价值所在——AI 还是那个 AI但站在了工作方法论的肩上。3.2 调试技能用假设树代替瞎猜排查 bug 是最容易“跟着感觉走”的任务debugging 技能在这方面做得很出色。技能文件里要求 AI 按步骤进行先复现问题、明确期望行为和实际行为、建立可能原因的假设树、逐个验证排除、最后确定根因并给出修复建议。有一次线上出现偶发性请求超时用传统方式查了很久没头绪后来借助调试技能AI 先帮我排查了连接池配置分析 SQL 慢查询最后定位到 DNS 解析的超时设置。如果没有这种强制流程我大概率会在错误的方向上浪费时间。它的每一步都会问你当前的观测结果再基于观测给出下一步行动。这对有经验的开发者来说其实是把常见的排查方法论固化了下来省去了自己每次都要从头理思路的麻烦。4. 如何引入自己的技能从 SKILL.md 写起框架内置技能再多最终还是要落到你的实际工作流里。学会自定义技能才能把这套工具的效能最大化。自定义技能的核心就是创建SKILL.md文件放在.ai/skills/技能名/目录下。这个文件的结构并不复杂但写得好坏直接决定 AI 能不能正确调用它。最基本的目录结构是这样的项目/ └── .ai/ └── skills/ └── skill-name/ ├── SKILL.md └── references/ └── 参考资料.mdSKILL.md里面分两个部分frontmatter 和正文。frontmatter 是 YAML 格式包含 name 和 description 两个字段正文则是 Markdown 指令集包含技能的详细介绍和完整步骤。这里要特别提醒frontmatter 里的 description 写得好不好直接影响技能能不能被 AI 在合适场景下自动触发。AI 判断是否调用某个技能就是靠用户需求和 description 之间的语义匹配。所以 description 不能写成“这是一个代码审查技能”而要写成“当你需要对指定文件或代码段进行逐行检查找出潜在错误、安全隐患和性能瓶颈时使用本技能”。越具体越好。正文部分决定了技能调用后 AI 怎么做。我建议写成分步骤指令每个步骤下再附上“怎么做”的细节。AI 是逐段读取指令执行的所以不要大段放背景知识要把步骤拆得足够细、足够可操作。比如你写“检查代码安全性”就太宽泛了要拆成“检查用户输入是否经过校验”“检查是否使用参数化查询防注入”“检查敏感信息是否硬编码”等具体条目。4.1 从零写一个自定义技能代码审查增强版我举个例子。团队要做一个专门审查云上部署配置的技能直接叫infra-review。我在.ai/skills/infra-review/SKILL.md里写的内容大概是这样--- name: infra-review description: 当需要对 Kubernetes 部署配置、Dockerfile、Terraform 脚本进行安全与最佳实践审查时使用 --- # 基础设施配置审查 执行以下步骤逐步审查并输出报告 1. 定位配置文件要求用户提供或确认待审查文件路径。 2. 逐项检查安全配置包括镜像来源、特权模式、敏感环境变量、网络策略。 3. 检查资源声明CPU 和内存 limits 是否配置避免 Kubernetes 节点资源耗尽。 4. 检查高可用配置副本数、Pod 反亲和性、PodDisruptionBudget 是否存在。 5. 输出审查报告分为高危、中危、低危、建议四个等级按文件路径行号列出问题。这里面最关键的一步是第 5 步我刻意指定了输出格式。如果不指定格式AI 会自由发挥出来的报告结构五花八门。指定之后它每次输出都是统一的等级划分和摘要格式可以直接贴进工作流。写完SKILL.md后直接在 AI 对话里发一句“用 infra-review 审查我准备上传的这份 deployment.yaml”如果 description 写得够清晰AI 会自动匹配并读取文件执行。完全没有其他额外操作。4.2 技能的参考资料目录怎么用references目录存放辅助信息比如代码规范、架构说明、术语表、历史决策记录。AI 在某些场景下需要这些背景知识才能提供合适的输出。它的作用就像给新同事一份参考资料有问题时自己查不需要你把每一个概念都写进主指令文件。我这里举个例子你的项目用了一种内部开发的构建工具外部资料很少。你可以在技能的 references 里放一份“构建命令手册.md”然后在主SKILL.md里写一行“遇到构建相关问题时查阅 references/构建命令手册.md 获取命令格式”。这样 AI 回答时就会优先引用你整理的权威资料。注意 references 目录下的内容不要过多否则 AI 读取时会占用上下文窗口技能执行效率会变低。我自己的经验是单个技能的参考资料控制在 5 个文件以内每个文件不超过 1000 行。4.3 技能的版本管理与协作因为技能文件是纯文本天然适合放进 Git 仓库。团队协作时每个人都可以在本地新增技能经过评审后合并到主干。这实际上是把团队经验沉淀到了代码库里而不需要靠口口相传或者写长文档。我特别推荐把技能文件当作“代码规范的可执行版本”来对待。以前团队定了一堆开发规范文档放在 Wiki 里真正干活时没人会翻现在规范被写成技能文件AI 在代码评审时自动按规范检查相当于规范被强制执行了。这个思路的效果比任何代码规范文档都好。5. 常见问题与排错实录折腾这套框架的过程中我也踩过不少坑。这里整理几个最典型的问题供你参考。技能没有被自动触发。这是最常遇到的问题。表现是你明明安装了技能AI 却在你需要时没有调用它。原因大概率出在 description 不够具体AI 无法把它和当前任务关联起来。解决方法是把 description 写得更贴近真实需求场景多写几个同义触发词比如代码审查技能不仅写“审查代码”还要写“code review”“检查代码质量”“找出潜在风险”等常见表达。CLI 列表和 AI 识别结果不一致。CLI 能扫到的技能 AI 说没有这种情况通常是配置加载问题重启会话或者检查技能目录是否在 AI 助手的搜索路径下。技能输出质量不稳定。同一个技能有时输出很好有时很敷衍问题大多出在正文的逻辑结构不够严谨。如果SKILL.md步骤写得模糊AI 就会自由发挥。我在补丁中加入了强制输出格式的提示词后质量稳定了很多。参考资料文件过多导致上下文膨胀。技能文件本身加上附带参考文件会占据上下文如果技能过多或者单个技能内容过长AI 的执行质量会下降。解决方法是保持技能的“小巧”一个技能专注解决一个场景不要贪多求全。5.1 排查思路与调试技巧遇到问题我第一步会直接去读 AI 的原始输出日志查看它是否有加载技能文件的记录。很多 CLI 工具都支持 verbose 模式或调试日志开启后能看到每一步的调用情况。第二步是检查技能文件的 YAML 格式。frontmatter 解析非常严格空格、缩进错误、冒号后没加空格都会导致整个文件无法加载。我写文件后都会找一个 YAML 校验工具先检查一遍格式这个小习惯帮我避免了很多低级错误。第三步是隔离变量。如果自定义技能有问题先把全套配置切回默认状态只保留一个自定义技能再测试这样能快速判断是框架问题还是配置问题。5.2 几个容易被忽略的细节技能文件内不要出现过多互相矛盾的指令。AI 在步骤冲突时会随机选择导致输出不可控。每个技能应该保持单一职责。不要给技能设置过长的标题。技能名最好控制在 2-4 个单词太长会导致识别率下降。另外不要在SKILL.md里写“你是某某专家”这种角色设定。角色设定应该放在助手的基础配置里技能文件专注在操作流程上。最后定期更新项目版本。框架本身迭代很快新版本会修复兼容性问题也会优化技能加载机制。我用的是官方的自动更新脚本每隔一周拉一次最新版本基本没遇到太大问题。我的实际体验和下一步计划如果你刚接触这套框架我建议先从内置技能开始用别急着自定义。先用planning和code-review跑几个真实项目体会一下“按流程输出”和“自由发挥”的差别。等你对技能文件的写法有了感觉再动手写自己的技能。我自己目前维护了一套团队内部技能库包含 12 个定制技能基本覆盖了从需求分析到上线验证的全流程。个人比较想扩展的方向是把设计文档自动生成、接口契约测试也做成技能。这套东西的价值要真正用起来才感受得到如果你正在为 AI 输出不稳定而头疼它大概率能帮到你。