One AGENTS.md for every agent

# AGENTS.md: one source of truth for every coding agent

This repository keeps agent instructions in one file, `AGENTS.md`, and generates or imports everything else.
Follow these rules whenever you add or change agent configuration.

## Where things go
- Project rules every agent needs: `AGENTS.md` at the root. Folder-specific rules: a nested `AGENTS.md` in that folder.
- Per-agent files hold only an import or that agent's genuine quirks:
  - CLAUDE.md contains `@AGENTS.md` plus Claude-only notes, if any.
  - GEMINI.md contains `@AGENTS.md`.
  - `.github/copilot-instructions.md` is optional; Copilot reads `AGENTS.md` itself.
- Workflows longer than ~15 lines go in a skill: `.agents/skills/<name>/SKILL.md` (also mirrored to `.claude/skills/` for Claude Code).
- MCP servers are declared once in `agents/mcp.servers.json` and converted per agent with the `sync-mcp-config` skill.

## Rules
- Never paste the same rule into two files. Move it to `AGENTS.md` and import.
- Keep root `AGENTS.md` under ~150 lines. Every line must change behaviour; delete lines an agent would follow anyway.
- Write commands exactly as they are run (`npm test -- --run`), not descriptions of them.
- When you change a build, test or lint command, update `AGENTS.md` in the same commit.
- Do not add a CLAUDE.md that lacks `@AGENTS.md`: since Claude Code v2.1.277, a CLAUDE.md on the path stops `AGENTS.md` loading natively.
- After any change to agent config, run the `audit-agent-config` skill.

# CLAUDE.md

@AGENTS.md

## Claude Code notes
- Skills from this loadout live in `.claude/skills/`: `audit-agent-config`, `sync-mcp-config`. Use them when their description matches the task.
- Follow AGENTS.md above; where this file and AGENTS.md disagree, AGENTS.md wins.

<!-- From the Agent Loadout "One AGENTS.md for every agent" v1.0.0 — https://loadout.jnw-it.com/loadouts/one-agents-md-every-agent/ -->

# GEMINI.md

@./AGENTS.md

## Gemini CLI notes
- Skills from this loadout live in `.agents/skills/`: `audit-agent-config`, `sync-mcp-config`. Use them when their description matches the task.
- Follow AGENTS.md above; where this file and AGENTS.md disagree, AGENTS.md wins.

<!-- From the Agent Loadout "One AGENTS.md for every agent" v1.0.0 — https://loadout.jnw-it.com/loadouts/one-agents-md-every-agent/ -->

---
name: audit-agent-config
description: Check that every coding agent in this repo actually loads the shared AGENTS.md, skills and MCP config, and find duplicated or shadowed rules. Use after changing agent config or when an agent ignores a rule.
---

# Audit agent config

Run from the repository root. Report findings as a table: agent, file, problem, fix. Fix only what the human approves.

1. **Inventory.**
   `git ls-files | grep -Ei '(^|/)(AGENTS|CLAUDE|GEMINI|CLAUDE\.local)\.md$|copilot-instructions|\.instructions\.md$|\.cursor/rules/|/SKILL\.md$|mcp'`
2. **Imports.** Every CLAUDE.md and GEMINI.md must contain `@AGENTS.md` (or the nested path). Flag any that do not.
3. **Shadowing.** Use `references/loading.md` to check each agent the team uses. Typical problems:
   - a CLAUDE.md without the import, which hides `AGENTS.md` from Claude Code;
   - a `.cursorrules` file (legacy) alongside `.cursor/rules/`;
   - skills only in `.claude/skills/` when Codex or Antigravity users need `.agents/skills/`.
4. **Duplicates.** Look for the same rule in more than one file:
   `grep -rhoE '^[-*] .{25,}' AGENTS.md CLAUDE.md GEMINI.md .github/copilot-instructions.md .cursor/rules 2>/dev/null | sort | uniq -d`
5. **Size.** Report root instruction files over ~150 lines and skills whose description does not say when to use them.
6. **Live check.** Ask the human to start each agent and ask it "Which instruction files and skills did you load?" Record the answers.

# What each agent loads (checked 16 October 2026)

