Superpowers 与 Codex Harness：冲突分析与治理提示词

Superpowers 和 Codex 可以同时运行，冲突主要发生在工作方式上，而不是代码运行时。Superpowers 通过 Skill 规定需求澄清、设计、计划、TDD、子 Agent、评审和分支收尾；Codex Harness 与项目级 AGENTS.md 也在管理其中一部分流程。

对缺少工程规范的项目，Superpowers 能快速补齐开发纪律。对已经有 Issue、分支策略、CI、验收契约和 Agent 协作规则的仓库，整套启用容易形成重复审批、重复文档和两套编排。更合适的做法通常是停用全局路由和通用编排，保留 TDD、系统化排障、验证和独立评审等单项能力。

判断是否冗余，不应只看插件大小或 Skill 数量。关键是它是否重复管理了 Harness 和项目已经拥有的职责。

先确定每层负责什么

Agent 工程可以拆成四层：

flowchart TB H[Harness<br/>指令优先级 权限 工具调用 计划 子 Agent 沙箱] P[Project Governance<br/>AGENTS md 架构边界 Issue 分支 CI 验收契约] S[Skill<br/>TDD 排障 评审 发布等任务方法] T[Tool<br/>Shell Git MCP 浏览器 图像生成] H --> P P --> S S --> T

Harness 负责执行机制，包括权限、工具、计划状态、子 Agent 和隔离环境。项目治理负责仓库规则，包括模块边界、分支策略、验证命令和完成标准。Skill 提供某类任务的方法。Tool 执行具体操作。

Skill 的触发范围越广，越接近 Harness。只在排查故障时加载的调试 Skill 边界清楚；要求所有回复前先调用、统一决定审批和收尾方式的 Skill，已经开始参与全局调度。

可以用三个问题判断它是否越界：

1. 是否改变了所有任务的执行顺序；
2. 是否覆盖项目已有的授权和交付规则；
3. 是否建立了新的长期事实源。

沿着这三个问题，再看 Superpowers 的具体行为，重叠位置会比较清楚。

Superpowers 在哪里与 Codex 重叠

全局 Skill 路由

Codex 使用渐进式加载。启动时只读取 Skill 的名称、描述和路径，匹配任务后再加载完整 SKILL.md。官方文档还说明，初始 Skill 目录有上下文预算；数量过多时，描述会被缩短，部分 Skill 可能被省略。

这套机制依赖准确的 description。Superpowers 6.3.0 的 using-superpowers 又增加了一层全局规则：只要某个 Skill 有较小概率适用，就应在回复、提问或行动前调用。

这种设计提高了 Skill 的触发率，也让简单任务更容易进入完整流程。对于已经具备 Skill 匹配和计划能力的 Harness，额外的全局路由收益有限。

固定的批准门禁

brainstorming 要求创造性工作先形成设计并获得批准，边界清楚的小改动也要暂停等待。

安全模型、公共协议和数据迁移需要先确认方案。用户已经明确授权的局部修复，则未必需要再增加一轮批准。是否暂停应由风险、歧义和影响范围决定，而不是由"是否属于创造性工作"统一决定。

这里的重叠在于：Harness 已经根据权限和操作风险决定何时请求确认，项目也可能定义高风险变更的评审流程。再叠加固定批准门禁，会增加无效往返。

平行文档事实源

Superpowers 默认把设计和计划写进专用目录。没有文档制度时，这比只保留聊天记录可靠；已有 ADR、Roadmap 和 Issue 治理的仓库则可能出现重复：

• 架构结论同时存在于 ADR 和 Skill 设计稿；
• Issue 与计划文件分别记录进度；
• 临时执行步骤被当成长期事实；
• 插件移除后，正式文档仍引用专用路径。

Skill 可以辅助生成设计和计划，但稳定结论应进入项目原有的事实源。会话计划只服务本次执行，不承担长期治理。

通用子 Agent 与 worktree 编排

