Open specification · Draft 1.0

Write a custom agent once.
Install it in any coding harness.

The Common Agent Format (CAF) is a plain Markdown file, AGENT.md, with a short YAML header. It describes a custom agent's role, instructions, model and tool limits in a way people can read and programs can parse. An installer turns it into the native files for Claude Code, GitHub Copilot, Codex, Gemini CLI, Cursor and others.

Read the specification See an example

The problem

Every coding harness now supports custom agents, and every one stores them differently. Claude Code reads Markdown from .claude/agents/. Copilot wants .agent.md files in .github/agents/. Codex wants TOML in .codex/agents/. Tool names, model names and permission settings differ in each.

Teams that use more than one harness end up keeping several copies of the same agent, and the copies drift.

The format

CAF is one source file per agent, in a folder that can also carry bundled Agent Skills, reference documents, and settings for particular harnesses.

Markdown body: the agent's instructions, as you'd write them anyway
Portable fields for model tier, effort, tools and MCP servers
Per-harness overrides when you need native features
Same layout and naming rules as Agent Skills

One file in, native files out

The same agent, as written in CAF and as an installer writes it for three harnesses.

Source.agents/caf/docs-writer/AGENT.md

---
name: docs-writer
description: Updates README and docs/ to match the current code.
  Use after a feature lands or an interface changes.
model: balanced
tools: [read, search, edit]
---

You keep a project's documentation in step with its code.

1. Find what changed with `git log` and `git diff`
   since the docs were last touched.
2. Update only the documents that describe changed behaviour.
3. Keep each document's existing tone and audience.
4. List the files you changed and one line on why for each.

Generated.claude/agents/docs-writer.md

---
name: docs-writer
description: Updates README and docs/ to match the current code.
  Use after a feature lands or an interface changes.
model: sonnet
tools: Read, Glob, Grep, Edit, Write, NotebookEdit
---

You keep a project's documentation in step with its code.
…

Generated.github/agents/docs-writer.agent.md

---
name: docs-writer
description: Updates README and docs/ to match the current code.
  Use after a feature lands or an interface changes.
tools: [read, search, edit]
---

You keep a project's documentation in step with its code.
…

Generated.codex/agents/docs-writer.toml

name = "docs-writer"
description = """Updates README and docs/ to match the current code. \
Use after a feature lands or an interface changes."""
web_search = "disabled"
developer_instructions = """
You keep a project's documentation in step with its code.
…
"""

[features]
shell_tool = false

Highlighted values are translated by the installer. See harness mappings for every field.

What's in an agent folder

Only AGENT.md is required. Everything else is there when you need it.

The harness/ folder holds settings and files for a single harness, written in that harness's own terms: a Claude Code hook script, a Codex reasoning setting, extra instructions that only make sense in Copilot. Installers merge them over what they generate from the portable fields.

How harness configuration works →

code-reviewer/
├── AGENT.md              # required
├── harness/
│   ├── claude-code/
│   │   ├── settings.yaml   # native keys
│   │   └── files/hooks/…
│   └── codex/
│       └── instructions.md # appended
├── skills/               # Agent Skills
│   └── review-checklist/
│       └── SKILL.md
├── references/
└── assets/

How it gets installed

1
Write

Author AGENT.md in your repository, or pull a shared agent from someone else's.
2
Install

An installer such as Agent Manager validates the agent, maps its fields and writes native files.
3
Use

The harness loads the generated agent as if you had written it by hand.

Installers never give an agent more access than its definition allows. If a harness can't enforce a tool restriction, the install stops and asks.

Harnesses

Claude Code.claude/agents/
GitHub Copilot.github/agents/
Codex.codex/agents/
Gemini CLI.gemini/agents/
Cursor.cursor/agents/
OpenCode.opencode/agents/
Grok Build.grok/agents/
Kilo Code.kilo/agents/

Questions

How is this different from AGENTS.md?: AGENTS.md holds instructions for every agent working in a repository. CAF describes one named agent with its own role, model and tool limits. A repository can have both.
How is it different from Agent Skills?: A skill is a capability any agent can load when a task calls for it. A CAF agent is a separate worker that the main agent hands tasks to. CAF copies the Agent Skills layout and naming rules, and an agent can bundle skills.
Why not just copy Claude Code's format?: Its tool names, model aliases and permission settings only mean something in Claude Code, and Codex uses TOML. CAF keeps the parts every harness shares and puts the rest under harness:.
Doesn't something like this exist already?: Partly. supagents generates native files from one Markdown source, but leaves tool names and models untranslated. General agent formats such as AAIF and gitagent describe whole agent runtimes rather than coding-harness subagents. CAF sits between the two: a small, portable vocabulary plus native escape hatches.
Is this tied to a vendor?: No. The specification is open and changes are made by pull request.

Write a custom agent once.Install it in any coding harness.