Agent Standards

One git checkout drops a shared AI coding setup (skills, subagents, MCP servers, OpenSpec scaffolding) into any project.

Why it exists

For developers and teams running multiple AI coding agents across multiple repos. Every project drifts (different prompt files, skill versions, MCP configs, subagent definitions). This repo is the single source: import once, pull updates with one git fetch. Used across every project in the portfolio.

Consumer projects pull only production-ready content: skills, generated subagent files, the preflight gate, the MCP configs, and the shipped docs. The canonical subagents/ source and tools/ generator stay here.

The canonical source is .agents/skills/, which Codex, OpenCode, Kilo Code, and every GitHub Copilot surface read natively. The layout follows the cross-tool AGENTS.md and SKILL.md conventions, so the setup stays portable across the supported agents rather than tied to one tool.

Prerequisites

Four things. The first two matter in every project, the last two depend on your platform and on which agents you run.

Git. The import is a selective checkout from a second remote, so nothing else installs the files.
Python 3 on your path, under either name. Every hook in .agents/hooks/ is a Python script, and every wiring throws away a failed call so a broken gate can never break a session. Each POSIX wiring resolves python3 first and falls back to python, which is the name the python.org installer puts on a Windows path, so either name is enough. With neither on the path the gate reads as an allow, which means it is silently off rather than loudly broken. Check before you trust it.
Windows only: Developer Mode (Settings, System, For developers) plus git told to honour symlinks. Three paths in the import are symlinks, and without both git writes each one out as a text file holding its target path.
Node, only if you run OpenCode or Kilo Code. Their gate adapter is .agents/plugin/hooks.js, loaded by their own runtime. The other three agents need none.

Confirm the interpreter. PowerShell:

python --version

Unix shell:

python3 --version

If that prints nothing, install Python 3 before you go on, or the gate will allow every call it was meant to block.

Quickstart

On Windows, turn on Developer Mode first, then set the symlink option inside the project you are importing into. PowerShell:

git config core.symlinks true

Unix shell:

git config core.symlinks true

Adding --global to that command sets it once for every repository on the machine, including clones you have not made yet, which is the form to use if you import the standards more than once.

Add the upstream remote. PowerShell:

git remote add agent-standards https://github.com/Lukk17/agent-standards

Unix shell:

git remote add agent-standards https://github.com/Lukk17/agent-standards

Point its push URL at nothing, so a stray push cannot reach it. PowerShell:

git remote set-url --push agent-standards no_push

Unix shell:

git remote set-url --push agent-standards no_push

Fetch it. PowerShell:

git fetch agent-standards

Unix shell:

git fetch agent-standards

Check out the production-ready paths. PowerShell:

git checkout agent-standards/master -- .agents .claude .opencode .kilo .codex .github/agents .github/hooks .vscode/mcp.json .mcp.json .github/mcp.json opencode.json docs/AGENT_TOOLING.md docs/MCP_SETUP.md docs/GLOBAL_SETUP.md docs/AGENTS-UPDATE.md AGENTS.md.example

Unix shell:

git checkout agent-standards/master -- .agents .claude .opencode .kilo .codex .github/agents .github/hooks .vscode/mcp.json .mcp.json .github/mcp.json opencode.json docs/AGENT_TOOLING.md docs/MCP_SETUP.md docs/GLOBAL_SETUP.md docs/AGENTS-UPDATE.md AGENTS.md.example

Rename the one template. PowerShell:

Rename-Item AGENTS.md.example AGENTS.md

Unix shell:

mv AGENTS.md.example AGENTS.md

Add the agent task list to your own ignore file, because the task-list hook writes it every session. PowerShell:

Add-Content .gitignore "`n/tasks.md"

Unix shell:

printf '\n/tasks.md\n' >> .gitignore

That's it. Open the project in Claude Code, Kilo Code, OpenCode, Codex, or GitHub Copilot and skills are live.

The MCP config files arrive as real files, ready to use, so nothing else needs renaming: .mcp.json for Claude Code, opencode.json for OpenCode and Kilo Code, .codex/config.toml for Codex, .vscode/mcp.json for Copilot in VS Code, and .github/mcp.json for the Copilot CLI. AGENTS.md.example is the only template left in the repo.

Human-side MCP setup (keys, environment variables, the two Copilot surfaces that get no file) lives in docs/MCP_SETUP.md.

Full walkthrough lives in docs/AGENT_TOOLING.md.

Per-agent setup

