Port agent config

Port Agent Config

Move a project's agent instructions and skills to work with a different coding tool, without breaking what already works for the current one. Two situations, two procedures — check which one applies before doing anything.

Step 0: which situation is this?

Look for a reachable agentharness checkout with tools/generate-*.sh in it:

• This repo itself (agentharness) — the scripts are right here.
• A consumer project where harness-link.sh init ran: readlink a .claude/skills/* entry to find the harness's real path, or look for an agentharness/ submodule, or a durable npm-mode copy.

Found one → Section A. Not found → Section B.

Section A — agentharness-linked: use the real generators

Don't hand-write the target file. Each generator already reuses the exact same source (CLAUDE.md + the skill catalog), is CI-drift-checked against its committed output, and carries the correct caveats — reconstructing its shape by hand is strictly worse and will drift the next time CLAUDE.md changes.

Target tool	Generator	Produces
Codex CLI	tools/generate-agents-md.sh --output AGENTS.md	AGENTS.md
Gemini CLI / Antigravity	tools/generate-gemini-md.sh --output GEMINI.md	GEMINI.md
GitHub Copilot	tools/generate-copilot-instructions.sh --output-dir .	.github/copilot-instructions.md + .github/instructions/*.instructions.md
Kilo Code	tools/generate-kilo-rules.sh --output .kilo/rules/agentharness.md	.kilo/rules/agentharness.md
Cursor	tools/generate-cursor-rules.sh --output-dir .	.cursor/rules/agentharness-router.mdc + one .mdc per skill
OpenCode / Zed	nothing to generate — both read AGENTS.md directly	—
Claude Code	nothing to generate — CLAUDE.md is the hand-authored source	—

Steps:

1. Run the matching command against the target project (see each script's own --help, or docs/INTEGRATION.md's per-platform section when the harness checkout and the target project aren't the same directory).
2. Re-run the project's own content-quality check (tools/verify-content-quality.py here; the consumer's equivalent elsewhere) to confirm the new file isn't silently broken.
3. Tell the user this is a manual step, not auto-wired into init/update (ROADMAP.md's P1-01) — they'll need to re-run it whenever CLAUDE.md or the skill catalog changes.
4. Keep the same caveat every generated file already states: not verified against a live session of the target tool.

Custom subagents (task delegation to a separate agent instance — .claude/agents/*.md — a different mechanism from the routing/skill generators above) have their own set of generators, one per delegation-capable target:

Target tool	Generator	Produces
Codex CLI	tools/generate-codex-agents.sh --output-dir .	.codex/agents/<name>.toml
OpenCode	tools/generate-opencode-agents.sh --output-dir .	.opencode/agents/<name>.md
Cursor	tools/generate-cursor-agents.sh --output-dir .	.cursor/agents/<name>.md (not .cursor/rules/ — that's the skill generator)
Kilo Code	tools/generate-kilo-agents.sh --output-dir .	.kilo/agents/<name>.md
GitHub Copilot	tools/generate-copilot-agents.sh --output-dir .	.github/agents/<name>.agent.md (not .github/copilot-instructions.md/.github/instructions/ — those are the routing/skill generator)
Gemini CLI	tools/generate-gemini-agents.sh --output-dir .	.gemini/agents/<name>.md
Zed	nothing to generate — real subagent delegation exists architecturally, but no confirmed user-facing named-config-file format was found (see docs/CLIENT_COMPATIBILITY.md's custom-agent table)	—

Important limitation, state it every time: none of these six generators port tool/permission scoping (Claude Code's tools: field, Cursor's readonly/is_background, Kilo's permission/ permission.task, Copilot's target/disable-model-invocation/ user-invocable, Gemini's tools/temperature/max_turns) — that vocabulary is unverified per-platform. Ported files carry name/description/model and the body verbatim; tell the user the tool/permission scope needs re-specifying by hand for the target platform.

Section B — no agentharness: hand-port

1. Read the source config in full. Don't summarize from memory — find every file the source tool actually reads.
2. Identify the target's real mechanism: its always-on file (name, location, whether it's read hierarchically or as a single file) and its skill/rule format (Agent Skills' progressive disclosure vs. Cursor's per-file .mdc frontmatter). docs/CLIENT_COMPATIBILITY.md in agentharness is a good reference table even from outside the repo; don't guess if you can check the target tool's own docs instead.
3. Port routing prose near-verbatim, demoting every heading one level so the source's own H1 doesn't collide with the target file's H1 — the same rule every generator here follows (demote_headings() in tools/lib/adapter-common.sh).
4. Port skills without duplicating bodies:
   • Target supports the Agent Skills standard (Codex, Gemini CLI, Antigravity, GitHub Copilot, Zed, Kilo Code, OpenCode all do): point it at the same skills directory instead of re-authoring content, and add only a name+description index to the always-on file.
   • Target has no Agent Skills support (Cursor is the only confirmed case): port each skill individually into the target's native rule format — for Cursor, one .mdc per skill, description copied verbatim, no globs (Agent-Requested activation, not Auto-Attached).
5. State the caveat explicitly: "ported from <source>'s config to <target>'s format; not verified against a live <target> session" — unless the user has actually run it themselves.
6. Custom subagents (task delegation, not skills/instructions) only port meaningfully between tools that both support real delegation with a confirmed config-file format (Claude Code, Codex CLI, OpenCode, Cursor, Kilo Code, GitHub Copilot, Gemini CLI — see docs/CLIENT_COMPATIBILITY.md's custom-agent table); Zed likely has real delegation too but no confirmed file format to port into, so treat it as unconfirmed rather than either persona-only or portable. Don't assume a tool is persona-only without checking its docs directly — this table was wrong about both Copilot and Gemini CLI for a full session before being caught and corrected (same root-cause error both times: conflating "can't nest further subagents" with "no delegation at all"). Same tool/permission-scoping limitation as Section A's generators applies here too — port name/description/model/body, don't guess at the target's tool-name vocabulary.

The one mistake to avoid either way

Never concatenate every skill's full body into the always-on router file "to be safe." That defeats progressive disclosure and front-loads irrelevant context into every task regardless of relevance — the exact bug this repo's own AGENTS.md redesign fixed (P0-06: an 880-line file cut to ~200 by switching to an index). Always prefer: routing rules + skill index, full bodies loaded on demand.

Reference

• docs/CLIENT_COMPATIBILITY.md — per-tool file/mechanism table, sources and caveats.
• docs/INTEGRATION.md — the exact manual-regen recipe for each already-built target.
• tools/lib/adapter-common.sh — the shared logic (demote_headings, render_skill_index, frontmatter_field) every generator uses; read it before hand-porting something none of the generators cover yet.