跪拜 Guibai
← Back to the summary

When Agent Skills Overlap: Auditing Superpowers Against Codex Harness

Superpowers and Codex can run simultaneously; conflicts mainly arise in how they work, not in code execution. Superpowers uses Skills to prescribe requirements clarification, design, planning, TDD, sub-agents, review, and branch wrap-up. Codex Harness and the project-level AGENTS.md also manage part of this process.

For projects lacking engineering discipline, Superpowers can quickly establish development rigor. For repositories that already have issues, branching strategies, CI, acceptance contracts, and agent collaboration rules, enabling the full suite tends to create duplicate approvals, duplicate documentation, and two competing orchestrations. A more suitable approach is usually to disable the global routing and generic orchestration while keeping individual capabilities like TDD, systematic debugging, verification, and independent review.

Judging redundancy should not rely on plugin size or Skill count alone. The key question is whether it duplicates responsibilities that the Harness and the project already own.

First determine what each layer is responsible for

Agent engineering can be broken into four layers:

flowchart TB
  H[Harness<br/>Instruction priority Permissions Tool calls Planning Sub-agents Sandbox]
  P[Project Governance<br/>AGENTS md Architecture boundaries Issues Branches CI Acceptance contracts]
  S[Skill<br/>TDD Debugging Review Release and other task methods]
  T[Tool<br/>Shell Git MCP Browser Image generation]
  H --> P
  P --> S
  S --> T

The Harness is responsible for execution mechanisms, including permissions, tools, plan state, sub-agents, and isolated environments. Project governance is responsible for repository rules, including module boundaries, branching strategies, verification commands, and completion criteria. Skills provide methods for specific types of tasks. Tools execute concrete operations.

The broader a Skill's trigger scope, the closer it sits to the Harness. A debugging Skill loaded only during troubleshooting has clear boundaries; a Skill that requires invocation before every reply and uniformly decides approval and wrap-up methods is already participating in global scheduling.

Three questions can determine whether it oversteps:

  1. Does it change the execution order of all tasks?
  2. Does it override the project's existing authorization and delivery rules?
  3. Does it establish a new long-term source of truth?

Following these three questions and examining Superpowers' specific behaviors makes the overlap clearer.

Where Superpowers overlaps with Codex

Global Skill routing

Codex uses progressive loading. At startup it reads only Skill names, descriptions, and paths; the full SKILL.md is loaded only after a task matches. Official documentation also states that the initial Skill directory has a context budget; when there are too many, descriptions are shortened and some Skills may be omitted.

This mechanism depends on accurate description fields. Superpowers 6.3.0's using-superpowers adds another layer of global rules: whenever a Skill has even a small probability of being applicable, it should be invoked before replying, asking, or acting.

This design increases Skill trigger rates but also pushes simple tasks into a full process. For a Harness that already has Skill matching and planning capabilities, the additional global routing offers limited benefit.

Fixed approval gates

brainstorming requires creative work to first form a design and obtain approval; even small, clearly scoped changes must pause and wait.

Security models, public protocols, and data migrations do need a confirmed plan first. Local fixes that the user has already explicitly authorized may not need an additional round of approval. Whether to pause should be determined by risk, ambiguity, and impact scope, not by a blanket rule of "whether it counts as creative work."

The overlap here: the Harness already decides when to request confirmation based on permissions and operational risk, and the project may define review processes for high-risk changes. Adding a fixed approval gate on top creates unnecessary round-trips.

Parallel document sources of truth

Superpowers defaults to writing designs and plans into a dedicated directory. When there is no documentation system, this is more reliable than keeping only chat history; repositories that already have ADRs, roadmaps, and issue governance may see duplication:

Skills can assist in generating designs and plans, but stable conclusions should enter the project's original source of truth. Session plans serve only the current execution and do not carry long-term governance.

Generic sub-agents and worktree orchestration

Codex already provides sub-agent creation, task appending, interruption, and waiting, and supports worktree isolation. The official recommendation is to prefer sub-agents for independent, read-heavy tasks; write-heavy parallelism increases token, coordination, and conflict costs.

Superpowers simultaneously provides parallel dispatching, sub-agent development, and worktree Skills. The problem is not that these principles are wrong, but that generic processes carry their own project assumptions.

For example, Superpowers 6.3.0's worktree process runs npm install when it detects package.json, but some repositories only allow a specific version of pnpm. Its subagent-driven development tends to dispatch a fresh implementer for each task, having multiple implementation agents write sequentially to the current branch; some projects require each editing agent to use an independent branch, worktree, and file owner.

Parallelism decisions can be informed by a Skill, but actual scheduling should be left to the current Harness; dependency installation, branching, and file ownership must obey project rules.

Generic verification and branch wrap-up

Superpowers' verification Skill requires running commands that can prove the result before declaring completion. This principle is worth keeping, but the specific evidence should be defined by the project.

Real projects may separately require lint, type checking, contract tests, security tests, consumer canaries, artifact provenance, and host acceptance. A generic test suite cannot substitute for these pieces of evidence.

Branch wrap-up has the same problem. Superpowers offers options like local merge, PR creation, and branch retention; some repositories mandate that the default branch can only be merged via MR and require checking pipeline, squash, remote branch, and worktree state. A generic Skill can only provide principles; it cannot cover the project's delivery contract.

Decide to keep or disable based on responsibility

Superpowers contains both global processes and individual methods. The two types of Skills differ greatly in intrusiveness.

Dimension Low intrusion High intrusion
Trigger scope Explicit invocation or narrow semantic match Every session or all development tasks
Control scope Provides a task method Decides planning, approval, scheduling, and wrap-up
Artifact scope Writes to user-specified artifacts Automatically creates parallel sources of truth
Harness assumptions Uses current tool capabilities Hardcodes specific tool protocols
Reversibility Exit by deleting directory Project depends on dedicated commands and paths
Project adaptation Obeys AGENTS and CI Overrides repository rules with generic processes

systematic-debugging and verification-before-completion primarily provide individual methods and can usually be kept. using-superpowers, generic worktree, and full development orchestration affect the entire session and are better enabled or disabled per project.

Therefore, the approach need not be all-or-nothing. Skills can first be classified into three categories:

After classification, the next step is to judge how alternatives can avoid turning back into a full methodology. AIHero provides a design worth comparing.

From full methodology to on-demand Skills

AIHero and mattpocock/skills are closer to a selectable skill set rather than a default takeover of the development process. Their relatively low intrusion comes from three design choices.

Install only the Skills you need

The installer allows per-Skill selection and does not require importing a complete workflow at once. Skill count affects directory budget and matching accuracy; installing only capabilities with stable use cases makes it easier to maintain trigger boundaries.

Distinguish explicit invocation from automatic matching

The repository distinguishes user-invoked and model-invoked Skills. Orchestration entry points like grill-with-docs and ask-matt are set to explicit invocation; Skills like TDD use narrower descriptions to match corresponding tasks.

This does not mean there are no side effects. Explicitly invoking /implement may still execute implementation, testing, review, and commit; model-invoked Skills will also auto-load. The characteristic is that the impact is smaller when not invoked, and a full process can still execute after invocation.

Files are reviewable, updates are user-triggered

Installed Skills are ordinary files that can be reviewed, modified, and deleted. Updates require an active action and will not silently change the workflow.

The file format only solves visibility and exit cost. Overly broad descriptions will still trigger frequently, and scripts may still execute high-impact operations. Low intrusion also requires narrow triggers and explicit authorization.

After trimming from Superpowers to this kind of on-demand Skill, the distribution problem remains: can the same Skill be reliably discovered by different Harnesses? If each product maintains its own copy, trigger rules will quickly drift again.

Solve cross-Harness discovery with a shared directory

Cursor scans:

It is also compatible with .codex/skills and .claude/skills. Codex's official documentation lists shared locations as project-level .agents/skills and user-level ~/.agents/skills, and does not reverse-scan ~/.cursor/skills.

Therefore, a Skill placed only in ~/.cursor/skills/<skill-name>/ is visible to Cursor but not to Codex. This is an asymmetry in directory discovery rules, not a problem with Skill content.

Skills used personally across agents are best placed uniformly in ~/.agents/skills/; Skills needed by teams, remote agents, and CI workers should go into the repository's .agents/skills/ and be version-controlled. Cursor's official documentation also states that local user directories are not automatically copied to Cloud Agents, remote SSH, or workers.

When migrating, process in this order:

  1. Move the Skill to ~/.agents/skills/<skill-name>;
  2. Check the directory name, name, and description;
  3. Open a new Codex session to confirm loading;
  4. Confirm the same Skill is visible in Cursor;
  5. Delete the old Cursor-specific copy.

Do not keep a copy in both ~/.cursor/skills and ~/.agents/skills. Cursor scans both directories; duplicate Skills may appear simultaneously and will cause version drift.

For Skills that only allow explicit execution, different Harnesses also need trigger metadata. Cursor supports:

disable-model-invocation: true

Codex supports setting in agents/openai.yaml:

policy:
  allow_implicit_invocation: false

The core SKILL.md remains shared; product-specific trigger configurations are only thin adaptations.

Use an audit to decide keep, rewrite, or disable

Directly uninstalling will miss three types of dependencies: hooks or tools registered by the plugin, REQUIRED Skills in plans, and formal document references to dedicated directories. A safer sequence is to first do a read-only inventory, then handle document coupling, and finally disable the plugin.

The audit must cover at least:

  1. Which Skills, hooks, MCPs, and scripts the plugin registers;
  2. Each Skill's trigger conditions, write locations, and external side effects;
  3. Whether AGENTS.md, CI, issues, and documents already have corresponding rules;
  4. Whether the current plan requires using a specific Skill;
  5. Which engineering disciplines need to be migrated into the project's source of truth after removal.

After completing the inventory, decisions can follow these rules:

This kind of audit does not need to rely on agent free-form reasoning. Writing the source of truth, output format, and prohibited actions into the prompt produces more stable results.

Governance prompts you can use directly

The prompts below are for inventory, trimming, migration, and problem discovery. Before executing write operations, it is recommended to run a read-only audit first.

Audit Skill and Harness responsibility overlap

Please perform a read-only audit of the current project's agent instruction system to determine whether installed Skills overlap with the Harness and project governance.

First read and list:
1. Planning, permissions, sub-agents, worktree, verification, and threading capabilities already provided by the current Harness
2. Global and project-level AGENTS.md and their priorities
3. Names, versions, descriptions, trigger strategies, hooks, MCPs, scripts, and write paths of installed plugins and Skills
4. Issues, branches, CI, acceptance, and document sources of truth in the project

For each Skill, output:
- The specific task it solves
- Whether triggered explicitly or implicitly
- What it reads, writes, and executes
- Overlap points with the Harness
- Conflict points with project rules
- Recommendation: keep, rewrite, disable, or remove
- File paths and line numbers supporting the conclusion

Strictly distinguish facts, inferences, and recommendations. Do not modify files, do not uninstall plugins, do not create branches, do not execute external write operations.

Turn a broad Skill into a low-intrusion Skill

Please review and rewrite <skill-path> with the goal of making it handle only one clear task without taking on global orchestration.

Requirements:
1. The description must state clearly when to use and when not to use
2. Remove global trigger semantics like every session, all tasks, must invoke first
3. Project AGENTS.md, CI, and formal documents always take priority
4. Do not automatically create parallel spec, plan, or status sources of truth
5. For publishing, deployment, messaging, Git writes, and deletions, allow only explicit invocation
6. Move Harness-specific tool usage into thin adaptation files
7. Keep the Skill's unique methods, checklists, templates, and verification principles

First output the responsibility boundaries and trigger examples before and after the rewrite, then submit a minimal diff. Do not incidentally modify other Skills.

Decouple before removing a methodology plugin

Please perform a read-only preflight for removing <plugin-name>; do not uninstall or delete any files yet.

Check:
- Skills, hooks, MCPs, scripts, and agents in the plugin manifest
- Direct dependencies in package manifest, lockfile, CI scripts, and AGENTS.md
- REQUIRED SUB-SKILL or dedicated commands in planning documents
- References to plugin-specific directories in ADRs, roadmaps, and architecture documents
- Files generated by the plugin that still carry valid project facts

Output three lists:
1. Runtime capabilities that can be directly removed
2. Project facts that must be migrated first
3. Individual Skills recommended to keep or replace

For each migration item, give the target owner and verification method. Do not uninstall, delete, or rewrite history without explicit authorization.

Troubleshoot Skill discovery between Cursor and Codex

Please perform a read-only audit of Skill discovery paths on this machine and the current repository, and explain why a specified Skill is visible in Cursor but not in Codex.

Check:
- .agents/skills and ~/.agents/skills
- .cursor/skills and ~/.cursor/skills
- .codex/skills and ~/.codex/skills
- Whether SKILL.md exists, whether the directory name matches name, whether description is valid
- Whether duplicate copies, symlinks, or version drift exist
- Whether the current session needs a restart for re-discovery

Provide a single source-of-truth plan:
- Personal cross-agent Skills should preferably go in ~/.agents/skills
- Team and remote agent Skills should preferably go in the repository's .agents/skills
- Product-specific trigger strategies use thin adaptation configs

First report the current state and precise migration targets. Do not copy or move files; execute only after confirmation.

Generate Skill governance rules for a project

Based on the current repository's existing sources of truth, draft a Skill governance section that can be added to AGENTS.md.

The rules must cover:
- Skills can only supplement task methods; they cannot override project authorization and delivery contracts
- Long-term facts must enter ADRs, roadmaps, issues, tests, or formal documentation
- High-impact Skills must be explicitly invoked
- Parallel edits must obey the project's branch, worktree, and owner rules
- Completion declarations must give commands, artifacts, and evidence levels
- Before adding a new Skill, check standard capabilities, trigger overlap with existing Skills, and exit paths

Only output candidate rules and the problem each rule solves; do not directly modify AGENTS.md.

Prompts are suitable for completing one inventory or transformation; they cannot replace long-term governance. After confirming effectiveness, stable rules should be written into AGENTS.md, CI, and formal documentation so that subsequent agents do not need to repeatedly infer them.

References