The Quickstart above is the recommended path and stays right for most projects: it pulls the whole setup once and every agent then finds what it reads. If a project only ever sees one agent, the subsection for that agent pulls just its share instead.

Run the first three Quickstart commands once so the read-only remote exists (git remote add, git remote set-url --push agent-standards no_push, and git fetch agent-standards), then follow the single subsection you need. Adding a second agent later is nothing more than running its subsection too, because the shared paths are the same files.

Claude Code

Claude Code 2.1.277 and later reads AGENTS.md natively, but only while the project holds no CLAUDE.md, so this setup ships none and you add none (why). It is the one agent that does not read .agents/skills/ on its own, so it gets the skills through the .claude/skills symlink, subagents from .claude/agents/, hooks from .claude/settings.json, and MCP servers from .mcp.json at the project root.

.claude/skills is a symlink, so Windows needs Developer Mode on (Settings, System, For developers) and git told to honour symlinks. Without both, git writes a text file holding the target path and Claude Code sees no skills at all. PowerShell:

git config core.symlinks true

The Unix shells need nothing here.

Pull what Claude Code reads. PowerShell:

git checkout agent-standards/master -- .agents/skills .agents/hooks .claude .mcp.json AGENTS.md.example docs/AGENT_TOOLING.md docs/MCP_SETUP.md docs/GLOBAL_SETUP.md docs/AGENTS-UPDATE.md

Unix shell:

git checkout agent-standards/master -- .agents/skills .agents/hooks .claude .mcp.json AGENTS.md.example docs/AGENT_TOOLING.md docs/MCP_SETUP.md docs/GLOBAL_SETUP.md docs/AGENTS-UPDATE.md

Rename the template so Claude Code reads it as AGENTS.md. PowerShell:

Rename-Item AGENTS.md.example AGENTS.md

Unix shell:

mv AGENTS.md.example AGENTS.md

To update later, fetch first. PowerShell:

git fetch agent-standards

Unix shell:

git fetch agent-standards

Then pull upstream's half back over your tree. Your AGENTS.md, .claude/settings.json, and .mcp.json are left out on purpose, because they become yours at import. PowerShell:

git checkout agent-standards/master -- .agents/skills .agents/hooks .claude/agents .claude/workflows docs/AGENT_TOOLING.md docs/MCP_SETUP.md docs/GLOBAL_SETUP.md docs/AGENTS-UPDATE.md

Unix shell:

git checkout agent-standards/master -- .agents/skills .agents/hooks .claude/agents .claude/workflows docs/AGENT_TOOLING.md docs/MCP_SETUP.md docs/GLOBAL_SETUP.md docs/AGENTS-UPDATE.md

Codex

Codex reads AGENTS.md and .agents/skills/ natively, and it follows symlinks while scanning them, so nothing has to be bridged. Custom agents come from .codex/agents/ as TOML, and .codex/config.toml carries both the [mcp_servers] tables and the preflight hooks as inline [[hooks.*]] tables. No symlink is involved in this set, so Windows needs neither Developer Mode nor git config core.symlinks true.

Pull what Codex reads. PowerShell:

git checkout agent-standards/master -- .agents/skills .agents/hooks .codex AGENTS.md.example docs/AGENT_TOOLING.md docs/MCP_SETUP.md docs/GLOBAL_SETUP.md docs/AGENTS-UPDATE.md

Unix shell:

git checkout agent-standards/master -- .agents/skills .agents/hooks .codex AGENTS.md.example docs/AGENT_TOOLING.md docs/MCP_SETUP.md docs/GLOBAL_SETUP.md docs/AGENTS-UPDATE.md

Rename the template. PowerShell:

Rename-Item AGENTS.md.example AGENTS.md

Unix shell:

mv AGENTS.md.example AGENTS.md

Codex loads a project's .codex/ layer only after you trust the project once, so approve it on first run or none of the hooks and none of the MCP servers apply.

To update later, fetch first. PowerShell:

git fetch agent-standards

Unix shell:

git fetch agent-standards

Then pull upstream's half back. .codex/config.toml stays out of it, because your MCP servers and the hook tables share that one file, so merge an upstream change there by hand. PowerShell:

git checkout agent-standards/master -- .agents/skills .agents/hooks .codex/agents docs/AGENT_TOOLING.md docs/MCP_SETUP.md docs/GLOBAL_SETUP.md docs/AGENTS-UPDATE.md

Unix shell:

