1. 从“superpowers”说起这套 agentic skills framework 到底在解决什么问题第一次看到 “superpowers” 这个词是在几个做 AI 编程工具链的朋友群里。有人甩了一句“想要安装 superpowers”底下立刻有人接“你是说 Claude Code 那套 skills 框架吧”。聊了十几分钟我才反应过来大家嘴里的 superpowers 并不是某个单独的软件而是一套围绕agentic skills framework构建的软件开发方法论——它把 Claude Code、Codex CLI 这类命令行智能体当作“执行手”把可复用的技能模块当作“招式库”让一个原本只会聊天的模型变成能真正动手改代码、跑命令、查文档的工程搭档。这套东西的核心价值用一句话概括把“提示词工程”升级成“技能工程”。以前我们用 Claude Code 或者 Codex CLI靠的是每次现写 prompt写得好模型就干得好写得烂就翻车。而 superpowers 的思路是把常见任务比如初始化项目、写测试、重构函数、生成提交信息沉淀成一个个独立的 skill 文件智能体在执行时按需加载不用每次从零描述。这就像你带徒弟不是每次口头教一遍而是给他一本操作手册遇到什么场景翻到哪一页。适合谁来参考三类人最该看一是已经在用 Claude Code 或 Codex CLI但总觉得“它怎么老是不按我想的来”的开发者二是想把 AI 编程工具接进团队工作流却不知道怎么标准化的技术负责人三是刚接触 agentic 工具链想找一个能落地的切入点的新手。这篇文章我会从框架设计思路、核心技能拆解、完整实操流程、常见坑排查四个维度把 superpowers 这套方法论掰开揉碎讲清楚中间会穿插 Claude Code 安装、Codex CLI 命令、VS Code 配置这些热搜里高频出现的实操细节。提示本文提到的所有工具和命令均以官方公开文档和社区常见实践为准涉及账号、订阅、地区可用性等问题请以你实际环境为准本文不做任何绕过限制的讨论。2. 框架整体设计与思路拆解为什么是“技能”而不是“提示词”2.1 从提示词堆砌到技能模块化的必然性早期用 Claude Code 的人应该都有体会你打开终端输入claude然后开始跟它对话。第一次让它“帮我写个 React 组件”它写得不错第二次让它“帮我写个带表单验证的 React 组件”也还行但到第十次你发现每次都要重复描述项目结构、代码风格、测试框架、命名规范累不说还容易漏。这就是典型的提示词堆砌困境——所有上下文都靠你临时喂模型没有稳定的“记忆锚点”。superpowers 这套 agentic skills framework 的设计出发点就是解决这个困境。它把“你希望智能体怎么做事”从对话里抽出来写成结构化的 skill 文件。每个 skill 包含三部分触发条件什么场景下用、执行步骤具体怎么做、验收标准做完什么样算对。智能体在接到任务时先匹配 skill再按步骤执行。这样一来你的经验就固化下来了不用每次重复。我打个生活化的比方提示词像你每次做饭都凭感觉放盐技能像你写了一张菜谱贴在厨房墙上。前者依赖状态后者依赖流程。状态会波动流程可复用。2.2 为什么选 Claude Code 和 Codex CLI 作为执行层热搜词里反复出现 Claude Code 和 Codex CLI不是偶然。这两个工具是目前命令行智能体里工具调用能力比较成熟的两类代表。Claude Code 的优势在于它对终端命令的直接执行、对文件系统的读写、以及对 VS Code 的深度集成Codex CLI 的优势在于命令语义清晰/compact、/model、/resume这些指令让会话管理很顺手。superpowers 作为技能框架本身不绑定具体执行器。你可以把它理解成一套“接口规范”Claude Code 能接Codex CLI 也能接。选哪个取决于你的场景如果你主要在 VS Code 里写代码希望智能体能直接改文件、跑测试Claude Code 的 VS Code 插件体验更顺如果你习惯纯终端操作喜欢用/resume恢复会话、用/compact压缩上下文Codex CLI 更对味。这里有个关键设计取舍技能文件用 Markdown 而不是 JSON 或 YAML。原因是 Markdown 对模型友好模型读 Markdown 的指令遵循率明显高于读结构化配置。而且 Markdown 方便人写、方便版本控制、方便 diff。你把它放进 Git 仓库团队每个人都能改改完提交下次智能体加载的就是最新版。2.3 技能加载机制背后的上下文经济学很多人没意识到智能体的上下文窗口是稀缺资源。你把所有技能一次性塞进去模型反而会“注意力涣散”。superpowers 的做法是按需加载智能体先读一个索引文件通常叫SKILLS.md或skills/index.md里面列出所有技能的名称和一句话描述当任务匹配到某个技能时再读取该技能的完整文件。这个机制的好处我用一个数字说明。假设你有 20 个技能每个平均 800 字全量加载就是 16000 字差不多占掉 Claude 上下文窗口的一大块。按需加载的话索引可能只有 500 字单个技能 800 字总共 1300 字省了 90% 以上。省下来的上下文留给实际代码和任务描述模型的表现会明显更稳。注意索引文件的描述要写得“可匹配”。比如“用于生成单元测试”就比“测试相关”好因为智能体是靠语义匹配来选技能的描述越具体选错概率越低。3. 核心细节解析与实操要点技能文件怎么写才有效3.1 一个合格 skill 文件的四段式结构我踩过几次坑之后总结出一个 skill 文件最稳的结构是四段适用场景、前置条件、执行步骤、验收清单。少一段都会出问题。适用场景写清楚“什么时候用这个技能”。比如“当用户要求为新函数补充测试时”就比“写测试”精确。前置条件写“执行前需要确认什么”比如“确认项目已安装 Jest 且 package.json 里有 test 脚本”。执行步骤是核心要写成有序列表每步一个动作动作要具体到命令级别。验收清单写“做完后检查哪几项”比如“测试文件命名符合*.test.ts规范”“至少覆盖正常路径和边界路径”。我见过有人把 skill 写成一大段散文模型读完不知道从哪下手。也见过有人写成纯命令列表缺少判断逻辑遇到异常就卡住。四段式的好处是模型先判断场景对不对再检查条件满不满足然后按步骤走最后自检。这跟人类工程师做事的方式是一致的。3.2 触发词设计让智能体“该出手时才出手”技能框架最容易翻车的地方是误触发。你写了一个“重构函数”的技能结果模型在你只是想“看看这个函数干嘛的”时候也去重构那就麻烦了。解决办法是在技能文件开头加一段触发词与反触发词。触发词是“出现这些词才考虑用”比如“重构”“提取方法”“消除重复”。反触发词是“出现这些词就别用”比如“解释”“阅读”“只是看看”。这看起来简单但实际效果差别很大。我实测下来加了反触发词之后误触发率能降一半以上。另外触发词要覆盖同义表达。用户可能说“重构”也可能说“整理一下这个函数”还可能说“这段代码太乱了帮我理理”。你不可能穷举但可以把最常见的三五种写进去。剩下的靠模型语义理解兜底。3.3 技能之间的依赖与组合真实项目里任务很少是单一的。比如“给这个模块加一个新功能”可能涉及“读代码”“写实现”“写测试”“更新文档”四个技能。superpowers 的处理方式是允许技能声明依赖在技能文件里写一行depends_on: [read-code, write-test]智能体加载主技能时会把依赖技能一起加载。但这里有个坑依赖不能成环。A 依赖 BB 又依赖 A模型会陷入循环加载。我的做法是画一张依赖图确保是 DAG有向无环图。如果两个技能确实互相需要就抽一个公共技能出来让两者都依赖它。组合技能的时候还要注意执行顺序。通常的顺序是先读后写先实现后测试先测试后文档。这个顺序不是死的但偏离太多容易出问题。比如你先写文档再写实现文档大概率跟实现对不上。3.4 版本管理与团队协作技能文件放 Git 里管理这点前面提过。但具体怎么管有几个细节值得说。第一每个技能一个文件不要把所有技能塞一个巨型文件否则 diff 的时候看不清改了啥。第二技能文件加 frontmatter写上作者、最后更新时间、适用版本范围。第三改动技能要写 commit message说明为什么改比如“修复 write-test 技能在 Vitest 项目下误用 Jest 命令的问题”。团队协作时建议指定一个“技能维护者”角色负责审核技能改动。因为技能是给智能体看的写得太随意会导致模型行为不稳定。审核要点就三条触发条件是否清晰、步骤是否可执行、验收标准是否可检验。4. 实操过程与核心环节实现从零搭一套可用的技能框架4.1 环境准备Claude Code 与 Codex CLI 的安装配置先说 Claude Code 的安装。macOS 和 Ubuntu 下官方推荐的方式是通过包管理器安装装完之后在终端输入claude就能进入交互界面。Windows 用户注意热搜里出现过“claude code 由于与64位版本的windows不兼容”这类问题通常是环境变量或终端模拟器的问题建议用 WSL2 或者官方推荐的终端环境。VS Code 用户可以直接装 Claude Code 的 VS Code 插件装完后在设置里配置好路径就能在编辑器里直接调用。Codex CLI 的安装类似装完后常用命令有这么几个/compact用来压缩当前会话上下文防止太长/model用来切换模型/resume用来恢复之前的会话。删除 Codex CLI 的话用对应的包管理器卸载命令即可配置文件一般在用户目录下的隐藏文件夹里卸载后手动清理一下更干净。提示如果你在配置过程中遇到“your organization has disabled claude subscription access”这类提示说明你的账号权限或订阅状态有问题这属于账号层面的事本文不展开。你需要做的是确认自己的账号状态而不是找绕过办法。关于用本地模型热搜里有人问“claude code 调用 lmstudio 的本地模型”。这个思路是可行的核心是把本地模型的 API 端点配置成兼容格式然后在 Claude Code 的配置里指向本地地址。但要注意本地模型的能力和云端模型有差距复杂任务上表现会打折扣适合做简单补全和格式化。4.2 目录结构设计让技能“找得到、读得快”我推荐的目录结构是这样的project-root/ skills/ index.md read-code.md write-test.md refactor.md commit-message.md .claude/ config.jsonskills/放所有技能文件index.md是索引.claude/放 Claude Code 的配置。Codex CLI 的话配置目录名不同但结构类似。索引文件index.md的写法很关键。我一般写成表格技能名触发场景文件路径read-code需要理解现有代码结构时skills/read-code.mdwrite-test需要为新功能或修复补测试时skills/write-test.mdrefactor需要消除重复、提取方法时skills/refactor.md这样模型一眼就能扫完匹配效率高。表格比列表好因为列对齐后信息密度更高。4.3 编写第一个技能以“生成提交信息”为例我拿“生成提交信息”这个技能做示范因为它足够简单又能体现完整结构。适用场景当用户完成一次代码改动需要生成符合 Conventional Commits 规范的提交信息时。前置条件确认当前目录是 Git 仓库且git status有未提交改动。执行步骤运行git diff --staged查看暂存区改动如果没有暂存内容运行git diff查看工作区改动。分析改动涉及的文件类型和改动性质判断是 feat、fix、refactor、docs、test 中的哪一类。提取改动的核心意图用一句话概括不超过 50 个字符。如果改动涉及多个不相关的内容提示用户拆分提交。按type(scope): subject格式生成提交信息。验收清单type 是 feat/fix/refactor/docs/test/chore 之一。subject 用祈使句首字母小写结尾不加句号。如果改动超过 3 个文件且涉及不同模块已提示拆分。这个技能写完之后我实测了十几次生成的提交信息基本不用改。关键就在于验收清单把格式约束住了模型不会自由发挥。4.4 把技能接进日常工作流技能写好了怎么让它真正用起来我的做法是在项目根目录放一个CLAUDE.md或AGENTS.md里面写一句话“执行任务前先读取 skills/index.md匹配到技能后按技能文件执行。”这样每次启动 Claude Code 或 Codex CLI它都会先加载索引。然后就是在实际任务中观察。第一次用可能会发现技能没被触发或者触发了但步骤没走完。这时候不要急着改技能先看模型的执行日志判断是触发词没匹配上还是步骤描述有歧义。我一般会迭代两三轮技能就稳定了。还有一个技巧给技能加“示例”段落。在技能文件末尾附一个输入输出示例模型看到示例后执行准确率会明显提升。比如“生成提交信息”技能里附一个feat(auth): add login validation的例子模型就知道格式长什么样。5. 常见问题与排查技巧实录那些文档里不会写的坑5.1 技能不触发或误触发怎么排查技能不触发九成是触发词写得太窄。比如你写“重构”用户说“优化一下结构”模型就匹配不上。解决办法是把触发词扩展成一组同义表达并且在索引文件的描述里也带上这些词。误触发的话先看反触发词够不够。我遇到过一次用户说“帮我看看这个函数”结果模型触发了重构技能。后来在重构技能里加了反触发词“看看”“解释”“阅读”问题就解决了。还有一个隐蔽原因索引文件太长。如果索引超过 2000 字模型扫的时候会漏。解决办法是索引只保留技能名和一句话描述详细内容放各自文件里。5.2 上下文被技能占满导致任务失败这是按需加载没做好的典型症状。表现是模型执行到一半开始“胡言乱语”或者忘记前面的步骤。排查方法是看当前会话的上下文占用如果技能内容占了超过一半就要优化。优化手段有三个一是拆分大技能把 800 字的技能拆成两个 400 字的二是把技能里的示例移到单独文件需要时再加载三是用/compactCodex CLI或对应的压缩命令清理历史对话。5.3 技能执行结果不稳定的三种典型情况第一种步骤描述有歧义。比如“检查代码质量”这种描述模型不知道检查什么。改成“检查是否有未使用的变量、是否有超过 50 行的函数、是否有重复代码块”就具体了。第二种验收标准不可检验。比如“代码要优雅”这没法检验。改成“函数不超过 30 行、命名符合 camelCase、无 console.log 残留”就可检验了。第三种技能之间冲突。两个技能对同一件事给了不同指令模型会随机选一个。解决办法是定期审查技能库发现冲突就合并或明确优先级。5.4 常见问题速查表问题现象可能原因排查动作解决方向技能不触发触发词太窄检查用户输入与触发词匹配度扩展同义触发词技能误触发缺反触发词复现误触发场景补充反触发词执行到一半卡住上下文超限查看上下文占用拆分技能或压缩会话结果格式不对验收标准模糊检查验收清单改成可检验的条目两个技能打架指令冲突对比技能文件合并或定优先级模型忽略技能索引未加载检查 CLAUDE.md 配置确认索引读取指令5.5 我踩过的三个印象最深的坑第一个坑技能文件用了太多专业缩写。我写了个技能叫“DRY 重构”结果模型不知道 DRY 是 Dont Repeat Yourself执行时完全跑偏。后来改成“消除重复代码重构”就正常了。教训是技能是给模型看的不是给人类专家看的能用大白话就别用缩写。第二个坑技能里写了“根据情况选择”。这种描述对模型来说等于没写因为它不知道“情况”是什么。后来我改成“如果函数超过 50 行提取子函数如果参数超过 4 个封装成配置对象”模型就能执行了。教训是把判断条件写死别让模型自己悟。第三个坑技能更新后没通知团队。有次我改了一个测试技能的框架配置从 Jest 换成 Vitest但没告诉同事。结果同事用旧技能跑测试一直报错。后来我们约定技能改动必须在群里说一声并且 commit message 写清楚影响范围。教训是技能是团队资产改动要同步。6. 技能框架的扩展玩法与个人经验6.1 把技能框架接到其他工具链上superpowers 这套思路不局限于 Claude Code 和 Codex CLI。我试过把它接到其他支持工具调用的智能体上核心改动只有一处把技能加载的触发指令换成对应工具的配置方式。比如有的工具用system prompt注入有的用配置文件有的用插件机制。只要能让智能体在任务开始前读到索引文件这套框架就能跑。热搜里有人问“飞书如何连接 claude code”这属于把智能体接进协作工具的场景。思路是类似的在飞书机器人里配置一个命令入口收到指令后转发给 Claude Code 执行再把结果返回。技能框架在这里的作用是保证执行的一致性不管从哪个入口进来行为都一样。6.2 技能库的长期维护策略技能库用久了会膨胀需要定期清理。我的做法是每季度做一次“技能审计”统计每个技能过去三个月的触发次数触发次数为零的考虑删除或合并触发次数高但经常出错的优先优化触发次数高且稳定的保持不动。另外技能文件要加“最后验证时间”。因为工具链会更新模型会升级半年前好用的技能现在可能不适用了。我一般每两个月把核心技能跑一遍确认还能用。6.3 关于“要不要用第三方 API”的取舍热搜里有人问“第三方 api 使用技巧”也有人问“使用 cc switch 接入 deepseek v4、qwen、glm 等模型”。我的看法是技能框架本身不依赖特定模型但模型能力会影响技能执行效果。复杂技能比如多步重构建议用能力强的模型简单技能比如格式化提交信息用便宜模型就行。切换模型的时候要注意技能的兼容性。不同模型对指令的遵循程度不同同一个技能在 A 模型上跑得好在 B 模型上可能跑偏。解决办法是在技能文件里标注“适用模型范围”切换时先小范围测试。6.4 我个人的使用体会用这套框架大半年最大的感受是它把 AI 编程从“碰运气”变成了“可管理”。以前用 Claude Code每次都要祈祷它今天状态好现在有了技能库行为稳定多了团队新人上手也快因为技能文件本身就是最好的操作手册。最后分享一个小技巧给技能文件加一个“失败案例”段落。把你踩过的坑写进去比如“不要在这个技能里用git add .会误加无关文件”。模型读到失败案例后会主动避开这些坑。这个技巧我用了之后技能的一次通过率又提升了一截。