Codex 已经提供子 Agent 的创建、追加任务、中断和等待，也支持 worktree 隔离。官方建议优先把子 Agent 用于独立、读密集的任务；写密集并行会增加 token、协调和冲突成本。

Superpowers 同时提供并行派发、子 Agent 开发和 worktree Skill。问题不在于这些原则错误，而在于通用流程会携带自己的项目假设。

例如，Superpowers 6.3.0 的 worktree 流程检测到 package.json 后会运行 npm install，但有些仓库只允许指定版本的 pnpm。它的 subagent-driven development 倾向于为每个任务派一个 fresh implementer，让多个实现 Agent 顺序写入当前分支；有些项目则要求每个编辑 Agent 使用独立 branch、worktree 和文件 owner。

并行判断可以由 Skill 提供，实际调度应交给当前 Harness；依赖安装、分支和文件所有权必须服从项目规则。

通用验证与分支收尾

Superpowers 的 verification Skill 要求在声明完成前运行能够证明结果的命令。这项原则值得保留，但具体证据应由项目定义。

真实项目可能分别要求 lint、类型检查、契约测试、安全测试、Consumer canary、制品来源和宿主验收。一个通用 test suite 无法替代这些证据。

分支收尾也有同样的问题。Superpowers 提供本地合并、创建 PR、保留分支等选项；部分仓库则规定默认分支只能通过 MR 合入，并要求核对 pipeline、squash、远端分支和 worktree 状态。通用 Skill 只能提供原则，不能覆盖项目交付契约。

按职责决定保留还是停用

Superpowers 内部既有全局流程，也有单项方法。两类 Skill 的侵入性差异很大。

维度	低侵入	高侵入
触发范围	显式调用或窄语义匹配	每次会话或所有开发任务
控制范围	提供一种任务方法	决定计划 审批 调度和收尾
产物范围	写入用户指定的产物	自动建立平行事实源
Harness 假设	使用当前工具能力	固化具体工具协议
可逆性	删除目录即可退出	项目依赖专用命令和路径
项目适配	服从 AGENTS 和 CI	用通用流程覆盖仓库规则

systematic-debugging 和 verification-before-completion 主要提供单项方法，通常可以保留。using-superpowers、通用 worktree 和完整开发编排会影响整个会话，更适合按项目决定是否启用。

因此，处理方式不必是完整保留或全部删除。可以先把 Skill 分为三类：

• 保留：排障、TDD、验证、独立评审等窄方法；
• 改写：方法有效，但触发过宽或写入位置不符合项目治理；
• 停用：重复管理 Harness 编排、审批和分支生命周期。

完成分类后，还需要判断替代方案怎样避免再次变成完整方法论。AIHero 提供了一个适合对照的设计。

从完整方法论转向按需 Skill

AIHero 和 mattpocock/skills 更接近可选择的技能集，而不是默认接管研发流程。其相对低侵入来自三个设计。

只安装需要的 Skill

安装器允许按 Skill 选择，不要求一次引入完整工作流。Skill 数量会影响目录预算和匹配准确率，只安装存在稳定使用场景的能力，更容易保持触发边界。

区分显式调用与自动匹配

该仓库区分 user-invoked 和 model-invoked Skill。grill-with-docs、ask-matt 等编排入口设置为显式调用；TDD 等 Skill 则使用较窄的描述匹配对应任务。

这不代表没有副作用。显式调用 /implement 后，仍可能执行实现、测试、评审和提交；model-invoked Skill 也会自动加载。它的特点是未调用时影响较小，调用后仍可执行完整流程。

文件可审查，更新由用户触发

安装后的 Skill 是普通文件，可以审查、修改和删除。更新需要主动执行，不会静默改变工作流。

文件形式只解决可见性和退出成本。描述过宽仍会频繁触发，脚本仍可能执行高影响操作。低侵入还需要窄触发和明确授权。