git checkout agent-standards/master -- .agents/skills .agents/hooks .codex/agents docs/AGENT_TOOLING.md docs/MCP_SETUP.md docs/GLOBAL_SETUP.md docs/AGENTS-UPDATE.md

OpenCode

OpenCode reads AGENTS.md and .agents/skills/ natively. Subagents arrive through the .opencode/agents symlink into .agents/agents/. opencode.json at the project root declares the gate plugin by path in its plugin array and carries the MCP servers under its mcp key. That file has to stay at the root, because inside .opencode/ it is ignored.

.opencode/agents is a symlink, so Windows needs Developer Mode on (Settings, System, For developers) and git told to honour symlinks, or OpenCode ends up with no subagents. PowerShell:

git config core.symlinks true

The Unix shells need nothing here.

Pull what OpenCode reads. PowerShell:

git checkout agent-standards/master -- .agents/skills .agents/agents .agents/hooks .agents/plugin .opencode opencode.json AGENTS.md.example docs/AGENT_TOOLING.md docs/MCP_SETUP.md docs/GLOBAL_SETUP.md docs/AGENTS-UPDATE.md

Unix shell:

git checkout agent-standards/master -- .agents/skills .agents/agents .agents/hooks .agents/plugin .opencode opencode.json AGENTS.md.example docs/AGENT_TOOLING.md docs/MCP_SETUP.md docs/GLOBAL_SETUP.md docs/AGENTS-UPDATE.md

Rename the template. PowerShell:

Rename-Item AGENTS.md.example AGENTS.md

Unix shell:

mv AGENTS.md.example AGENTS.md

To update later, fetch first. PowerShell:

git fetch agent-standards

Unix shell:

git fetch agent-standards

Then pull upstream's half back. opencode.json stays out, because it holds your MCP servers and the plugin declaration together. PowerShell:

git checkout agent-standards/master -- .agents/skills .agents/agents .agents/hooks .agents/plugin docs/AGENT_TOOLING.md docs/MCP_SETUP.md docs/GLOBAL_SETUP.md docs/AGENTS-UPDATE.md

Unix shell:

git checkout agent-standards/master -- .agents/skills .agents/agents .agents/hooks .agents/plugin docs/AGENT_TOOLING.md docs/MCP_SETUP.md docs/GLOBAL_SETUP.md docs/AGENTS-UPDATE.md

Kilo Code

Kilo Code works like OpenCode. It reads AGENTS.md and .agents/skills/ natively, takes its subagents through the .kilo/agents symlink into .agents/agents/, and accepts the root opencode.json as a project config file, so it picks up the gate plugin and the MCP block from the same file OpenCode uses.

Kilo is stricter than OpenCode about substitution. A {env:VAR} anywhere in a project config file is a fatal error for Kilo, and it rejects that entire file rather than leaving the token literal, which would cost it the MCP servers and the gate plugin in one go. The shipped opencode.json therefore carries no tokens at all. Local servers still get their secrets, because both tools start them with the environment of the process that started the agent, so exporting the variable is enough. The single value that cannot be inherited is the Context7 API key, which travels in an HTTP header, so context7 ships unauthenticated on the free tier. Adding a paid key is a global-config change, described in docs/MCP_SETUP.md.

.kilo/agents is a symlink, so Windows needs Developer Mode on (Settings, System, For developers) and git told to honour symlinks, or Kilo Code ends up with no subagents. PowerShell:

git config core.symlinks true

The Unix shells need nothing here.

Pull what Kilo Code reads. PowerShell:

git checkout agent-standards/master -- .agents/skills .agents/agents .agents/hooks .agents/plugin .kilo opencode.json AGENTS.md.example docs/AGENT_TOOLING.md docs/MCP_SETUP.md docs/GLOBAL_SETUP.md docs/AGENTS-UPDATE.md

Unix shell:

git checkout agent-standards/master -- .agents/skills .agents/agents .agents/hooks .agents/plugin .kilo opencode.json AGENTS.md.example docs/AGENT_TOOLING.md docs/MCP_SETUP.md docs/GLOBAL_SETUP.md docs/AGENTS-UPDATE.md

Rename the template. PowerShell:

Rename-Item AGENTS.md.example AGENTS.md

Unix shell:

mv AGENTS.md.example AGENTS.md

To update later, fetch first. PowerShell:

git fetch agent-standards

Unix shell:

git fetch agent-standards

Then pull upstream's half back, leaving opencode.json alone for the same reason as OpenCode. PowerShell:

