1. 从“超能力”到可复用技能库superpowers 到底在解决什么问题第一次听到 “superpowers” 这个词很多人会下意识联想到漫威电影里的超能力但在开发者圈子里它指的是一套围绕 AI 编程助手构建的技能skills集合与工作流框架。简单说它做的事情就是把那些你反复在 AI 对话里敲的提示词、反复纠正的代码规范、反复强调的项目约定全部沉淀成一个个可命名、可调用、可复用的“技能包”让 AI 助手在需要的时候自动加载而不是每次从零开始解释。这个需求是怎么冒出来的我自己用 AI 写代码有一年多最痛的三个点非常具体。第一是上下文漂移同一个项目里AI 前面还记得用 TypeScript 严格模式、用 pnpm 而不是 npm聊到第十轮就开始给你写any和npm install。第二是重复劳动每次开新会话都要把项目结构、代码风格、测试命令重新贴一遍贴到我自己都烦。第三是技能不可迁移我在 A 项目里调教好的一套“写 React 组件”的提示词换到 B 项目就得重写因为路径、依赖、约定全变了。superpowers 这类框架的核心价值就是把这三点一次性解决。它本质上是一个技能注册与注入机制你先把技能写成结构化的文件通常是 Markdown 加元数据框架负责在合适的时机把这些技能内容注入到 AI 的上下文里。这样一来AI 不再是“每次都要重新培训的实习生”而是“带着你团队 SOP 上岗的老员工”。适合谁来参考三类人最受益。第一类是重度使用 AI 编程助手的独立开发者你一个人要管前端后端部署技能库能帮你把脑子里的隐性知识显性化。第二类是小团队的技术负责人你可以把团队的代码规范、Review 清单、发布流程做成共享技能让每个成员的 AI 助手都遵守同一套标准。第三类是对 AI 工作流感兴趣的技术爱好者你想搞清楚“技能注入”这件事在工程上到底怎么落地superpowers 是一个很好的解剖样本。需要提前说明的是superpowers 并不是某个单一官方产品而更像是一类模式和实践的集合不同实现比如基于 Claude 的技能系统、基于 Cursor 的 rules、基于自建脚本的注入方案在细节上差异很大。所以下面我讲的内容会以“一个合格从业者在这种场景下最可能采用的合理方案”为基准来展开同时把不同实现路线的取舍讲清楚你对照自己的工具链做适配就行。2. 核心设计思路拆解为什么是“技能”而不是“提示词”2.1 技能与提示词的本质区别很多人会问我直接把提示词存成文本片段不就行了为什么要搞一套“技能”体系这个问题问到点子上了。提示词片段和技能的区别类比一下就是便利贴和函数的区别。便利贴是你随手写的一句话贴在哪儿算哪儿复用全靠你自己记得去翻函数是有名字、有参数、有明确调用时机的代码单元系统知道什么时候该调它。技能相比裸提示词多了四个关键属性。第一是触发条件技能文件里会写明“当用户要求写测试时加载本技能”而不是靠你手动粘贴。第二是作用域技能可以限定在某个目录、某个文件类型、某个任务类型下生效避免全局污染。第三是版本与依赖技能可以声明自己依赖哪些其他技能或工具形成组合。第四是可发现性框架能列出所有可用技能AI 自己也能“看到”有哪些技能可调这跟人翻手册是一个道理。我实测下来这四个属性里触发条件是最容易被低估的。早期我自己写技能只写了内容没写触发条件结果 AI 根本不知道什么时候该用技能等于白写。后来我把触发条件写清楚比如“当检测到项目根目录存在vitest.config.ts时测试相关技能自动激活”命中率立刻上来了。2.2 为什么选择 Markdown 作为技能载体几乎所有 superpowers 类实现都选择 Markdown 作为技能文件的格式这个选择不是随意的。Markdown 有三个天然优势人类可读、AI 友好、工具链成熟。人类可读意味着你 review 技能就像 review 文档不需要懂什么 DSLAI 友好意味着大模型对 Markdown 结构的理解非常成熟标题、列表、代码块都能被准确解析工具链成熟意味着你可以用 Git 管理、用 CI 校验、用编辑器插件高亮。对比一下其他可能的载体JSON 结构化好但写起来痛苦YAML 适合配置但不适合写长段说明纯文本没有结构。Markdown 是唯一一个在“写起来舒服”和“解析起来准确”之间取得平衡的格式。我试过用 YAML 写技能写到第三段说明就想砸键盘因为多行字符串的缩进处理太反人类了。2.3 技能注入的三种时机与取舍技能什么时候注入到 AI 上下文这个决策直接影响效果和成本。常见的有三种时机各有取舍。第一种是会话启动时全量注入。优点是简单AI 一开始就知道所有技能缺点是上下文被大量无关技能占满token 成本高而且 AI 容易在无关技能上分心。我早期就这么干结果一个写 CSS 的任务AI 给我扯了一堆数据库迁移的规范纯属干扰。第二种是按需检索注入。框架根据当前任务关键词从技能库里检索最相关的几个技能注入。优点是精准、省 token缺点是需要一套检索逻辑检索不准就会漏掉关键技能。这是目前主流方案通常用向量检索或关键词匹配实现。第三种是显式调用注入。用户或 AI 主动说“加载 XX 技能”框架才注入。优点是可控性最强缺点是对用户有认知负担你得记得有哪些技能。实际落地时混合方案最稳会话启动时注入一个“技能目录”只有技能名和一句话描述很省 tokenAI 需要时再按需加载完整技能内容。这就像你进图书馆先看索引需要哪本书再去取而不是一进门就把所有书堆你桌上。3. 技能库的目录结构与文件规范3.1 推荐的目录组织方式技能库的目录结构直接决定了可维护性。我踩过的坑是早期把所有技能平铺在一个目录里到二十个技能的时候找起来就费劲了。后来改成按领域分层清爽很多。下面是我目前用的结构你可以直接抄skills/ ├── core/ # 核心技能几乎每个项目都用 │ ├── code-style.md │ ├── git-commit.md │ └── error-handling.md ├── frontend/ # 前端相关 │ ├── react-component.md │ ├── css-convention.md │ └── state-management.md ├── backend/ # 后端相关 │ ├── api-design.md │ ├── db-migration.md │ └── auth-pattern.md ├── testing/ # 测试相关 │ ├── unit-test.md │ └── e2e-test.md └── project-specific/ # 项目专属技能 └── this-project.md这个结构的关键在于分层维度是“领域”而不是“工具”。我见过有人按工具分vscode 技能、cursor 技能结果同一个代码规范技能要在多个工具目录下重复维护改一处漏一处。按领域分工具只是加载方式不同技能内容只有一份。3.2 单个技能文件的标准字段一个规范的技能文件头部应该有元数据区正文才是技能内容。元数据区我建议至少包含这几个字段用 YAML front matter 写在文件最上方--- name: react-component description: 编写 React 函数组件的规范与模板 triggers: - 写组件 - 创建 React 组件 - component scope: **/*.tsx priority: 10 dependencies: - code-style --- # React 组件编写规范 正文内容...逐个解释这些字段为什么重要。name是技能的唯一标识检索和依赖都靠它所以必须全局唯一我习惯用短横线命名。description是一句话说明会出现在技能目录里写得好不好直接决定 AI 能不能判断该不该加载它所以要写“做什么”而不是“是什么”比如写“编写 React 函数组件的规范与模板”就比“React 组件技能”强得多。triggers是触发关键词列表这是命中率的关键。我的经验是每个技能写 3 到 8 个触发词覆盖用户可能的不同说法。比如“写组件”“创建组件”“新建组件”“component”都要列上因为不同人表达习惯不一样。scope用 glob 模式限定生效范围**/*.tsx表示只在 tsx 文件相关任务里生效避免污染其他任务。priority是优先级数字越大越优先。当多个技能同时命中时框架按优先级排序注入高优先级的先注入。这个字段在技能多的时候特别有用比如“项目专属规范”优先级设高一点能覆盖通用规范。dependencies声明依赖加载本技能时自动把依赖的技能也加载进来避免技能之间引用断裂。3.3 正文内容的写法要点元数据写好了正文才是技能的灵魂。我总结下来好的技能正文有三个特征具体、可执行、带反例。具体是指不要写“代码要整洁”这种废话要写“函数不超过 50 行超过就拆分嵌套不超过 3 层超过就用早返回”。可执行是指每条规范都能直接对应到一个动作AI 读完知道该怎么做。带反例是指除了写“应该怎样”还要写“不要怎样”因为大模型对反例的敏感度很高。举个例子我写的error-handling技能里有这么一段## 错误处理规范 ### 应该做的 - 所有 async 函数用 try/catch 包裹catch 里必须记录日志 - 对外 API 的错误统一用 AppError 类包含 code 和 message - 用户可见的错误信息要友好技术细节写进日志 ### 不要做的 - 不要吞掉错误空 catch 块 - 不要直接把 error.stack 返回给前端 - 不要在 catch 里只写 console.log 就完事这种“正反对比”的写法实测比单纯列规范效果好很多。AI 看到反例会主动规避就像你告诉新人“别这么干”比“要那么干”印象更深。4. 技能引入与安装的完整实操流程4.1 环境准备与前置检查在动手引入技能之前先确认你的环境满足基本条件。不同实现路线要求不同但通用的前置条件有这么几个。第一是一个支持技能注入的 AI 编程工具比如支持 rules 或 skills 机制的编辑器或者你自己写脚本对接 API。第二是Git技能库强烈建议用 Git 管理方便版本回溯和团队共享。第三是Node.js 或 Python 环境如果你要用脚本做检索和注入的话。我建议先做一个最小验证手动把一个技能文件的内容粘贴到 AI 对话里看 AI 能不能理解并遵循。这一步能帮你确认“技能内容本身”是有效的排除掉内容问题后面调试注入机制时就只需要关注机制本身。我见过有人一上来就搞复杂注入结果技能没生效排查半天发现是技能内容写得太模糊AI 根本没当回事。4.2 技能库的初始化步骤初始化一个技能库我习惯按下面的顺序来每一步都有明确的产出物。第一步创建目录骨架。按前面 3.1 的结构建好目录先只建core和project-specific两个其他等有需要再加避免一开始就过度设计。第二步写第一个技能。选一个你每天都在重复强调的规范比如 Git 提交信息格式。这个技能最容易见效因为提交信息格式是高频且明确的。写的时候严格按 3.2 的字段规范来别偷懒省字段。第三步写技能目录文件。在技能库根目录建一个SKILLS.md列出所有技能的名字和描述这个文件就是给 AI 看的“索引”。格式很简单# 可用技能目录 - react-component: 编写 React 函数组件的规范与模板 - git-commit: Git 提交信息格式规范 - error-handling: 错误处理与日志规范第四步配置注入机制。这一步取决于你的工具。如果是支持 rules 目录的工具把技能库软链接或复制到工具的 rules 目录如果是自建脚本写一个读取SKILLS.md并注入的脚本。下面给一个自建脚本的示例用 Node.js 实现按需检索// inject-skills.js const fs require(fs); const path require(path); const SKILLS_DIR ./skills; // 读取技能目录 function loadSkillIndex() { const indexPath path.join(SKILLS_DIR, SKILLS.md); return fs.readFileSync(indexPath, utf-8); } // 根据任务关键词检索技能 function findRelevantSkills(task, allSkills) { const keywords task.toLowerCase().split(/\s/); return allSkills.filter(skill { const triggerText skill.triggers.join( ).toLowerCase(); return keywords.some(kw triggerText.includes(kw)); }); } // 解析单个技能文件 function parseSkill(filePath) { const content fs.readFileSync(filePath, utf-8); const match content.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/); if (!match) return null; const meta {}; match[1].split(\n).forEach(line { const [key, ...rest] line.split(:); if (key rest.length) meta[key.trim()] rest.join(:).trim(); }); return { meta, body: match[2] }; } // 主流程注入技能目录 相关技能 function buildContext(task) { const index loadSkillIndex(); const allSkills fs.readdirSync(SKILLS_DIR, { recursive: true }) .filter(f f.endsWith(.md) f ! SKILLS.md) .map(f parseSkill(path.join(SKILLS_DIR, f))) .filter(Boolean); const relevant findRelevantSkills(task, allSkills); return # 技能目录\n${index}\n\n# 相关技能\n${relevant.map(s s.body).join(\n\n)}; } console.log(buildContext(process.argv[2] || ));这个脚本虽然简单但把核心逻辑讲清楚了目录常驻、技能按需。你可以把它接到你的工具链里比如做成一个命令每次开新任务时跑一下把输出粘贴给 AI。4.3 验证技能是否生效的方法技能装好了怎么确认它真的生效了我有一套三步验证法。第一步是目录验证让 AI 复述它看到了哪些技能如果它能准确说出技能名和描述说明目录注入成功。第二步是触发验证给一个明确命中触发词的任务看 AI 是否按技能规范执行。比如触发词里有“写组件”你就说“帮我写一个按钮组件”看它是否遵循了组件技能里的规范。第三步是反例验证故意给一个技能里明确禁止的写法看 AI 会不会纠正你。比如技能里写了“不要用 any”你就写一段带 any 的代码让它 review看它是否指出问题。这三步走下来基本能定位问题出在哪一环。目录验证失败说明注入机制有问题触发验证失败说明触发词写得不好反例验证失败说明技能内容约束力不够。我每次新增技能都会跑一遍这三步虽然麻烦但省心。5. 技能设计与维护中的常见坑与排查技巧5.1 技能不生效的五大原因技能写了但 AI 不遵守这是最高频的问题。我把踩过的坑整理成一张速查表你对照排查现象可能原因排查方法解决方式AI 完全不知道有这技能目录未注入或路径错误让 AI 复述技能列表检查注入脚本路径和权限AI 知道技能但不触发触发词不匹配手动用触发词测试补充同义触发词AI 触发了但内容不对技能正文太模糊检查正文是否可执行改成具体规范加反例多个技能冲突优先级未设置查看命中技能列表设置 priority 字段技能时灵时不灵上下文被挤占检查 token 占用精简技能或改按需注入这张表里触发词不匹配是最隐蔽的。因为 AI 可能“理解”了技能但没“激活”它表现就是它知道规范但没主动用。我的经验是触发词要覆盖“用户视角”的说法而不是“开发者视角”的说法。比如技能叫db-migration但用户可能说“改数据库”“加字段”“建表”这些都要列进触发词。5.2 技能粒度怎么把握技能写得太粗一个技能包罗万象AI 抓不住重点写得太细一个技能只讲一件事技能数量爆炸检索和维护都累。我的经验法则是一个技能对应一类任务而不是一个动作。什么叫一类任务比如“写 React 组件”是一类任务它包含命名、props 设计、样式组织、测试等多个动作这些动作放在一个技能里是合理的因为它们总是同时出现。而“给变量命名”是一个动作单独成技能就太细了应该作为“代码风格”技能的一部分。判断粒度是否合适有个简单测试如果两个技能总是被同时加载就该合并如果一个技能里有两部分内容从不一起用就该拆分。我早期把前端所有规范塞一个技能结果写 CSS 的时候被一堆状态管理的规范干扰后来拆成三个技能命中率和准确率都上来了。5.3 技能库的版本管理与团队协作技能库一旦超过一个人维护版本管理就必须规范。我的做法是技能库独立成 Git 仓库而不是塞在业务项目里。这样好处有三一是技能可以跨项目复用二是技能变更历史清晰三是团队成员可以订阅技能库更新。团队协作时我建议设一个技能 Review 流程。新增或修改技能走 Pull Request至少一个人 review。Review 的重点不是文字优美而是触发词是否覆盖足够、规范是否可执行、有没有和现有技能冲突。我见过团队里两个人各写了一个“代码风格”技能内容还互相矛盾AI 加载后直接精神分裂。有了 Review 流程就能提前发现这种冲突。另外技能库要有变更日志。每次修改技能在CHANGELOG.md里记一笔写清楚改了什么、为什么改。这个习惯在排查“为什么 AI 行为变了”的时候特别有用因为很可能是某次技能更新导致的。6. 进阶玩法让技能库自己进化6.1 从 AI 对话中自动提取技能技能库维护最大的成本是“写”而最好的技能来源其实是你和 AI 的对话本身。我现在的做法是每次和 AI 协作解决了一个有代表性的问题就回头看看对话里有没有值得沉淀的规范。如果有就把它提炼成技能。这个过程可以半自动化。比如你可以写一个脚本定期扫描你的 AI 对话记录找出那些你反复纠正 AI 的点。反复纠正意味着 AI 默认行为不符合你的预期这正是技能该覆盖的地方。我统计过我技能库里超过一半的技能都来自“同一个错误我纠正了三次以上”的场景。提炼的时候有个技巧不要照搬对话原文要抽象成规范。对话里你说的是“这里别用 var用 const”抽象成技能就是“变量声明一律用 const需要重新赋值时用 let禁用 var”。抽象后的规范适用范围更广不会局限于当时那个具体场景。6.2 技能的组合与继承当技能多起来之后组合和继承能大幅减少重复。组合是指一个技能可以引用其他技能比如“React 组件”技能可以依赖“代码风格”和“测试规范”技能。继承是指技能可以有基础版和项目定制版项目版继承基础版再覆盖部分内容。实现组合靠前面说的dependencies字段实现继承我建议用命名约定加覆盖机制。比如基础技能叫code-style项目定制版叫code-stylethis-project加载时如果存在定制版就优先用定制版否则用基础版。这个机制需要你的注入脚本支持但实现起来不复杂就是在检索时做一次优先级判断。我实测下来组合和继承能把技能库的维护成本降低一半以上。因为通用规范只维护一份项目差异只写差异部分改通用规范时所有项目自动受益。6.3 技能效果的量化评估技能到底有没有用不能靠感觉要有数据。我建议跟踪两个指标首次命中率和纠正率。首次命中率是指 AI 第一次执行任务就符合技能规范的比例纠正率是指需要你手动纠正的比例。这两个指标一升一降就说明技能在起作用。收集数据的方法很简单每次 AI 输出后你心里打个分符合规范记 1不符合记 0一周统计一次。我坚持记了一个月发现首次命中率从最初的 40% 提升到了 75%这个提升主要来自触发词的优化和技能正文的具体化。没有数据的时候我根本不知道哪次修改是有效的。需要提醒的是不要追求 100% 命中率。AI 不是确定性系统技能是提高概率而不是保证结果。我的经验是命中率到 80% 左右就很好用了再往上投入产出比急剧下降。剩下的 20% 靠人工 review 兜底这才是健康的协作模式。7. 我个人的一些实操体会技能库这东西最大的价值不在于“技术多先进”而在于逼你把隐性知识显性化。我以前很多规范都在脑子里觉得“这还用说吗”但 AI 不知道新人也不知道。写技能的过程其实就是一次自我梳理很多模糊的地方写着写着就清晰了。另一个体会是从小处着手。别一上来就想建一个覆盖全流程的技能库那只会让你半途而废。先写三个技能用一周感受一下效果再决定要不要继续。我见过太多人兴致勃勃建了五十个技能结果一个都没用起来因为维护成本超过了收益。最后分享一个我常用的小技巧给技能写“使用示例”。在技能正文末尾加一段“示例场景”描述这个技能在什么情况下怎么用。这段内容对 AI 理解技能意图帮助很大尤其是那些触发词比较抽象的。比如error-handling技能末尾我写了“示例当用户要求给某个 API 加错误处理时按本技能规范输出”AI 看到这个示例后命中准确率明显提升。这个技巧成本极低但效果立竿见影值得一试。