从 Superpowers 裁剪到这类按需 Skill 后，还要解决分发问题：同一份 Skill 能否被不同 Harness 稳定发现。如果每个产品维护一套副本，触发规则很快会再次漂移。

用共享目录解决跨 Harness 发现

Cursor 会扫描：

• .agents/skills/
• .cursor/skills/
• ~/.agents/skills/
• ~/.cursor/skills/

它还兼容 .codex/skills 和 .claude/skills。Codex 官方文档列出的共享位置则是项目级 .agents/skills 和用户级 ~/.agents/skills，不会反向扫描 ~/.cursor/skills。

因此，只放在 ~/.cursor/skills/<skill-name>/ 的 Skill，Cursor 能看到，Codex 看不到。这是目录发现规则不对称，不是 Skill 内容有问题。

个人跨 Agent 使用的 Skill，适合统一放到 ~/.agents/skills/；团队、远程 Agent 和 CI worker 需要使用的 Skill，应进入仓库的 .agents/skills/ 并纳入版本控制。Cursor 官方文档也说明，本机用户目录不会自动复制到 Cloud Agent、远程 SSH 或 worker。

迁移时按以下顺序处理：

1. 将 Skill 移到 ~/.agents/skills/<skill-name>；
2. 检查目录名、name 和 description；
3. 新开 Codex 会话确认加载；
4. 在 Cursor 中确认同一份 Skill 可见；
5. 删除旧的 Cursor 专属副本。

不要在 ~/.cursor/skills 和 ~/.agents/skills 各留一份。Cursor 会扫描两个目录，重复 Skill 可能同时出现，也会产生版本漂移。

只允许显式执行的 Skill，还需要提供不同 Harness 的触发元数据。Cursor 支持：

disable-model-invocation: true

Codex 支持在 agents/openai.yaml 中设置：

policy:
  allow_implicit_invocation: false

核心 SKILL.md 保持共享，产品特定的触发配置只做薄适配。

用审计决定保留 改写还是停用

直接卸载会漏掉三类依赖：插件注册的 hook 或工具、计划中的 REQUIRED Skill、正式文档对专用目录的引用。比较稳妥的顺序是先只读盘点，再处理文档耦合，最后停用插件。

审计至少要覆盖：

1. 插件注册了哪些 Skill、hook、MCP 和脚本；
2. 每个 Skill 的触发条件、写入位置和外部副作用；
3. AGENTS.md、CI、Issue 和文档是否已有对应规则；
4. 当前计划是否要求使用某个 Skill；
5. 移除后哪些工程纪律需要迁入项目事实源。

完成盘点后，可以按以下规则决策：

• Harness 已有同等能力，Skill 只复制工具用法：停用；
• 项目已有更精确规则，Skill 可能覆盖它：停用或改写；
• Skill 提供独立专业方法，且触发范围窄：保留；
• Skill 会写文件或执行外部动作，但触发是隐式的：改为显式调用；
• 文档已经依赖 Skill 专用路径：先迁移有效结论，再移除。

这类审计不必依赖 Agent 自由发挥。把事实源、输出格式和禁止动作写进提示词，结果会更稳定。

可直接使用的治理提示词

下面的提示词分别用于盘点、裁剪、迁移和发现问题。执行写操作前，建议先运行只读审计。

审计 Skill 与 Harness 的职责重叠

请只读审计当前项目的 Agent 指令体系，判断已安装 Skill 是否与 Harness 和项目治理重叠。

先读取并列出：
1. 当前 Harness 已提供的计划 权限 子 Agent worktree 验证和线程能力
2. 全局与项目级 AGENTS.md 及其优先级
3. 已安装 Plugin 和 Skill 的名称 版本 description 触发策略 hook MCP 脚本和写入路径
4. 项目中的 Issue 分支 CI 验收和文档事实源

对每个 Skill 输出：
- 它解决的具体任务
- 显式触发还是隐式触发
- 会读取什么 写入什么 执行什么
- 与 Harness 的重叠点
- 与项目规则的冲突点
- 建议保留 改写 停用或移除
- 结论依据的文件路径和行号