git checkout agent-standards/master -- .agents/skills .agents/agents .agents/hooks .agents/plugin docs/AGENT_TOOLING.md docs/MCP_SETUP.md docs/GLOBAL_SETUP.md docs/AGENTS-UPDATE.md

Unix shell:

git checkout agent-standards/master -- .agents/skills .agents/agents .agents/hooks .agents/plugin docs/AGENT_TOOLING.md docs/MCP_SETUP.md docs/GLOBAL_SETUP.md docs/AGENTS-UPDATE.md

GitHub Copilot

Copilot reads AGENTS.md and .agents/skills/ natively on every surface: VS Code, the JetBrains plugin, the CLI, and the cloud agent. No bridge file, and no symlink either, so Windows needs neither Developer Mode nor git config core.symlinks true. Subagents have to be Copilot's own *.agent.md format in .github/agents/, and the gate rides .github/hooks/preflight.json with camelCase event names. The JetBrains plugin reads AGENTS.md in agent mode too, per the March 2026 changelog, even though GitHub's published support matrix still leaves JetBrains out of that column.

MCP is the part that splits per surface. The CLI reads its own .github/mcp.json, literal values only, because it has no substitution engine for Claude Code's ${VAR:-default} syntax in .mcp.json. VS Code needs .vscode/mcp.json. The JetBrains plugin reads a global path only and gets no project file at all, and the cloud agent takes JSON pasted into a repository settings page. Both manual blocks live in docs/MCP_SETUP.md.

The CLI is also documented as capable of reading .mcp.json itself, and its own precedence rule makes that file win over .github/mcp.json whenever both exist in the same directory and name the same server, which is true for all eight servers here. The full Quickstart above pulls both files, so on a project imported that way the CLI currently resolves every server from .mcp.json, with its ${VAR:-default} placeholders left as literal unresolved strings, rather than from the clean file shipped for it. Measurement and full detail: docs/MCP_SETUP.md.

Pull what Copilot reads. PowerShell:

git checkout agent-standards/master -- .agents/skills .agents/hooks .github/agents .github/hooks .vscode/mcp.json .github/mcp.json AGENTS.md.example docs/AGENT_TOOLING.md docs/MCP_SETUP.md docs/GLOBAL_SETUP.md docs/AGENTS-UPDATE.md

Unix shell:

git checkout agent-standards/master -- .agents/skills .agents/hooks .github/agents .github/hooks .vscode/mcp.json .github/mcp.json AGENTS.md.example docs/AGENT_TOOLING.md docs/MCP_SETUP.md docs/GLOBAL_SETUP.md docs/AGENTS-UPDATE.md

Rename the template. PowerShell:

Rename-Item AGENTS.md.example AGENTS.md

Unix shell:

mv AGENTS.md.example AGENTS.md

To update later, fetch first. PowerShell:

git fetch agent-standards

Unix shell:

git fetch agent-standards

Then pull upstream's half back, leaving both MCP files alone because they are yours after the import. PowerShell:

git checkout agent-standards/master -- .agents/skills .agents/hooks .github/agents .github/hooks docs/AGENT_TOOLING.md docs/MCP_SETUP.md docs/GLOBAL_SETUP.md docs/AGENTS-UPDATE.md

Unix shell:

git checkout agent-standards/master -- .agents/skills .agents/hooks .github/agents .github/hooks docs/AGENT_TOOLING.md docs/MCP_SETUP.md docs/GLOBAL_SETUP.md docs/AGENTS-UPDATE.md

Once you have customised the set

The update commands above pull every skill and subagent back, including ones you deleted on purpose. As soon as you start adding or removing skills locally, switch to the selective refresh in docs/AGENTS-UPDATE.md, which refreshes only what is already in your working tree.

Architecture

