1. superpowers到底是什么从一个痛点说起如果你一直在用 Codex CLI 这类终端里的 AI 编程助手大概率已经遇到过这种情况同一个项目里让 AI 改数据库表结构它每次都从零开始问“你的表结构是什么”想让 AI 统一输出日志格式你得在 prompt 里反复粘贴规范项目里新来了同事AI 对他写的代码风格一无所知。说白了大模型没有“项目记忆”每次对话都是“初次见面”。这正是 superpowers 这个项目要解决的问题。superpowers 是一套为编程 Agent目前主要面向 OpenAI Codex CLI后续社区也在往其他 CLI 移植设计的“技能增强系统”。它通过给 Agent 挂载结构化的技能包skills、长期备忘memories、子代理agents和自定义命令commands让 AI 助手真正“记得住”你的项目规矩、“学得会”你的团队规范而不是每次对话都靠临时抱佛脚。这个项目在 GitHub 上开源后社区热度上升很快也是因为“给 AI 装技能”这件事切中的是每个重度 AI 编程用户的真实痛点。如果你符合下面任一情况这个项目值得花半小时研究一是天天用 Codex CLI 写代码已经受够了重复解释项目背景二是团队里有统一的开发规范git 提交格式、数据库迁移方式、代码风格想让 AI 默认遵守三是对“Agent 技能”这类新概念好奇想知道 Claude Code 里的 Skills 机制在 Codex 生态里怎么落地。文章后面所有操作我都基于实际安装测试过的流程来写命令和代码都验证过你可以直接照着复现。2. 设计思路拆解为什么是“技能包”而不是又一个框架2.1 这套体系的核心四个零件组成一个“增强回路”superpowers 不是一个大而全的框架它更像一套“插件协议”把增强能力拆成了四个互相咬合的零件Skills技能一段段带目录的说明文档。每个技能是一个文件夹里面有 SKILL.md 作为主说明书告诉 AI“在什么场景下、按什么步骤做某件事”。比如你写一个叫database-migration的技能里面写明“本项目改表结构必须走 migration 文件禁止直接改 schema”。Memories备忘短期记忆和长期记忆的合集。短期记忆存在memory/目录下的文本里会随对话更新长期记忆通过“归档”archive机制沉淀成项目级或全局级的行为准则。Agents子代理你可以预设多个“专业角色”比如“代码评审员”“测试用例生成器”“依赖分析员”。主 Agent 遇到对应场景时可以把子任务委派出去得到结果后再整合。Commands命令自定义斜杠命令本质上是把一段高频 prompt 固化成快捷键。比如/commit命令让 AI 自动按你团队的提交信息规范生成 commit message。这套结构很像什么像给 AI 装了一套“操作系统”——Skills 是安装的软件Memories 是用户配置和缓存Agents 是后台服务Commands 是快捷键。这四个零件互相配合才形成完整闭环而不是一个孤立的“模板库”。2.2 为什么没人早点做这件事大模型记忆机制的先天短板要理解 superpowers 的设计动机得先明白大模型对话的“失忆”本质每次调用 API模型都是无状态的它能看到的一切来自你当前会话里贴进去的上下文。Codex CLI 这类工具之所以让人又爱又恨就是因为它把“会话延续”做到了极致——自动读取文件、自动把历史信息塞回上下文——但面对大型项目上下文窗口终究有限不可能把整个项目的规范和历史都塞进去。所以这个项目最聪明的设计在于不是想办法“扩展上下文”而是“管理上下文”。它把规范、流程、偏好这些长期不变的信息沉淀成磁盘上的文件Skills 和 Memories只在需要时按需加载。你写表结构相关任务时AI 才去读database-migration技能你执行提交操作时它才去加载 commit 规范。这跟人脑的记忆机制其实是一个道理——不是把所有东西都记在“工作记忆”里而是把长期知识存进“硬盘”用的时候再调出来。2.3 和手写 prompt 模板的本质区别可能有朋友会说这不就是把 prompt 存成文件用的时候引用一下吗我自己写个~/.codex/prompts/commit.md不也一样区别在于三层。第一层是主动发现——superpowers 的 skills 会自动匹配当前任务AI 读到用户指令时会先去翻技能目录判断哪个技能合适而不是等你手动指定第二层是分层记忆——短期备忘会被自动更新、积累到一定程度会自动归档成长期规范这是一个动态演化过程静态 prompt 做不到第三层是组合复用——技能之间可以互相引用一个frontend-dev技能可以挂靠code-review子代理一个/commit命令可以触发“读取记忆 → 执行检查 → 生成提交信息”三步流程这些组合逻辑静态模板很难优雅实现。3. 实操准备从安装到跑通第一个技能3.1 安装 superpowers 到 Codex CLI前提条件你已经装好了 Codex CLI 并完成 OpenAI 账号认证。superpowers 的安装方式很直接官方推荐使用codex的扩展机制在项目目录下运行curl -sSL https://raw.githubusercontent.com/grapeot/superpowers/main/scripts/install.sh | bash这个脚本会做几件事克隆 superpowers 仓库到~/.codex/superpowersmacOS/Linux 默认路径把skills、agents、commands目录链接到 Codex CLI 的配置目录同时写一份建议的config.toml配置。装完后运行codex输入/help看看有没有出现superpowers相关的命令列表有就说明挂载成功。注意如果你用的是 Windows 环境脚本里的路径是基于 Unix 的。建议在 WSL 里跑或者手动把仓库 clone 下来后把三个目录复制到对应的 Codex 配置位置效果一样。3.2 理解配置文件agent 启用与指令注入安装完成之后最关键的一步是确认 Codex CLI 的配置文件里确实引用了 superpowers 的指令。这个项目之所以“装上就能用”是因为 Codex CLI 支持在配置里定义“额外系统指令”和“命令目录”。我的~/.codex/config.toml里这样写的# 把 superpowers 的 AGENTS.md 注入到每次会话 [project] instructions_files [ ~/.codex/superpowers/AGENTS.md ] [commands] enabled true directory ~/.codex/superpowers/commandsinstructions_files这个字段是核心它让 Codex 每次启动时自动把AGENTS.md的内容当作系统指令的一部分。AGENTS.md里面写了什么呢它告诉 Codex“如果用户的任务涉及某个技能请先去对应目录读 SKILL.md如果任务需要请使用 superpowers 提供的工具来更新记忆”。这样一来技能和命令的“发现机制”就自动生效了。3.3 写第一个技能给自己项目定制“数据库迁移规范”光说不练假把式我们现场做一个技能。场景你的项目里有个约定——所有数据库表结构的变更必须写 migration 文件不能直接手改数据库。AI 之前经常犯错现在给 AI 立个规矩。第一步创建技能目录mkdir -p ~/.codex/superpowers/skills/db-migration第二步写SKILL.md# Database Migration Skill ## 适用场景 当用户要求修改数据库表结构、新增表、修改字段、添加索引时必须使用本技能。 ## 执行步骤 1. 先在项目的 migrations/ 目录下查看现有 migration 文件的命名规范。 2. 参照最新一个 migration 的文件名格式通常是 YYYYMMDDHHMMSS_description.sql新建一个新的 migration 文件。 3. 在 migration 文件中用 SQL 写出表结构变更语句。 4. 更新 migrations/README.md在变更记录表中追加一行写明变更时间和内容。 5. 不要直接修改数据库或 schema.sql 主文件。如果项目使用 ORM同步更新对应的 model 定义文件。 ## 注意事项 - 如果用户明确要求“快速改一下数据库不用写 migration”也要拒绝并说明项目规范。 - migration 文件必须可重复执行如果存在破坏性变更如删表需要先备份数据。 - 如果项目使用 Flyway 或 Prisma按对应工具的约定执行但流程同上。第三步让 Codex “看见”这个技能。技能目录建好之后只要你在对话里说“帮我加个字段”Codex 就会因为AGENTS.md的指示去翻skills目录找到db-migration然后把SKILL.md的内容读到上下文里。这里有个小技巧技能说明文件里的“适用场景”一定要写得足够具体最好用“当用户要求……时”这种触发句式AI 的匹配准确率会大幅提升。我第一次写技能时场景写得太模糊“关于数据库的事”结果 AI 在纯查询类任务里也去读了一遍技能浪费了不少上下文。3.4 写一个自定义命令把“提交规范”变成斜杠命令技能解决“AI 做事情对不对”的问题命令解决“你让 AI 干活快不快”的问题。比如我团队要求 commit message 必须带feat:、fix:、docs:前缀还要引用 Jira 单号。每次手打这段 prompt 太累用 superpowers 的 commands 机制固化一下。在~/.codex/superpowers/commands/commit.md里写# 按团队规范生成 commit message 请按以下步骤执行 1. 运行 git status 和 git diff --stat了解本次改动涉及的文件和大致内容。 2. 根据改动类型选择前缀新功能用 feat:修复用 fix:文档用 docs:重构用 refactor:测试用 test:。 3. 在前缀后加上当前分支对应的 Jira 单号从分支名提取格式如 JIRA-123。 4. 总结改动内容生成一条简洁的 commit message不要超过 50 个字符。 5. 直接输出建议命令不要自动执行。配置好之后你在 Codex CLI 里输入/commitAI 就会自动走完上面五步。这也是我觉得 superpowers 最“爽”的地方——把高频但重复的固定流程变成快捷键省去每次手打一长串 prompt 的时间。4. 核心功能深入备忘机制、子代理调用与协作场景4.1 备忘机制是怎么“进化”的从短期记忆到长期契约很多人没注意到 superpowers 对 memories 的处理其实是它最有想法的部分。短期备忘short-term memory存放在memory/目录下的 Markdown 文件里AI 在对话过程中发现“用户不喜欢用 TypeScript 的 enum喜欢用 union type”这类偏好时可以主动写入短期备忘。随着对话推进短期备忘不断积累当某个备忘被多次确认、或者 AI 判断它足够稳定时就会触发“归档”archive——把它写入项目级长期规范文件project_registry.md或全局级文件。你可以把短期备忘理解成“印象”长期备忘理解成“契约”。印象很容易改变一见如故可能三分钟就改观契约则是白纸黑字的共识不能随便推翻。这套设计好在哪里好在它解决了“AI 记错东西”的问题——短期备忘写错了随时能改一旦进入长期规范就相当于签了合同是严格约束。实操中怎么利用这个机制我的做法是项目刚启动时所有规范都以短期备忘形式让 AI 记录用一两周之后定期review一下短期备忘把真正有效的沉淀成长期规范把过时的删掉。让 AI 判断归档节点比自己手动维护规范文档省力得多。4.2 子代理Agents把任务拆给“专业团队”superpowers 的 agents 机制可以理解为内置了多个“专家分身”——比如code-reviewer代码评审员、debugger调试专家、dependency-analyzer依赖分析员。当主 Agent 觉得任务需要专业视角时它可以把子任务分配给对应子代理子代理返回结果后主 Agent 再综合处理。我实测最有用的场景是代码评审。过去让 Codex 直接“review 一下代码”它往往泛泛而谈说些“代码可读性良好”“建议增加注释”之类的废话。有了子代理之后code-reviewer会按预设的评审清单逐项检查安全性有没有 SQL 注入风险、性能有没有 N1 查询、可维护性有没有魔法数字、测试覆盖关键路径有没有单测。每一类问题给出具体行号和修改建议。这种结构化的 review质量完全不一样。子代理的配置也很简单在agents/code-reviewer.md里定义角色、职责、评审维度和输出格式即可。重点在于“输出格式”——你必须规定子代理的返回格式比如“问题列表 行号 建议修复代码”这样主 Agent 才能高效整合结果。我第一次配置时没写输出格式子代理返回一大段散文主 Agent 还要二次提炼体验很差。4.3 团队场景一套技能全家桶还是各自为战superpowers 的目录结构天然支持“团队复用”。你可以把一份配置好的skills、commands、AGENTS.md提交到 Git 仓库团队其他人 clone 下来后安装脚本会自动链接。这意味着团队规范可以像代码一样管理——有版本有 diff有人 review。我见过一个团队这么玩他们把完整的superpowers配置放进 monorepo 的根目录里面每个技能对应一个模块的开发约定前端组件怎么写、后端接口怎么定义、数据库 migration 流程是什么。新人入职那天clone 代码库、装上 Codex CLI、跑一遍安装脚本AI 助手就自动“学会了”团队所有规矩而不是靠两周的入职培训慢慢积累。这里有个关键建议团队级技能和全局级技能要分开。我自己的~/.codex/superpowers/skills里放的是通用技能比如“如何写清晰的中文提交信息”“如何优雅处理 Markdown 表格”项目仓库里的skills目录放项目专属规范比如“必须使用 pnpm”“禁止直接改数据库结构”。两层分开的好处是跳槽或者换项目时通用技能跟随你的全局配置走不需要每次重新建。5. 常见问题与排查技巧实录5.1 为什么装了技能AI 完全不理我这是最常见的坑90% 的情况是发现机制没生效。所谓发现机制就是 Codex 判断“当前任务该读哪个技能”的过程——它依赖AGENTS.md里的指示。如果你没把AGENTS.md挂到config.toml的instructions_files里或者链接路径写错AI 根本不知道有技能这回事自然也用不上。排查三步走先确认~/.codex/superpowers/AGENTS.md存在再确认config.toml里instructions_files路径正确最后在 Codex 对话里直接问“你有哪些可用技能”让它列出目录看看。如果它列出内容为空大概率是路径配置有问题。5.2 技能文件写了很多但 AI 总是“读不完”或“读取顺序不对”技能目录里文件多了之后AI 会在一个任务里试图读取多个技能上下文被塞得满满当当反而影响回答质量。我踩过这个坑给小程序项目一次写了六个技能页面开发、接口调用、状态管理、兼容性、性能优化、埋点实际一个改密任务触发了两三个技能的读取上下文瞬间膨胀。解决办法是给技能分级高频通用技能比如“项目代码风格”保留场景专用技能比如“上架审核注意事项”设置为弱触发——在 SKILL.md 开头写“仅当用户提到‘上架、审核、隐私政策’等关键词时才读取”。控制技能数量和触发条件本质上是管理 AI 的“注意力”这才是用好这套系统的核心能力。5.3 安装了最新版本但新技能不起作用superpowers 更新比较快如果你在旧版本基础上新增技能可能会遇到“目录在但 AI 不认”的情况。原因多半是AGENTS.md里列出的技能索引没有更新。这个文件里有所有技能目录的清单新增技能后要确认它被索引到。最简单的做法重新跑一次安装脚本或者手动更新AGENTS.md里的技能列表。5.4 命令失效了查查目录前缀优先级如果你自己定义了命令比如~/.codex/commands/和 superpowers 的commands/并存注意同名命令的优先级。Codex CLI 通常按目录顺序加载先加载的优先。所以如果你之前自己写过一个/commit命令可能覆盖掉 superpowers 的同名命令。解决方式很直接删掉旧命令或者给新命令改个名字比如/supercommit。这个细节容易忽略我遇到过两次“为什么我改了 commands 不生效”最后都是这个问题。5.5 没有 GitHub Copilot 那种“自动补全”的体验有朋友问这玩意儿和 Copilot 的自动补全有什么区别本质上是两个不同层级的工具。Copilot 做的是“token 级别的补全”——你输入一半代码它帮你续写superpowers 做的是“任务级别的编排”——你下达一个任务它按预设流程调动技能和子代理完成。前者是“手指”后者是“大脑”。实际使用中我通常是两个一起开Copilot 负责在编辑器里快速补全样板代码Codex superpowers 负责在终端里处理跨文件的重构任务、写测试、做 code review。两者不冲突互补性很强。5.6 常用问题速查表现象大概率原因解决方案AI 不读取任何技能配置里没有挂载AGENTS.md在 config.toml 的 instructions_files 里加上路径只触发部分技能技能触发条件写得太宽泛在 SKILL.md 开头明确使用场景和关键词技能读到但内容无效SKILL.md 结构不清晰按“适用场景-执行步骤-注意事项”三段结构重写命令不生效同名命令被覆盖或路径错误检查 commands 目录优先级和 yaml frontmatter更新的技能没生效技能索引未更新重新运行安装脚本或手动更新 AGENTS.md上下文快速爆满一次性读取过多技能精简技能数量设置更精确的触发条件子代理返回格式混乱没有规定输出格式在子代理定义里明确输出结构列表行号建议6. 经验总结这套“技能系统”该怎么用才最省力我个人用下来的体会是superpowers 最关键的使用心法就一句话技能要少而精规范要写清楚触发词要具体。少而精是为了不让 AI 在“该读哪个技能”上纠结也别浪费上下文规范要写清楚是因为 AI 对模糊描述的执行力远低于对你的清晰步骤——它只会忠实执行你的流程流程不清晰它就自己发挥触发词具体是为了让“发现机制”快速命中正确的技能文件。还有一个很多人忽视的点技能文档也得维护。项目规范会变技能内容就得跟着改。我的做法是把技能文档当成代码来管理——每次改动走 review改动历史留在 Git 里。时间久了这套技能库本身就成了团队的“知识库”AI 不仅是写代码工具更是团队文化的载体。如果你刚开始接触别急着一次写一堆技能。先装好 superpowers跑通一两个简单的比如 commit 规范、数据库迁移规范体验一下“AI 自动按规矩办事”的感觉再逐步扩展。等你积累了自己的技能库你会发现换项目、带新人这些事情都轻松了一大截。