Harness Configuration
One canonical tree, projected into each harness. Your config repo — a personal,
versioned repository checked out at a stable path, written <config> below — is
the behavioural source of truth. Each harness consumes a projection of it: a
symlink, a generated file, or a native discovery path. Preserve native host
configuration where formats or capabilities genuinely differ.
Resolving <config>
Before anything else, locate the canonical tree: check a conventional location
such as ~/.agents, or an env var like $AGENTS_CONFIG. If neither resolves,
ask the user once and record the answer. If no config repo exists yet, offer
to create one — a fresh versioned repository at a stable path — before
proceeding.
The tooling contract
Two tools you implement once, whatever you name them:
- sync — projects the canonical tree into each host's directories
(symlinks where the format matches, generated files where it does not).
Idempotent; run it after every edit.
- doctor — validates the projections: every shared surface reaches every
harness, no orphaned or hand-edited projections, no credentials or session
state in the shared tree. Non-zero exit on any failure.
Classify the change
| Surface |
Canonical source |
Projection |
| Personal instructions |
<config>/AGENTS.md |
Linked as ~/.claude/CLAUDE.md and ~/.codex/AGENTS.md |
| Personal skills |
<config>/skills/<name>/SKILL.md |
The skills directory is linked into each harness's discovery folder (e.g. ~/.claude/skills, ~/.codex/skills) |
| Repository instructions and skills |
Repo AGENTS.md, .agents/skills/ |
CLAUDE.md and .claude/ compatibility links |
| Repository commands |
.agents/commands/ |
Generated per-harness command skills |
| Repository agents |
.agents/agents/*.md |
Generated host-native agent definitions (e.g. Codex .toml) |
| MCP registrations |
Repo .mcp.json |
Generated host config (e.g. Codex config.toml), plus per-repo overrides under <config>/hosts/<harness>/ |
| Reusable prompts |
<config>/prompts/ |
Each harness's prompt/command mechanism (e.g. slash-command files) |
| Hooks, permissions, UI |
Native host settings |
Keep behaviour equivalent; do not force identical syntax |
The Codex entries illustrate one projection scheme, not stock Codex behaviour.
Note one scoping mismatch: .mcp.json is per-repo while Codex registers MCP
servers globally — your sync tool must decide how to bridge it (namespacing
generated entries, or per-repo overrides).
Process
- If no sync or doctor tooling exists yet, offer to scaffold both from the
classification table before proceeding: sync as a script projecting each
canonical path to its per-harness location, doctor as a script verifying
the projections match canon and that no host directory contains hand edits.
- Read both current projections before changing a host-specific surface.
- Edit the canonical source when the surface is shared — never the projection.
- Keep shared prose model- and harness-neutral. Quarantine unavoidable
differences under
<config>/hosts/<harness>/ or a repository override file.
- Run your sync tool.
- Run your doctor check, then commit and push. Commit promptly — an
uncommitted edit is the only copy that exists and can be lost to a parallel
session overwriting the same files. Commit only after the doctor passes, so
a broken state is never the tip.
- Report what now propagates automatically and any genuine host limitation.
Rules
- Never copy a shared skill into a host directory.
- Never edit a generated projection (command skills, agent definitions, host
config) — change the canonical source and re-run sync.
- Translate host primitives instead of forking a shared file for syntax:
Agent(...) or Task(...) means the current harness's native sub-agent
mechanism; Skill(...) means its native skill loader.
- Never copy credentials, authentication state, sessions, history, caches, or
tokens into the shared tree.
- Preserve host-specific capabilities (e.g. two harnesses whose hooks fire on
the same events but are configured with different syntax). Match information
and workflow, not syntax.
1---2name: harness-config3description: Keep agent configuration — instructions, skills, commands, agents, MCP registrations, hooks, permissions, and reusable prompts — aligned across more than one agent harness (e.g. Claude Code + Codex) from a single canonical config repo. Use when changing personal or repository agent configuration, migrating a workflow between harnesses, diagnosing configuration drift, or asking whether a capability will propagate from one harness to another.4---56# Harness Configuration78One canonical tree, projected into each harness. Your config repo — a personal,9versioned repository checked out at a stable path, written `<config>` below — is10the behavioural source of truth. Each harness consumes a *projection* of it: a11symlink, a generated file, or a native discovery path. Preserve native host12configuration where formats or capabilities genuinely differ.1314## Resolving `<config>`1516Before anything else, locate the canonical tree: check a conventional location17such as `~/.agents`, or an env var like `$AGENTS_CONFIG`. If neither resolves,18ask the user once and record the answer. If no config repo exists yet, offer19to create one — a fresh versioned repository at a stable path — before20proceeding.2122## The tooling contract2324Two tools you implement once, whatever you name them:2526- **sync** — projects the canonical tree into each host's directories27 (symlinks where the format matches, generated files where it does not).28 Idempotent; run it after every edit.29- **doctor** — validates the projections: every shared surface reaches every30 harness, no orphaned or hand-edited projections, no credentials or session31 state in the shared tree. Non-zero exit on any failure.3233## Classify the change3435| Surface | Canonical source | Projection |36| --- | --- | --- |37| Personal instructions | `<config>/AGENTS.md` | Linked as `~/.claude/CLAUDE.md` and `~/.codex/AGENTS.md` |38| Personal skills | `<config>/skills/<name>/SKILL.md` | The skills directory is linked into each harness's discovery folder (e.g. `~/.claude/skills`, `~/.codex/skills`) |39| Repository instructions and skills | Repo `AGENTS.md`, `.agents/skills/` | `CLAUDE.md` and `.claude/` compatibility links |40| Repository commands | `.agents/commands/` | Generated per-harness command skills |41| Repository agents | `.agents/agents/*.md` | Generated host-native agent definitions (e.g. Codex `.toml`) |42| MCP registrations | Repo `.mcp.json` | Generated host config (e.g. Codex `config.toml`), plus per-repo overrides under `<config>/hosts/<harness>/` |43| Reusable prompts | `<config>/prompts/` | Each harness's prompt/command mechanism (e.g. slash-command files) |44| Hooks, permissions, UI | Native host settings | Keep behaviour equivalent; do not force identical syntax |4546The Codex entries illustrate one projection scheme, not stock Codex behaviour.47Note one scoping mismatch: `.mcp.json` is per-repo while Codex registers MCP48servers globally — your sync tool must decide how to bridge it (namespacing49generated entries, or per-repo overrides).5051## Process52530. If no sync or doctor tooling exists yet, offer to scaffold both from the54 classification table before proceeding: sync as a script projecting each55 canonical path to its per-harness location, doctor as a script verifying56 the projections match canon and that no host directory contains hand edits.571. Read both current projections before changing a host-specific surface.582. Edit the canonical source when the surface is shared — never the projection.593. Keep shared prose model- and harness-neutral. Quarantine unavoidable60 differences under `<config>/hosts/<harness>/` or a repository override file.614. Run your sync tool.625. Run your doctor check, then commit and push. Commit promptly — an63 uncommitted edit is the only copy that exists and can be lost to a parallel64 session overwriting the same files. Commit only after the doctor passes, so65 a broken state is never the tip.666. Report what now propagates automatically and any genuine host limitation.6768## Rules6970- Never copy a shared skill into a host directory.71- Never edit a generated projection (command skills, agent definitions, host72 config) — change the canonical source and re-run sync.73- Translate host primitives instead of forking a shared file for syntax:74 `Agent(...)` or `Task(...)` means the current harness's native sub-agent75 mechanism; `Skill(...)` means its native skill loader.76- Never copy credentials, authentication state, sessions, history, caches, or77 tokens into the shared tree.78- Preserve host-specific capabilities (e.g. two harnesses whose hooks fire on79 the same events but are configured with different syntax). Match information80 and workflow, not syntax.
olzn