graph LR
    subgraph AS[agent-standards repo]
      ASK[.agents/skills/<br/>canonical SKILL.md files]
      SU[subagents/<br/>canonical sources]
      GEN[tools/gen_subagents.py]
      SU --> GEN
    end
    AS -->|git checkout production-ready dirs only| P[Your project]
    P --> SK[.agents/skills/]
    P --> OA[.agents/agents/<br/>generated, OpenCode format]
    P --> CA[.claude/agents/<br/>generated]
    P --> CXA[.codex/agents/<br/>generated TOML]
    P --> GH[.github/agents/<br/>generated .agent.md]
    P --> AG[AGENTS.md]
    SK -.symlink.-> CL[.claude/skills]
    OA -.symlink.-> OCL[.opencode/agents]
    OA -.symlink.-> KIL[.kilo/agents]
    CL --> Claude[Claude Code]
    SK --> OpenCode[OpenCode]
    SK --> Kilo[Kilo Code]
    SK --> Codex[Codex]
    SK --> Copilot[GitHub Copilot]
    OCL --> OpenCode
    KIL --> Kilo
    CA --> Claude
    CXA --> Codex
    GH --> Copilot
    AG --> OpenCode
    AG --> Kilo
    AG --> Codex
    AG --> Copilot
    AG -.imported.-> Claude

    classDef src fill:#ede0ff,stroke:#7c3aed,color:#1a1033
    classDef consumer fill:#fff7e0,stroke:#d97706,color:#1a1033
    classDef tool fill:#e0f2fe,stroke:#0284c7,color:#1a1033
    class AS,ASK,SU,GEN src
    class P,SK,CA,OA,CXA,GH,AG,CL,OCL,KIL consumer
    class Claude,Kilo,OpenCode,Codex,Copilot tool

Two canonical sources in this repo: .agents/skills/ and subagents/. Consumers receive .agents/skills/ plus four generated subagent trees (.agents/agents/ in OpenCode format, .claude/agents/, .codex/agents/ in TOML, and .github/agents/ as *.agent.md). OpenCode and Kilo Code share the OpenCode-format tree through the .opencode/agents and .kilo/agents symlinks rather than getting a copy each. The subagents/ source and the tools/ generator never ship downstream.

Full agent compatibility matrix (what each agent reads and where): docs/agent-compatibility.md. Full repository layout and per-agent instruction precedence: docs/repository-layout.md.

The second diagram is the path of one tool call. Every agent takes it, because every agent's hook wiring calls the same script, and the denial is what turns the written rule into an enforced one.

sequenceDiagram
    accTitle: Preflight gate on one tool call
    accDescr: The agent calls a tool, the hook runs the shared gate script, and the gate allows or denies with text telling the caller to delegate.
    participant M as Main thread
    participant H as Agent hook surface
    participant G as preflight_gate.py
    participant S as Subagent
    M->>H: Edit README.md
    H->>G: hook payload on stdin
    G-->>H: deny, the path is inside the repo
    H-->>M: "delegate this change to a subagent that owns the area"
    M->>S: spawn markdown-writer
    S->>H: Edit README.md
    H->>G: hook payload, agent_type set
    G-->>H: allow, the subagent declares skills
    H-->>S: write applied

A missing interpreter, an unreadable script, or an unparseable payload all resolve to allow, so the arrow that says deny is the only one that stops anything. That is why Python 3 is a prerequisite rather than an optional extra.

Agent support

All five agents read AGENTS.md natively, Claude Code only while the project holds no CLAUDE.md. Four read .agents/skills/ natively, and Claude Code gets a symlink for the skills, a pattern its own documentation supports. Subagents and MCP are per tool because no shared format exists. Full per-surface detail, including what each hook surface can actually block, lives in docs/agent-compatibility.md.

Agent	Instructions	Skills	Subagents	Preflight	MCP config
Claude Code	`AGENTS.md` (native, with no `CLAUDE.md`)	`.claude/skills` (symlink)	`.claude/agents/`	hooks in `.claude/settings.json`, blocks tools and replies	`.mcp.json`
OpenCode	`AGENTS.md` (native)	`.agents/skills/` (native)	`.opencode/agents` (symlink)	shared plugin, blocks tools	`opencode.json`
Kilo Code	`AGENTS.md` (native)	`.agents/skills/` (native)	`.kilo/agents` (symlink)	the same plugin, blocks tools	`opencode.json`
Codex	`AGENTS.md` (native)	`.agents/skills/` (native)	`.codex/agents/` (TOML)	inline hooks in `.codex/config.toml`, blocks tools	`.codex/config.toml`
GitHub Copilot	`AGENTS.md` (native)	`.agents/skills/` (native)	`.github/agents/` (`*.agent.md`)	`.github/hooks/preflight.json`, blocks tools, no agent identity	`.vscode/mcp.json`, CLI uses `.github/mcp.json`

What's in the box

.agents/skills/: canonical SKILL.md files. Source of truth, shared by every agent, shipped to consumers. Each one carries standard front matter (name, description, and optionally license or compatibility) following the open Agent Skills specification, a description written as the phrases that should trigger it, and its depth in a references/ subdirectory rather than in the manifest. Browse the catalogue to see what's available.
.agents/hooks/: four Python scripts, all standard library only, all run on -S -E under whichever of python3 and python the wiring resolves first. .agents/hooks/preflight_gate.py is the one shared gate rule every agent surface wires into. .agents/hooks/no_ai_markers_check.py rejects a reply whose prose carries a dash, a semicolon, or a bold or italic marker. .agents/hooks/markdown_lint_check.py reports lint violations back as context after an edit to a linted file. .agents/hooks/task_list_sync.py mirrors the live task list into tasks.md at the project root and injects it again after a compaction, so the session's own plan survives. tasks.md is per-session working state: add it to your .gitignore rather than committing it. .agents/hooks/copilot/prompt_reminder.py appends the gate text to every GitHub Copilot prompt, and sits one level down so the OpenCode and Kilo Code runner never spawns it. .agents/plugin/hooks.js: the OpenCode and Kilo Code adapter, a runner that hands every tool call to every hook in that directory. Contract: docs/hooks-contract.md.
subagents/ (this repo only): canonical subagent sources. Generator emits the per-tool copies. Each source names the skills its agent preloads, and the generator refuses to run when one of those names has no folder under .agents/skills/, so a renamed skill fails the build instead of silently doing nothing.
tools/ (this repo only): the subagent generator, the markdown linter, the badge-count linter, the AGENTS.md size guard, and the pytest suite for the shared hook scripts in tools/tests/. The generator emits four subagent trees (.agents/agents/, .claude/agents/, .codex/agents/, .github/agents/) and maintains the .opencode/agents and .kilo/agents symlinks. It also emits a per-format tools list, including Copilot's own tool names, sets permissionMode: plan on Claude Code for the read-only agents, and accepts model: inherit for an agent that should run on whatever the session already uses.
.claude/: Claude Code's own folder, with a skills symlink, a generated agents/ tree, and the hooks in settings.json. It holds no CLAUDE.md, because any CLAUDE.md stops Claude Code reading AGENTS.md.
.claude/workflows/skill-audit.js: a saved Claude Code workflow, run as /skill-audit, that audits the skills. See docs/AGENT_TOOLING.md.
OpenSpec scaffold (consumer side only, this repo ships no openspec-* skills of its own, because OpenSpec is a consumer concern): spec-driven workflow. Initialise it with the vendor-neutral openspec init --tools agents, which writes into .agents/skills/ and creates no per-tool directories. That one target covers every agent, since Codex, OpenCode, Kilo Code, and Copilot read .agents/skills/ natively and Claude Code reaches the same files through its .claude/skills symlink. Later, openspec update regenerates the per-agent files for the tools already configured in the project and takes no tools flag. Skip the per-tool targets: on top of fragmenting a layout built for one skills directory, OpenSpec 1.10.0 still hardcodes the abandoned .kilocode path for its Kilo target. See docs/AGENT_TOOLING.md.
Companion OpenSpec schema (optional): Lukk17/openspec-schemas ships an e2e-runbooks schema for spec-driven end-to-end capability tests through OpenSpec's lifecycle. Install steps and the invocation live in docs/AGENT_TOOLING.md.
AGENTS.md: shared instructions read natively by Codex, OpenCode, Kilo Code, and GitHub Copilot. AGENTS.md.example is the one template left, renamed to AGENTS.md on import.
GitHub Copilot: .github/agents/ holds generated *.agent.md subagents, and .github/hooks/preflight.json wires the gate through camelCase hook events. Copilot reads AGENTS.md and .agents/skills/ natively on every surface, so no bridge instruction file ships. The JetBrains plugin reads AGENTS.md in agent mode too, per the March 2026 changelog, though GitHub's own support matrix still omits it.
MCP config: .mcp.json (Claude Code), opencode.json (OpenCode and Kilo Code), .codex/config.toml (Codex), .vscode/mcp.json (Copilot in VS Code), and .github/mcp.json (the Copilot CLI). Five real files, one per agent surface, not templates.

Server list and configuration live in docs/MCP_SETUP.md. Claude Code's file uses ${VAR} with defaults. The others hardcode their URLs because their substitution syntax has no fallback, and the shared OpenCode and Kilo file carries no substitution tokens at all, because Kilo Code rejects a whole project config file that contains one.

Configuration

There are no ports and no service to run. Everything is files, and they split into three groups.

