<div align="center">

Agent Standards

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

agent-standards quickstart demo

</div>

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 and the Copilot CLI, opencode.json for OpenCode and Kilo Code, .codex/config.toml for Codex, .vscode/mcp.json for Copilot in VS Code, and .github/mcp.json, the Copilot CLI fallback for a folder that has no .mcp.json. 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 take an upstream change to its hook tables with the .codex/config.toml command under Taking only the gate half. 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 .mcp.json, the file Claude Code reads, and expands its ${VAR:-default} entries, measured on Copilot CLI 1.0.103 on 2026-10-25. 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.

.github/mcp.json is kept only as a fallback. The CLI reads it only in a folder that has no .mcp.json, because when both files are in one folder it reads .mcp.json and not .github/mcp.json at all, measured on 1.0.103 on 2026-10-25. The full Quickstart above pulls both files, so there the CLI reads .mcp.json. The Copilot block below pulls only .github/mcp.json, so there the CLI reads the fallback. 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.

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 and the Copilot CLI), opencode.json (OpenCode and Kilo Code),

.codex/config.toml (Codex), .vscode/mcp.json (Copilot in VS Code), and .github/mcp.json (the Copilot CLI fallback, read only in a folder that has no .mcp.json). Five real files, not templates.

Server list and configuration live in docs/MCP_SETUP.md. Claude Code's file, which the Copilot CLI reads too, uses ${VAR} with defaults. The others hardcode their URLs, because the OpenCode and VS Code syntax has no fallback form and Codex has no substitution, and the Copilot fallback file hardcodes them as well. 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 servers, apart from the exceptions listed in docs/MCP_SETUP.md, 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

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/<name>.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

#### This repo only

#### Template

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.