AI Agent Config Standards
How do independent AI agents coordinate on the same codebase without vendor lock-in?
Agentic AI Foundation
The Agentic AI Foundation (AAIF) launched December 2025 under the Linux Foundation. Three anchor standards, donated by competitors who agree coordination beats fragmentation.
| Standard | Donated By | Governs | Maturity |
|---|---|---|---|
| AGENTS.md | OpenAI / Sourcegraph | Project instructions | Adopted: 60,000+ repos, 20+ tools |
| Agent Skills | Anthropic | Modular capabilities | Early: Codex native, Copilot adopting |
| MCP | Anthropic | Tool connectivity | Adopted: Claude, Cursor, VS Code, Gemini |
Platinum members: Anthropic, OpenAI, Block, AWS, Bloomberg, Cloudflare, Google, Microsoft.
Complementary: Agent Client Protocol (ACP) by JetBrains and Zed standardizes how agents talk to IDEs — the transport layer, not the config file layer.
Three Layers
AGENTS.md WHAT to do in this repo (instructions)
.agents/skills/ HOW to do specific tasks (capabilities)
MCP config WHICH external tools (services)
These compose. AGENTS.md says "follow our content standards." .agents/skills/content-flow/SKILL.md provides the procedure. MCP connects the validator tool.
AGENTS.md Spec
The project instruction file. Tells every agent what matters in this repo.
| Property | Detail |
|---|---|
| File | AGENTS.md at project root and any subdirectory |
| Override | AGENTS.override.md takes precedence (same locations) |
| Global | ~/.codex/AGENTS.md for user-wide defaults |
| Size limit | 32 KiB combined (configurable via project_doc_max_bytes) |
| Walk | Root → cwd, each directory checked, files concatenate |
Which tools read AGENTS.md:
| Tool | Reads AGENTS.md | Native File | Notes |
|---|---|---|---|
| Codex CLI | Yes (primary) | AGENTS.md | First mover |
| GitHub Copilot | Yes | .github/copilot-instructions.md | Detects AGENTS.md, CLAUDE.md, GEMINI.md |
| Cursor | Yes | .cursor/rules/*.mdc | Reads alongside native rules |
| Gemini CLI | Yes | GEMINI.md | Falls back to AGENTS.md |
| Claude Code | No | CLAUDE.md | Feature request #6235 (2,777+ upvotes) |
| Windsurf | Not confirmed | .windsurf/rules/*.md | — |
The gap: Claude Code is the notable holdout. Workaround: @AGENTS.md import in CLAUDE.md.
Agent Skills Spec
Authored by Anthropic (Barry Zhang, Keith Lazuka, Mahesh Murag). Published at agentskills.io.
Structure
.agents/
skills/
content-flow/
SKILL.md # Required: name + description frontmatter
references/ # Optional: loaded on demand
cookbook/ # Optional: examples and patterns
scripts/ # Optional: executable code
assets/ # Optional: templates, schemas
SKILL.md Frontmatter
---
name: content-flow
description: Write and review /docs pages for Structure, Substance, and Connection
argument-hint: /path/to/file.md
---
| Field | Required | Max Length | Purpose |
|---|---|---|---|
name | Yes | 64 chars | Lowercase + hyphens. Discovery key. |
description | Yes | 1024 chars | When to activate. The trigger. |
argument-hint | No | — | What to pass when invoking |
license | No | — | For shared/published skills |
compatibility | No | — | Which agents support this skill |
allowed-tools | No | — | Restrict tool access |
Token Budget
Progressive disclosure controls context cost:
| Stage | What Loads | Budget |
|---|---|---|
| Startup | name + description from all skills | ~100 tokens per skill |
| Activation | Full SKILL.md body | <5,000 tokens recommended |
| On demand | references/, cookbook/, scripts/ | Loaded via Read when needed |
Discovery
Agents find skills by scanning .agents/skills/ from cwd upward to repo root. Codex also scans:
~/.codex/skills/(user-level)~/.codex/skills/.system/(system-level, admin-deployed)
Model Context Protocol
MCP standardizes how agents connect to external tools (databases, APIs, file systems). It defines servers, tools, resources, and prompts — but not where configs live.
| Tool | MCP Config Location |
|---|---|
| Claude Code | .mcp.json (project) or ~/.claude.json (user) |
| Cursor | .cursor/mcp.json |
| VS Code | .vscode/mcp.json |
| JetBrains | IDE-level mcp.json |
No .mcp/ directory convention exists. Each IDE owns its config location. MCP standardizes the protocol, not the file layout.
Tool Config Matrix
Complete mapping of where each tool reads configuration.
| Config Type | Claude Code | Gemini CLI | Codex CLI | Cursor | Windsurf | GitHub Copilot |
|---|---|---|---|---|---|---|
| Root file | CLAUDE.md | GEMINI.md | AGENTS.md | .cursor/rules/*.mdc | .windsurfrules | .github/copilot-instructions.md |
| Nested context | CLAUDE.md per dir | GEMINI.md per dir | AGENTS.md per dir | Globs only | To git root | Experimental |
| Rules dir | .claude/rules/*.md | — | — | .cursor/rules/*.mdc | .windsurf/rules/*.md | .github/instructions/*.instructions.md |
| Glob scoping | paths: frontmatter | — | — | globs: frontmatter | Activation modes | applyTo: frontmatter |
| Commands | .claude/commands/*.md | .gemini/commands/*.toml | .agents/skills/ | .cursor/agents/*.md | .windsurf/workflows/*.md | .github/prompts/*.prompt.md |
| Global config | ~/.claude/CLAUDE.md | ~/.gemini/GEMINI.md | ~/.codex/AGENTS.md | User Rules (UI) | global_rules.md (UI) | VS Code settings |
| Auto memory | MEMORY.md (auto) | /memory add (manual) | — | Notepads (beta) | Cascade Memories | — |
| Import syntax | @path | @file.md | — | — | — | #file: / links |
| MCP | .mcp.json | gemini-extension.json | — | Settings | — | Agent frontmatter |
Standard Maturity
How mature is each standard? When to adopt vs wait.
| Standard | Maturity | Signal | Our Position |
|---|---|---|---|
AGENTS.md | Adopted | 60K+ repos, AAIF governance, 20+ tools | Adopt: maintain AGENTS.md at root |
Agent Skills (.agents/skills/) | Early adopter | Spec published, Codex native, Copilot adopting | Adopt: skills in .agents/skills/ |
| MCP | Adopted | Broad IDE support, AAIF governance | Adopt: .mcp.json configured |
| ACP (IDE transport) | Emerging | JetBrains + Zed only | Watch: not relevant until IDE diversity matters |
.agent/ directory (issue #71) | Proposal | Open GitHub issue, mixed feedback | Wait: premature, conflicts with .agents/ |
| Unified rules directory | Not proposed | Each tool has its own format | Wait: symlink from .ai/rules/ to agent-native dirs |
Adoption Decision Framework
When a new standard appears, run this test:
| Gate | Question | Adopt If | Wait If |
|---|---|---|---|
| Governance | Who owns it? | Foundation (AAIF, Linux Foundation) | Single vendor |
| Adoption | Who uses it? | 3+ major tools | 1 tool only |
| Stability | Does the spec change often? | Versioned, backwards-compatible | Breaking changes monthly |
| Cost | What breaks if we adopt? | Adapter only, no rewrite | Full migration required |
| Reversibility | Can we undo it? | Rename/symlink back | Data loss or lock-in |
Applied to Agent Skills: Governance (AAIF) pass. Adoption (Codex + Copilot) pass. Stability (v1 spec published) pass. Cost (rename .ai/skills/ to .agents/skills/, update references) low. Reversibility (rename back) trivial. Decision: adopt.
Our Implementation
See Config Architecture for full documentation of how we implement these standards:
AGENTS.md— self-contained project instructions for Codex/Copilot.agents/skills/— 13 skills with standard SKILL.md frontmatter.ai/— rules, hooks, commands, voices (no standard yet)CLAUDE.md/GEMINI.md— agent-specific routers via@-imports.claude/commands/— proxy files redirect to.ai/commands/.claude/rules/— symlinks to.ai/rules/
Context
- Config Architecture — Our implementation and decision log
- Standards — Why engineering standards compound
- Model Context Protocol — Agent-to-tool communication
- A2A Protocol — Agent-to-agent coordination
- Composability — Build from reusable modules
- Interoperability — Coordinate across systems