MCP servers live in five files, one per agent surface, all carrying the same eight servers and differing only in the top-level key, the type value, and the substitution syntax: .mcp.json, opencode.json, .codex/config.toml, .vscode/mcp.json, and .github/mcp.json. Change one, change all five. Keys, environment variables per operating system, and the two Copilot surfaces that get no project file at all are in docs/MCP_SETUP.md.

Hook wiring lives beside them, one file per agent, all calling the same scripts in .agents/hooks/: .claude/settings.json, the inline [[hooks.*]] tables in .codex/config.toml, the plugin array of opencode.json, and .github/hooks/preflight.json.

Which agent reads which of those, and what each hook surface can actually block, is the Agent support table above. Per-surface detail is in docs/agent-compatibility.md.

How it compares

Approach	What you get	Trade-off
Copy-paste a single `AGENTS.md`	Fast start, one file	Drifts the moment upstream changes; no skills, no subagents, no MCP
Personal dotfiles repo	Total control	Manual sync, and not designed for cross-tool agent setup
Tool-native rules (Cursor rules, Claude Projects)	Works in that tool	Locks you in, no portability across the supported agents
Awesome lists / prompt collections	Inspiration	Curated reading, not an installable setup
agent-standards	One `git checkout` brings skills, subagents, MCP servers across every supported agent	Adds an `agent-standards` git remote; Windows symlinks need Developer Mode

Where this loses: setup overhead (one-time), the remote dependency, and Windows symlink ergonomics.

Where it wins: a single source for the whole agent surface (skills, subagents, MCP, OpenSpec scaffolding), refreshed with one git fetch.

Working with subagents

