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 tooling doc, and config templates. The canonical subagents/ source and tools/ generator stay here.

The canonical source is .agents/skills/, the same directory GitHub Copilot and Cursor read natively for agent skills. 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.

Quickstart

git config core.symlinks true

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

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

git fetch agent-standards

git checkout agent-standards/master -- .agents .claude .opencode .codex .kilocode .github/agents .github/copilot-instructions.md.example .vscode/mcp.json.example docs/AGENT_TOOLING.md docs/MCP_SETUP.md docs/AGENTS-UPDATE.md AGENTS.md.example opencode.json.example .mcp.json.example

cp AGENTS.md.example AGENTS.md

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

Optional next step: copy .mcp.json.example to .mcp.json (Claude Code), opencode.json.example to opencode.json (OpenCode), .kilocode/mcp.json.example to .kilocode/mcp.json (Kilo Code VS Code extension), and .vscode/mcp.json.example to .vscode/mcp.json (GitHub Copilot in VS Code) to enable the shared MCP server set.

Human-side MCP setup lives in docs/MCP_SETUP.md.

Full walkthrough lives in docs/AGENT_TOOLING.md.

Architecture

graph LR
    subgraph AS[agent-standards repo]
      ASK[.agents/skills/<br/>canonical SKILL.md files]
      SU[subagents/<br/>canonical templates]
      GEN[tools/gen_subagents.py]
      SU --> GEN
    end
    AS -->|git checkout production-ready dirs only| P[Your project]
    P --> SK[.agents/skills/]
    P --> CA[.claude/agents/<br/>generated]
    P --> OA[.opencode/agents/<br/>generated · shared by Kilo]
    P --> AG[AGENTS.md]
    SK -.symlink.-> CL[.claude/skills/]
    SK -.symlink.-> OC[.opencode/skills/]
    SK -.symlink.-> CX[.codex/skills/]
    CL --> Claude[Claude Code]
    SK --> Kilo[Kilo Code]
    OC --> OpenCode[OpenCode]
    CX --> Codex[Codex CLI]
    CA --> Claude
    OA --> Kilo
    OA --> OpenCode
    AG --> Claude
    AG --> Kilo
    AG --> OpenCode
    AG --> Codex
    P --> GH[.github/agents/<br/>generated]
    GH --> Copilot[GitHub Copilot]
    SK --> Copilot
    AG --> Copilot

    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,AG,CL,OC,CX,GH consumer
    class Claude,Kilo,OpenCode,Codex,Copilot tool

Two canonical sources in this repo: .agents/skills/ and subagents/. Consumer projects receive only the production-ready dirs: .agents/skills/, generated .claude/agents/, generated .opencode/agents/ (which Kilo Code reads natively, so no separate Kilo directory), and generated .github/agents/ for GitHub Copilot. The subagents/ source and the tools/ generator never ship to consumers.

Full repository layout, agent compatibility matrix, and per-agent instruction precedence: docs/repository-layout.md.

What's in the box

.agents/skills/: canonical SKILL.md files. Source of truth, shared by every agent, shipped to consumers. Browse the catalogue to see what's available.
subagents/ (this repo only): canonical subagent templates. Generator emits per-tool copies.
tools/ (this repo only): gen_subagents.py and pyproject.toml. Emits .claude/agents/, .opencode/agents/, and .github/agents/.
.claude/: Claude Code bridge. .claude/CLAUDE.md imports AGENTS.md, a skills/ symlink, generated agents/.
OpenSpec scaffold: spec-driven workflow. openspec init creates the openspec/ directory in the consumer project; commands land in each tool's native dir. See docs/AGENT_TOOLING.md for the full workflow.
Companion OpenSpec schema (optional): Lukk17/openspec-schemas ships an e2e-runbooks schema for spec-driven end-to-end capability tests through OpenSpec's lifecycle (/opsx:new --schema e2e-runbooks). Install steps live in docs/AGENT_TOOLING.md.
AGENTS.md: shared instructions auto-read by Kilo, OpenCode, Codex, and the Copilot CLI. AGENTS.md.example is the template you copy into a new project.
GitHub Copilot bridge: .github/agents/ holds generated *.agent.md subagents, and .github/copilot-instructions.md.example is the template you copy to .github/copilot-instructions.md so local VS Code and IntelliJ chat pick up the standards.
MCP scaffolds: .mcp.json.example, opencode.json.example, .kilocode/mcp.json.example, .vscode/mcp.json.example, and docs/MCP_SETUP.md for the human setup.

Server list and configuration live in docs/MCP_SETUP.md. All entries use ${VAR} or {env:VAR} substitution with defaults baked in.

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; 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 two tool-specific copies that are shipped.

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 .claude/agents/ and .opencode/agents/.
Kilo Code reads .opencode/agents/ natively per its current docs, so there is no separate Kilo directory.
Codex CLI has no per-agent file mechanism. It sees AGENTS.md plus shared skills only.
Run the generator after any canonical change and commit both the source and the generated output.
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 shipped docs (docs/AGENT_TOOLING.md, docs/MCP_SETUP.md, and docs/AGENTS-UPDATE.md itself).
Enumerate the skills already in the consumer's .agents/skills/ and pull only those (no surprise additions).
Enumerate the subagents already in .claude/agents/ and .opencode/agents/ and pull only those.

Files intentionally NOT touched by the update: the symlinked skill directories (.claude/skills/, .opencode/skills/, .codex/skills/), .claude/CLAUDE.md, AGENTS.md.example, the .kilocode/*.example templates, opencode.json.example, .mcp.json.example, and the consumer's customised AGENTS.md.

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	Prerequisites, key acquisition, env-var export per OS, Claude Desktop and Codex CLI global configs, verification.
docs/AGENTS-UPDATE.md	Per-OS selective update commands. Refreshes the shipped docs, plus the skills and subagents already present, and itself.

This repo only:

File	What's in it
docs/repository-layout.md	Repo structure, agent compatibility matrix, instruction precedence per agent.
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, MCP runtime, OpenSpec, instruction tree.

Template:

File	What's in it
AGENTS.md.example	Source instructions template. Copy to `AGENTS.md` after import; consumer projects 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.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Agent Standards

Why it exists

Quickstart

Architecture

What's in the box

How it compares

Working with subagents

Pulling updates

Docs map

Contributing

License

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 46 Commits
.agents/skills		.agents/skills
.claude		.claude
.codex		.codex
.github		.github
.kilocode		.kilocode
.opencode		.opencode
.vscode		.vscode
docs		docs
subagents		subagents
tools		tools
.gitattributes		.gitattributes
.gitignore		.gitignore
.mcp.json.example		.mcp.json.example
AGENTS.md		AGENTS.md
AGENTS.md.example		AGENTS.md.example
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
opencode.json.example		opencode.json.example

Folders and files

Latest commit

History

Repository files navigation

Agent Standards

Why it exists

Quickstart

Architecture

What's in the box

How it compares

Working with subagents

Pulling updates

Docs map

Contributing

License

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages