How to Ensure Cross-Harness Compatibility Between Claude Code, Codex, and Cursor

Cross-harness compatibility is achieved by maintaining parallel skill directories—skills/ as the canonical source, .agents/skills/ for Codex, and .cursor/skills/ for Cursor—while leveraging the harness-optimizer agent to automate synchronization and prevent functional drift.

In the affaan-m/everything-claude-code repository, contributors must ensure that custom skills work identically across Claude Code, OpenAI Codex, and Cursor. This requires strict adherence to a three-tier directory structure where the master skill definition in skills/ serves as the single source of truth for all other harness-specific subsets.

The Three-Tier Directory Architecture

Cross-harness compatibility relies on a specific filesystem layout that separates the canonical implementation from harness-specific subsets. Each AI assistant loads skills from a dedicated path, necessitating parallel maintenance of three identical skill collections.

Master Source in skills/

The canonical implementation lives under skills/<skill-name>/SKILL.md. This directory contains the source of truth that all other harnesses derive from. When creating a new skill, you must first establish it here with proper frontmatter including name, description, and origin fields.

Codex Harness Path (.agents/skills/)

Codex loads skills from a hidden .agents/skills/ directory, referenced via agents/openai.yaml. According to the repository source code, Codex cannot read from the master skills/ directory directly, requiring you to manually copy or reference skills into this subset location.

Cursor Harness Path (.cursor/skills/)

Cursor expects its skill collection under .cursor/skills/. Like Codex, Cursor maintains an isolated subset that must stay synchronized with the master source to ensure functional parity across different AI coding assistants.

Step-by-Step Cross-Harness Workflow

When adding or updating a skill, follow this propagation sequence documented in CONTRIBUTING.md under the Cross-Harness and Translations section:

1. Add the skill in skills/: Create skills/<skill-name>/SKILL.md with complete implementation and metadata. This step establishes the authoritative version.

2. Copy to Codex: Execute cp -R skills/<skill-name> .agents/skills/<skill-name> and ensure the entry appears in agents/openai.yaml. Codex reads exclusively from the hidden .agents/ tree.

3. Copy to Cursor: Execute cp -R skills/<skill-name> .cursor/skills/<skill-name>. Cursor requires the skill to exist in its dedicated subdirectory.

4. Keep subsets in sync: Whenever the master skill changes, repeat steps 2-3 or run the harness-optimizer agent to propagate updates automatically.

5. Test in each harness: Run validation commands—/skill-health, /quality-gate, or equivalent—in Claude Code, Codex, and Cursor to verify the skill loads without errors and maintains functional parity.

Automating Synchronization with the Harness Optimizer

Manual copying creates risk of subset drift. The repository provides a harness-optimizer agent defined in agents/harness-optimizer.md that detects missing or stale subset files and suggests the required copy operations.

After editing a master skill, run the optimizer to synchronize automatically:

/optimize-harness my-example

This command outputs the specific copy operations performed and reports any synchronization failures, ensuring .agents/skills/ and .cursor/skills/ reflect the current state of skills/.

Practical Implementation Examples

Adding a New Skill Across All Harnesses

When creating my-example, establish it in the master location then propagate to both harness subsets:

# 1️⃣ Create the master skill

mkdir -p skills/my-example
cat > skills/my-example/SKILL.md <<'EOF'
---
name: my-example
description: Demonstrates cross-harness handling
origin: ECC
---

# My Example Skill

...
EOF

# 2️⃣ Propagate to Codex

cp -R skills/my-example .agents/skills/my-example

# Update agents/openai.yaml if required

# 3️⃣ Propagate to Cursor

cp -R skills/my-example .cursor/skills/my-example

Updating Existing Skills with Automation

After modifying the master skill, use the optimizer instead of manual copying:

# Commit changes to master

git add skills/my-example/SKILL.md
git commit -m "feat(skills): update my-example"

# Run the optimizer to sync subsets

/optimize-harness my-example

Verification Commands for Each Harness

Validate cross-harness compatibility by testing skill loading in each environment:

# Claude Code

claude-code /skill-health my-example

# Codex (via GitHub CLI integration)

gh run --repo affaan-m/everything-claude-code codex-verify my-example

# Cursor

cursor-cli skill-list | grep my-example

Successful execution across all three commands confirms the skill is properly synchronized and accessible to Claude Code, Codex, and Cursor users.

Summary

• Maintain three parallel skill collections: master in skills/, Codex subset in .agents/skills/, and Cursor subset in .cursor/skills/.
• Use agents/openai.yaml to register skills for the Codex harness.
• Leverage the harness-optimizer agent (agents/harness-optimizer.md) to automate synchronization and prevent drift.
• Always test in each harness using /skill-health or equivalent commands to verify functional parity.
• Reference the Cross-Harness and Translations section in CONTRIBUTING.md for authoritative workflow details.

Frequently Asked Questions

What happens if I update only the master skill without copying to subsets?

If you modify skills/<skill-name>/SKILL.md without propagating to .agents/skills/ or .cursor/skills/, Codex and Cursor will continue using stale versions, causing inconsistent behavior across harnesses. The harness-optimizer agent detects this drift by comparing checksums between master and subset files.

Can I use symbolic links instead of copying directories?

While symbolic links technically work, the repository workflow in CONTRIBUTING.md recommends physical copies to ensure each harness receives an isolated, version-locked snapshot. This prevents cascading failures if the master skill receives breaking changes that require staged rollouts across different AI assistants.

How does the Codex harness know which skills to load?

Codex reads the manifest defined in agents/openai.yaml, which maps skill names to their locations under .agents/skills/. Even if the directory exists, the skill will not load unless explicitly declared in this YAML configuration file.

Where is the harness-optimizer agent defined?

The optimizer logic resides in agents/harness-optimizer.md. This agent can be invoked via the /optimize-harness slash command to automatically detect subset drift, perform required copy operations from skills/ to .agents/skills/ and .cursor/skills/, and report synchronization status.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}