The specialised subagents live as one canonical Markdown file each in subagents/ (this repo's root, not shipped to consumer projects). A generator emits the four tool-specific trees that are shipped, and maintains the two symlinks that let OpenCode and Kilo Code share one of them.

After editing any canonical file:

python tools/gen_subagents.py

CI gate (fails if generated tree is stale relative to canonical):

python tools/gen_subagents.py --check

Rules:

Edit subagents/.md only. The generator overwrites all four trees: .agents/agents/, .claude/agents/, .codex/agents/, and .github/agents/.
Each tool gets its own format. Claude Code, Codex (TOML), and GitHub Copilot (*.agent.md) each need their own. OpenCode and Kilo Code take the same OpenCode-format markdown and both follow symlinks when scanning an agent directory, so they share .agents/agents/ through .opencode/agents and .kilo/agents.
Run the generator after any canonical change and commit both the source and the generated output. It also repairs the two symlinks if they went missing.
Every skill a canonical file lists has to exist as a folder under .agents/skills/. The generator exits with an error naming the dangling entries rather than emitting an agent that preloads nothing.
Consumer projects pull only the generated trees. They never see subagents/ or tools/.

Adding a new subagent: drop a frontmatter-headed Markdown file in subagents/ and re-run the generator.

Removing one: delete the canonical file and re-run. Orphaned outputs are pruned automatically.

Pulling updates

Updates are driven from docs/AGENTS-UPDATE.md, a doc shipped from upstream that refreshes itself on every run. It contains bash and PowerShell commands that:

Refresh the four shipped docs (docs/AGENT_TOOLING.md, docs/MCP_SETUP.md, docs/GLOBAL_SETUP.md, and docs/AGENTS-UPDATE.md itself).
Refresh all four hook scripts in .agents/hooks/, the OpenCode and Kilo plugin in .agents/plugin/, and the Copilot hook file in .github/hooks/.
Enumerate the skills already in the consumer's .agents/skills/ and pull only those (no surprise additions).
Enumerate the subagents already in the four generated trees (.agents/agents/, .claude/agents/, .codex/agents/, .github/agents/) and pull only those.
Enumerate the saved Claude Code workflows already in .claude/workflows/ and pull only those.

The per-agent update commands earlier in this README work differently: they check out whole folders such as .agents/skills, .claude/agents and .claude/workflows, so they also bring in skills, subagents and workflows your project did not have yet.

Files intentionally NOT touched by the update: the three symlinks (.claude/skills, .opencode/agents, .kilo/agents, all of which follow their canonical directories anyway), AGENTS.md.example, the consumer's customised AGENTS.md, and the six configuration files (.mcp.json, opencode.json, .vscode/mcp.json, .github/mcp.json, .codex/config.toml, .claude/settings.json). Three of those six hold gate wiring next to something of yours, so a checkout would take your MCP servers or your permissions with it.

A project imported before agent-standards stopped shipping .claude/CLAUDE.md deletes it once, as retiring .claude/CLAUDE.md describes, because any CLAUDE.md stops Claude Code reading AGENTS.md natively.

When you do want an upstream change in one of the six, each shell section of that doc ends with a diff command and a checkout for all six, and what this skips says which half of each file is yours and which should track upstream.

If your project was imported before this doc shipped and has no docs/AGENTS-UPDATE.md, pull it with a one-off git checkout agent-standards/master -- docs/AGENTS-UPDATE.md, then use it for every later refresh.

Full walkthrough lives in docs/AGENT_TOOLING.md.

Docs map

Naming convention: UPPERCASE filenames ship to consumer projects via the git checkout above, lowercase filenames stay in this repo only.

Shipped to consumer projects

File	What's in it
docs/AGENT_TOOLING.md	Initial import flow, future updates, subagents, MCP overview, full OpenSpec integration and workflow.
docs/MCP_SETUP.md	The real MCP config files, prerequisites, keys, env-var export per OS, the manual JetBrains and cloud-agent blocks, verification.
docs/AGENTS-UPDATE.md	Per-shell selective update commands including the diff-first configuration-file pair, the Windows symlink prerequisite, and the OpenSpec init and update guidance. Refreshes itself.
docs/GLOBAL_SETUP.md	Installing the same skills, subagents and gate into your home directory so every project on the machine inherits them, per agent and per shell.

This repo only

File	What's in it
docs/agent-compatibility.md	Per-surface matrix of what each agent reads and what its hook surface can actually block.
docs/repository-layout.md	Canonical versus generated versus symlink, the full tree, and instruction precedence per agent.
docs/hooks-contract.md	The hook runner contract: discovery, the JSON envelope, ordering, exit codes, and the fail-open rules for writing a new hook.
docs/manual-setup.md	Fallback steps when the standard `git checkout` flow needs manual help (symlink recreation per OS) plus per-agent start commands.
docs/bootstrap-prompt.md	First-run verification prompt to paste into the agent after import. Checks skills, subagents, symlinks, the gate, MCP, and OpenSpec.
AGENTS.md	How to work on the standards themselves: canonical versus generated trees, repo conventions, and the local verification commands.
CONTRIBUTING.md	Branching, commit style, the pipeline triggers, and the local checks a pull request has to pass.
CHANGELOG.md	Release history in Keep a Changelog form.
sandbox-agent/README.md	Containerised end-to-end sandbox. Installs all five agent CLIs, imports the standards into a throwaway project, and asserts each agent discovers them.
e2e/README.md	The capability test suites the sandbox runs, one spec per behaviour, plus how to run a single test or the whole sweep.

Template

File	What's in it
AGENTS.md.example	The one remaining template. Rename to `AGENTS.md` after import, then fill the project-specific sections.

Contributing

Issues and pull requests welcome. For non-trivial changes please open an issue first to discuss the approach. The repo is opinionated by design and direction matters.

Maintained by Łukasz Sarna.

License

MIT, see LICENSE.

Navigation Menu

Repository navigation

About

Repository files navigation

Agent Standards

Why it exists

Prerequisites

Quickstart

Per-agent setup

Claude Code

Codex

OpenCode

Kilo Code

GitHub Copilot

Once you have customised the set

Architecture

Agent support

What's in the box

Configuration

How it compares

Working with subagents

Pulling updates

Docs map

Shipped to consumer projects

This repo only

Template

Contributing

License

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
.agents		.agents
.claude		.claude
.codex		.codex
.github		.github
.kilo		.kilo
.opencode		.opencode
.vscode		.vscode
docs		docs
e2e		e2e
global		global
openspec/schemas/e2e-runbooks		openspec/schemas/e2e-runbooks
sandbox-agent		sandbox-agent
subagents		subagents
tools		tools
.gitattributes		.gitattributes
.gitignore		.gitignore
.mcp.json		.mcp.json
AGENTS.md		AGENTS.md
AGENTS.md.example		AGENTS.md.example
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
main-thread-allowlist.txt		main-thread-allowlist.txt
opencode.json		opencode.json

Latest commit

History

Folders and files

Repository files navigation

Agent Standards

Why it exists

Prerequisites

Quickstart

Per-agent setup

Claude Code

Codex

OpenCode

Kilo Code

GitHub Copilot

Once you have customised the set

Architecture

Agent support

What's in the box

Configuration

How it compares

Working with subagents

Pulling updates

Docs map

Shipped to consumer projects

This repo only

Template

Contributing

License

About

Topics

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages