从第一次在同事的终端里看到“superpowers”这个项目到我自己把它完整接入日常开发流程中间踩了不少坑也摸清了不少门道。今天不写那种照抄 README 的流水账就从一个实际使用者的角度聊聊这个项目解决的是什么问题、技能包到底怎么组织、安装和引入过程中最容易在哪几个环节翻车以及最后我自己沉淀下来的一套造技能的方法论。先说结论如果你经常跟代码协作助手打交道或者团队里多人共用一套自动化工作流这个项目值得花半小时认真看一下。它能把你散落在各种文档、提示词、脚本里的“经验碎片”统一成一个个可安装、可复用的技能包让工具真正知道“在你的项目里该怎么干活”。1. 先搞清楚这个项目解决的是哪类痛点1.1 你大概率也遇到过每次进项目都要重新调教一次我最早接触这类技能管理工具起因是一个很现实的麻烦同时维护三四个项目每个项目的技术栈、代码规范、提交规范、测试约定都不一样。A 项目要求 Conventional CommitsB 项目要求单测必须跑完整套才能提 MRC 项目甚至规定所有配置文件里不能出现绝对路径。问题是这些约束写在哪一部分在 README一部分在团队 Wiki一部分在某个同事的聊天记录里。结果就是每次切换项目我都要把这些规则重新“喂”给工具一遍而且喂的方式还是复制粘贴。项目一多粘贴错误、版本过期、口径不一致的情况层出不穷。superpowers 这类项目解决的第一层问题就是把“约束上下文”从人脑和散落文档里抽出来变成项目目录下一个结构化的技能包。工具读到这个包就知道当前项目的规矩是什么。这套思路跟很多编辑器的 rules 机制类似但更强调的是“可安装、可复用、可分享”。1.2 第二层痛点流程型操作没有统一编排除了知识约束日常开发里还有一类工作是“流程型”的。比如提交代码前要跑 lint、更新 changelog、检查敏感信息发布版本前要打 tag、生成 release notes、同步文档。以前我做这些事靠的是自己写的一堆 shell 脚本再配合手打的命令序列。脚本一多管理起来很痛苦有的脚本只服务于特定项目有的脚本又跟版本库绑定换台机器就找不到。superpowers 把这类流程也封装成了技能。一个技能包可以描述“当用户触发 xxx 时依次执行哪几步每一步用什么工具产生什么中间结果”这样操作就从“靠记忆拼命令”变成“触发一个标准动作”。1.3 这个东西不是什么不是编程语言也不是自动化平台需要先泼盆冷水。superpowers 不是让你用一套新语言写业务代码也不像 Jenkins 那种重量级流水线工具。它更像是给“工具 人的协作过程”做了一个轻量级的标准化外壳。我见过不少人第一次接触这个概念下意识把它想复杂了。其实核心模型非常简单技能 一段结构化描述 若干资源文件。描述里写清楚触发条件、执行步骤、输入输出资源文件里放模板、提示词片段或脚本。工具负责识别、加载、按规则执行。理解到这个粒度后面所有的安装和排障都顺了。2. 核心设计拆解技能包到底长什么样2.1 一个技能包的文件构成先看目录结构。拿我项目里一个用于规范 Git 提交信息的技能举例superpowers/ └── skills/ └── git-commit-standard/ ├── skill.yaml ├── SKILL.md └── templates/ └── commit-message.md三个核心文件各司其职skill.yaml 是元数据文件声明技能的 id、名称、版本、适用场景、所需依赖。SKILL.md 是主体说明文件用自然语言加少量标记描述这个技能的使用方式、约束条件和执行步骤。templates 目录放配套资源可以是消息模板、配置文件模板也可以是小型脚本。这个设计的妙处在于它同时照顾了两种读者。工具能读 skill.yaml把技能登记到索引里人或者协作助手能读 SKILL.md理解技能的业务逻辑。资源文件则保证了技能的“自包含性”换环境不会丢东西。2.2 技能的分类知识型、流程型和工具型使用了一段时间后我把自己用到的技能分成了三类分类决定了怎么撰写 SKILL.md类型典型场景说明文件重点示例知识型项目约定、编码规范只写“是什么”和“为什么”git-commit-standard、项目架构说明流程型多步骤、有依赖关系写清楚执行顺序和判断条件release-prep、before-commit工具型调用外部命令或脚本写明入参、出参和错误处理fetch-jira-ticket知识型技能最简单本质上是给工具喂上下文流程型技能需要精确描述步骤不能有歧义工具型技能最考验鲁棒性因为外部命令的失败分支你必须预先想到。我的建议是新手从“知识型”开始练手。第一条技能就做一个简单的、记录团队编码规范的知识包跑通整个安装和引入链路后再碰流程型和工具型这样心智负担最小。2.3 为什么选择 YAML 而不是其他格式用过一段时间后我越来越认可项目采用 YAML 做元数据的决定。JSON 太啰嗦写几行就想加注释但没法加INI 虽然简洁但表达不了分层结构。YAML 的缩进语法在描述嵌套结构时非常舒服而且支持注释这个对团队协作来说太重要了。skill.yaml 我通常这么写id: git-commit-standard name: Git Commit 规范 version: 1.2.0 description: 检查并生成符合 Conventional Commits 规范的提交信息 tags: [git, commit, workflow] triggers: - commit - commit-message templates: - templates/commit-message.md这里有个细节要注意id 一旦定下来尽量别改。工具加载技能时通常用 id 建立索引你改了 id旧索引会变成死链接。版本号可以升id 要稳定。3. 安装与引入从零到第一条技能3.1 安装核心快、静、无多余依赖这是我当时很满意的一点superpowers 的核心运行环境安装起来非常轻。它本质上是一个用脚本实现的加载器不依赖特定的编程语言运行时也不要求你装额外的守护进程。以我熟悉的环境为例安装步骤只有三步下载核心脚本、赋予执行权限、设置环境变量。没有编译过程也不会往系统目录里塞一堆乱七八糟的东西。装完后执行初始化命令它会在当前用户目录下生成一个配置文件夹默认结构如下~/.superpowers/ ├── config.yaml ├── skills/ │ └── builtin/ └── registry/看到没即使你没主动创建任何技能它也会自带一组 builtin 技能用来演示基本能力。我建议新手先别删拿它们对照理解“一个技能包到底应该怎么写”。3.2 引入一个现成技能以社区技能包为例引入技能有两条路径从 Git 仓库直接拉取或者复制到本地技能目录。以拉取一个社区通用的代码评审辅助技能为例命令大致长这样superpowers install gitgithub.com:example/code-review-skill.git执行后工具会克隆仓库把 skill.yaml 里的 id 登记进 registry并自动做一次完整性检查。检查项包括必要文件是否齐全、元数据是否能正常解析、声明的模板文件是否存在。如果你的网络环境不方便走 Git还有更笨但稳定的办法直接把技能文件夹复制到 ~/.superpowers/skills/ 下然后执行扫描命令。工具会扫描目录自动把新技能加入索引。两种方式我都用过个人推荐优先用 Git 方式因为后续拉更新会更舒服。3.3 在会话中真正“用”起来安装只是前提关键是引入。在支持技能语法的前端里引入方式通常是斜杠命令。比如我装完 git-commit-standard 后提交代码前直接输入/use git-commit-standard工具解析到这条指令会做三件事读取 skill.yaml、把 SKILL.md 的内容注入当前协作上下文、根据 triggers 里的定义挂载相关的自动触发规则。这里有一个我初期没意识到、后来觉得特别重要的机制技能不仅可以手动触发还可以按条件自动触发。当你把 commit 这个动作写进 triggers 后只要检测到提交意图比如你打开了提交信息编辑界面相关技能就会自动被拉取。这个进一步减少了“我忘了用技能”的可能。3.4 两条我认为最实用的引路建议第一条引入完技能后一定先检查状态。一条命令就能看到技能列表、版本、启用状态。别相信“应该装好了”要眼见为实。superpowers list第二条技能之间允许有依赖关系。如果你的工作流技能 A 依赖 B 的输出那要在 skill.yaml 里声明 dependency。第一次引入时漏掉声明运行到一半报错“找不到 B 技能的输出”这是很多人踩过的坑。养成先看依赖、再引入的习惯能帮你省很多事。4. 实操排查最容易翻车的五个环节4.1 装了但发现不了目录扫描和命名规范先讲最频繁的问题技能明明放进目录里superpowers list就是扫不到。我之前排查过一次折腾了快半小时最后发现是文件夹命名问题。我建了个目录叫git_commit_standard下划线风格。工具的扫描器默认匹配 kebab-case短横线风格也就是git-commit-standard才符合规范。下划线命名的目录会被当作非标准目录忽略掉。这不是 bug是约定。技能的 id 和目录名最好都遵循 kebab-case不用下划线不用驼峰。解决办法也简单改名重新扫描。4.2 路径含空格或特殊字符操作系统的路径问题几乎人人都遇过。有一次我把技能仓库 clone 到一个带空格的目录里比如/Users/my name/work/...结果技能装载时资源文件路径解析失败模板永远找不到。排查思路先看 registry 里登记的路径再对比实际路径大概率发现空格没转义。轻量框架不会把这种问题都替你处理掉所以在路径安全这件事上最好自己动手规避技能仓库统一放在无空格、无中文、无特殊符号的路径下。这不是歧视是省事。4.3 多个技能相互覆盖优先级冲突当你的技能越来越多优先级问题就暴露了。比如我同时装了团队内部的代码风格技能和社区的通用代码规范技能两个技能都声称对“代码风格”这个场景有发言权后加载的往往覆盖先加载的。官方的设计里技能的优先级由加载顺序决定后加载的优先级高于先加载的。听起来简单但如果你通过不同入口先后加载了一堆技能很容易眼前一团乱。我的建议是能力相近的技能不要重复装。一个场景精挑细选保留一个技能比装五个冲突技能再花时间调整优先级要高效得多。真到了必须调整优先级的场景可以改配置显式声明依赖和冲突关系别依赖隐式顺序。4.4 模板变量不生效转义和注释技能里带模板文件时变量替换是常见的失效点。比如我在 commit-message.md 模板里写了{{branch_name}}结果引入时工具没做替换原样把大括号输出到了提交信息里。原因通常是模板引擎的注释符号和变量分隔符冲突。修改模板时不小心把变量部分注释掉了或者用了中文全角括号替代英文半角括号都会导致解析失效。这种问题不好直接报错因为模板语法本身合法只是匹配不上。所以我自己给模板文件下了条死规矩所有变量必须集中写在模板顶部并在底部附带一份示例值每次改模板都跑一次渲染测试验证变量确实被替换。这条纪律帮我省掉了无数隐蔽的小问题。4.5 权限和跨平台问题最后说一个典型的 Linux/Mac 环境下的坑技能里的可执行脚本没有执行权限。工具型技能经常要调用辅助脚本如果 clone 下来后脚本权限位不对运行时会直接提示 “Permission denied”。我之前有一次给团队分发技能包大家同步了同一个仓库Windows 上跑得好好的同事在 Mac 上跑就报权限错误。排查到最后是 git 拉取时丢失了可执行位。解决分两步本地提权chmod x scripts/xxx.sh根上解决在仓库里显式设置文件模式并在安装文档里写清这一步。千万别假设大家的 git 配置都正确。补充一个综合排查速查表遇到问题先按这个顺序过一遍现象优先检查次要检查扫不到技能目录命名格式registry 索引是否损坏模板变量没替换变量分隔符与注释冲突模板编码是否 UTF-8技能执行报权限错误脚本权限位挂载目录是否只读技能间互相覆盖依赖和优先级声明加载顺序自动触发不生效triggers 是否匹配上下文来源是否被阻断5. 自己造技能一套值回票价的方法论5.1 从需求到技能包我的一次完整实践安装和引入熟练之后造技能是绕不开的一步。因为别人的技能永远不可能完全匹配你的项目场景。拿我最近做的“发布前置检查”技能举例走一遍完整的设计流程。当时的需求每次发版前要检查版本号是否提升、CHANGELOG 是否更新、配置文件里是否有调试残留。以前靠手工检查效率低且容易漏。第一步我把这个需求拆成一个“流程型”技能。它需要三步读取当前版本号、比对上一版本、生成检查报告。每一步之间都有明确的输出和判断。第二步确定边界。它不该做什么不负责真正执行发布只做检查并给出结论。边界清晰技能才不会被滥用。第三步写 skill.yaml 和 SKILL.md。我先把整个流程逻辑写在 SKILL.md 里用 Markdown 的列表语法描述顺序配合if-else形式的自然语言说明分支处理。接着写一个辅助脚本单独负责版本比对输出统一格式的结果。5.2 我对 SKILL.md 内容组织的坚持写说明文件这件事看似简单其实是整个技能包质量的分水岭。我自己有个固定的写作模板# 技能名称 ## 使用场景 什么时候该用什么时候不该用 ## 执行步骤 1. 2. 3. ## 输入 需要哪些参数或上下文 ## 输出 会产出什么结果 ## 异常处理 哪些失败情况需要中止/告警最核心的是“执行步骤”和“异常处理”两块。执行步骤要用断言式的语言比如“检查版本号是否大于仓库内最新标签”而不是“看看版本号变了没”。后者太模糊不同执行者理解可能完全不一样。异常处理要覆盖常见失败分支比如版本比较脚本因为格式不一致无法解析时宁可中止并提示也不要静默通过。静默失败是技能里最害人的东西。5.3 完整示例一个最小可用的技能包写一个最小示例方便你在 10 分钟里跑通全流程。建文件夹skills/ └── check-version-bump/ ├── skill.yaml └── SKILL.mdskill.yamlid: check-version-bump name: 版本号变更检查 version: 0.1.0 description: 检查当前版本号是否在上一版本基础上合规递增 triggers: - pre-releaseSKILL.md# 版本号变更检查 ## 使用场景 发布预览前执行确认版本号已更新且更新符合 SemVer。 ## 执行步骤 1. 从 package.json 或项目配置中读取当前版本号。 2. 对比仓库内最新 git tag 的版本号。 3. 用 SemVer 规则比较新旧版本确认递增且非降级。 4. 将结果写入检查结论存在问题时标记为失败。 ## 输入 当前项目根目录配置。 ## 输出 一个状态结果通过或失败附两个版本号。 ## 异常处理 - 无法读取当前版本号中止提示缺少版本配置文件。 - 无历史 tag跳过对比但提示这是首次发布场景。放到技能目录后superpowers list能扫到它/use check-version-bump就能引入。这整套链路走完你对“技能到底怎么运作”的体感会比读十篇文档都深。5.4 造技能的三个进阶心法第一个心法先服务自己再考虑通用性。我见过团队里一上来就要求每个人都用它结果推进困难。自己先用起来在真实项目里暴露问题、不断迭代版本稳定了再推广阻力会小很多。第二个心法保持技能的单一职责。一个技能解决一件事是底线。把“代码检查 自动修复 生成报告 通知群消息”全塞进一个技能里表面看很全实际上是维护灾难。拆成多个互相配合的小技能反而容易维护。第三个心法版本号要严肃对待。技能会迭代旧版本的使用者可能需要平滑升级。我给自己定了个规范破坏性变更升主版本新增功能升次版本修小问题和文档升补丁版本。这样才能让使用者一眼看出风险等级。5.5 技能包应该放在哪里仓库内还是全局最后聊一个策略问题。技能有两种持久化位置全局用户目录和项目仓库内。全局技能适合个人通用的工作流比如提交信息规范项目仓库内的技能适合绑定项目特有约束比如和某个服务架构相关的代码生成规则。我的建议是“项目优先”。技能如果和业务紧密相关就往项目仓库放跟着代码走新成员 clone 下来就能用。全局技能只放那些不管在哪个项目里都用得上的通用能力。两者职责分明才不会出现“这台机器上有这个技能那台机器上没有”的割裂感。6. 一些使用体会和最后的提醒我的切身感受是这类技能管理工具的价值不是“装一次爽一次”而是积累得越多你的工作流越标准化越不依赖某个人的记忆。一开始数据看起来麻烦等你有了几十个技能包它们相互支撑、彼此调用整个开发流程会变得异常稳定。当然也别忘了它只是工具核心还是你定义规则的能力。技能包永远不能代替你自己思考它更像是把你最靠谱的那套做法固化下来关键时刻不用脑子也能执行到位。如果只给一条最实用的建议我会说现在就给自己建一个最简“知识型”技能哪怕内容只有几句代码规范。跑通从安装、引入、使用到排查的完整循环后面的一切都顺理成章。以后你回顾这个过程就会发现真正稀缺的从来不是工具而是把经验变成可复用资产的习惯。