| Agent | Instructions | Skills | MCP config (project) | Gotchas |
|---|---|---|---|---|
| Claude Code | CLAUDE.md (and `CLAUDE.local.md`); reads `AGENTS.md` natively since v2.1.277 only when no CLAUDE.md is on the path; setting "Project instructions" can read both | `.claude/skills/` | `.mcp.json` | Keep `@AGENTS.md` in CLAUDE.md. `/doctor prompt-audit` (v2.1.283+) lists what loaded |
| Codex | `AGENTS.md`, root to current folder, nearest last | `.agents/skills/` | `.codex/config.toml` `[mcp_servers.<name>]` | Untrusted projects do not supply project `AGENTS.md` or config; trust the project first |
| Cursor | `AGENTS.md`, `.cursor/rules/*.mdc` | `.agents/skills/`, `.cursor/skills/`, also `.claude/skills/` and `.codex/skills/` | `.cursor/mcp.json` | `.cursor/rules` does not apply to Bugbot; it reads `.cursor/BUGBOT.md` |
| GitHub Copilot | `AGENTS.md` (root and nested, nearest wins), `.github/copilot-instructions.md`, `.github/instructions/*.instructions.md` with `applyTo` | `.github/skills/`, `.claude/skills/` | `.vscode/mcp.json` (`servers`) | `excludeAgent` in front matter keeps an instruction file away from code review or the coding agent |
| Gemini CLI / Antigravity CLI | GEMINI.md (import `@AGENTS.md`); Antigravity also reads `AGENTS.md` | Gemini: `.gemini/skills/`; Antigravity: `.agents/skills/` | Gemini: `.gemini/settings.json`; Antigravity: .agents/mcp_config.json | Gemini CLI stopped serving personal Google accounts on 18 June 2026; Antigravity CLI replaces it and keeps GEMINI.md compatibility |

Sources: Claude Code changelog and memory docs, Codex AGENTS.md and skills docs, Cursor skills and Bugbot docs,
GitHub custom instructions docs, Google's Antigravity CLI announcement (19 May 2026). Re-check after major releases.

---
name: sync-mcp-config
description: Convert the single MCP server list in agents/mcp.servers.json into each agent's config file. Use when adding, removing or changing an MCP server for the team.
---

# Sync MCP config

The source of truth is `agents/mcp.servers.json`, an object `{ "mcpServers": { "<name>": {...} } }` in the
Claude/Cursor shape. Never edit generated files by hand; edit the source and re-run this skill.

1. Read the source. Each server is either stdio (`command`, `args`, `env`) or remote (`type: "http"`, `url`, `headers`).
2. Write only the files for agents the team uses (ask if unsure). Formats are in `references/formats.md`.
3. Secrets: never write a literal token. Use the agent's environment-variable syntax and tell the human which variable to set.
4. Pin package versions in `args` (for example `@playwright/mcp@0.0.83`), so an update is a reviewed diff.
5. Remove servers from generated files when they are removed from the source.
6. Show the human the diff. Each agent needs a restart or `/mcp` reconnect to pick up changes.

Keep the server list short: every server's tool descriptions cost context in every session. Prefer a CLI the
agent can already run (`gh`, `psql`, `supabase`) over an MCP server that wraps it.

# MCP config formats per agent

Source entry used in the examples:

```json
{ "mcpServers": {
  "docs": { "type": "http", "url": "https://mcp.example.com/mcp", "headers": { "Authorization": "Bearer ${DOCS_TOKEN}" } },
  "browser": { "command": "npx", "args": ["@playwright/mcp@0.0.83"] }
} }
```

| Agent | File | Shape |
|---|---|---|
| Claude Code | `.mcp.json` | Same as the source. `${VAR}` expands from the environment |
| Cursor | `.cursor/mcp.json` | Same as the source. Use `${env:VAR}` for environment variables |
| VS Code / Copilot | `.vscode/mcp.json` | Top-level key is `servers`, not `mcpServers`; each server keeps `type` (`stdio` or `http`) |
| Codex | `.codex/config.toml` (trusted projects) or `~/.codex/config.toml` | TOML tables, below |
| Gemini CLI | `.gemini/settings.json` | `mcpServers`; remote servers use `httpUrl` |
| Antigravity CLI | .agents/mcp_config.json | `mcpServers`; remote servers use `serverUrl` (not `url` or `httpUrl`). `agy plugin import gemini` migrates Gemini extensions |

Codex:

```toml
[mcp_servers.docs]
url = "https://mcp.example.com/mcp"
bearer_token_env_var = "DOCS_TOKEN"

[mcp_servers.browser]
command = "npx"
args = ["@playwright/mcp@0.0.83"]
```

Codex also has `codex mcp add <name> -- <command>` and `/mcp login` for servers that use OAuth.