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

> Ensure cross-harness compatibility between Claude Code, Codex, and Cursor by managing parallel skill directories and using the harness-optimizer agent for seamless synchronization.

- Repository: [Affaan Mustafa/everything-claude-code](https://github.com/affaan-m/everything-claude-code)
- Tags: best-practices
- Published: 2026-03-20

---

**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`](https://github.com/affaan-m/everything-claude-code/blob/main/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`](https://github.com/affaan-m/everything-claude-code/blob/main/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`](https://github.com/affaan-m/everything-claude-code/blob/main/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`](https://github.com/affaan-m/everything-claude-code/blob/main/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:

```bash
/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:

```bash

# 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:

```bash

# 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:

```bash

# 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`](https://github.com/affaan-m/everything-claude-code/blob/main/agents/openai.yaml)** to register skills for the Codex harness.
- Leverage the **harness-optimizer agent** ([`agents/harness-optimizer.md`](https://github.com/affaan-m/everything-claude-code/blob/main/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`](https://github.com/affaan-m/everything-claude-code/blob/main/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`](https://github.com/affaan-m/everything-claude-code/blob/main/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`](https://github.com/affaan-m/everything-claude-code/blob/main/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`](https://github.com/affaan-m/everything-claude-code/blob/main/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.