严格区分事实 推论和建议。不要修改文件 不要卸载插件 不要创建分支 不要执行外部写操作。

把宽泛 Skill 改成低侵入 Skill

请审查并改写 <skill-path>，目标是让它只处理一个明确任务，不承担全局编排。

要求：
1. description 写清何时使用 何时不使用
2. 删除每次会话 所有任务 必须优先调用等全局触发语义
3. 项目 AGENTS.md CI 和正式文档始终优先
4. 不自动创建平行的 spec plan 或状态事实源
5. 涉及发布 部署 消息 Git 写操作和删除时只允许显式调用
6. 将 Harness 特定工具用法移入薄适配文件
7. 保留该 Skill 独有的方法 检查表 模板和验证原则

先输出改写前后的职责边界和触发示例，再提交最小 diff。不要顺带修改其他 Skill。

移除方法论插件前做解耦

请为移除 <plugin-name> 做只读 preflight，暂时不要卸载或删除任何文件。

检查：
- Plugin manifest 中的 skills hooks MCP scripts 和 agents
- package manifest lockfile CI scripts AGENTS.md 中的直接依赖
- 计划文档中的 REQUIRED SUB-SKILL 或专用命令
- ADR Roadmap 架构文档中对插件专用目录的引用
- 插件生成但仍承载有效项目事实的文件

输出三个清单：
1. 可直接移除的运行时能力
2. 必须先迁移的项目事实
3. 建议保留或替换的单项 Skill

为每个迁移项给出目标 owner 和验证方法。没有明确授权前不要卸载 不要删除 不要改写历史。

排查 Cursor 与 Codex 的 Skill 发现问题

请只读审计本机和当前仓库的 Skill 发现路径，解释为什么指定 Skill 在 Cursor 可见但在 Codex 不可见。

检查：
- .agents/skills 和 ~/.agents/skills
- .cursor/skills 和 ~/.cursor/skills
- .codex/skills 和 ~/.codex/skills
- SKILL.md 是否存在 目录名与 name 是否一致 description 是否有效
- 是否存在同名副本 符号链接或版本漂移
- 当前会话是否需要重启后重新发现

给出一个单一事实源方案：
- 个人跨 Agent Skill 优先放 ~/.agents/skills
- 团队和远程 Agent Skill 优先放仓库 .agents/skills
- 产品特定触发策略使用薄适配配置

先报告现状和精确迁移目标。不要复制或移动文件，等确认后再执行。

为项目生成 Skill 治理规则

请根据当前仓库已有事实源，起草一段可加入 AGENTS.md 的 Skill 治理规则。

规则需要覆盖：
- Skill 只能补充任务方法 不能覆盖项目授权和交付契约
- 长期事实必须进入 ADR Roadmap Issue 测试或正式文档
- 高影响 Skill 必须显式调用
- 并行编辑必须遵守项目 branch worktree 和 owner 规则
- 完成声明必须给出命令 产物和证据等级
- 新增 Skill 前检查标准能力 已有 Skill 触发重叠和退出路径

只输出候选规则及每条规则解决的问题，不直接修改 AGENTS.md。

提示词适合完成一次盘点或改造，不能替代长期治理。确认有效后，应把稳定规则写入 AGENTS.md、CI 和正式文档，让后续 Agent 不必重复推断。

参考资料

• OpenAI：Build skills
• OpenAI：Codex as a platform
• OpenAI：Custom instructions with AGENTS.md
• OpenAI：Subagents
• Cursor：Agent Skills
• Superpowers 6.3.0：using-superpowers
• Superpowers 6.3.0：brainstorming
• Superpowers 6.3.0：finishing-a-development-branch
• AIHero：Skills for Real Engineers
• mattpocock/skills 源码仓库
• AIHero：调用策略约定
• AIHero：grill-with-docs Skill
• AIHero：TDD Skill