AGENTS.md and SKILL.md: The Complete Guide (2026)

Coding agents have become the default interface for a growing share of professional software work. They are also, individually, terrible at remembering project conventions across sessions. AGENTS.md is the format the industry settled on to fix that — a single Markdown file in the repository root that any agent can read on task start, giving it the build commands, test commands, code-style rules, and "do not touch" boundaries that would otherwise need to be re-stated in every prompt.

This guide is for engineering leads picking a standard for their team, OSS maintainers deciding what to commit alongside README.md, and anyone who has watched an AI agent re-invent the wheel for the fourth time in a row and asked "is there a config file for this?" There is. This is it.

Last updated: May 23, 2026.

TL;DR

• What it is: AGENTS.md is an open, vendor-neutral Markdown format placed at the project root. It contains the operational context — build commands, test commands, conventions, boundaries — that AI coding agents need but that doesn't belong in a human-facing README.md.
• Who reads it: Native support in OpenAI Codex, Cursor, GitHub Copilot coding agent, Gemini CLI, Windsurf, Aider, Zed, Factory, Jules, Devin, Amp, Kilo, RooCode, Augment, Warp, JetBrains Junie, Ona, Phoenix, UiPath, Semgrep, and more. Claude Code reads CLAUDE.md instead, but the standard workaround is to @AGENTS.md-import it from CLAUDE.md.
• Governance: Stewarded by the Agentic AI Foundation under the Linux Foundation, originally driven by OpenAI, Amp, Google (Jules), Cursor, and Factory.
• Format: Plain Markdown. No required fields, no YAML frontmatter (yet — v1.1 proposes optional description and tags). Pick whatever H2s make sense for your repo.
• Monorepos: Nest one per package; agents walk from the working file up to the repo root and the nearest AGENTS.md wins. OpenAI's own Codex monorepo ships 88 nested AGENTS.md files.
• Adoption: 60,000+ repositories at time of writing; the format has become the de-facto standard since formal stewardship moved to the Linux Foundation.
• Related: SKILL.md is Anthropic's separate, more structured spec for packaging reusable agent skills with YAML frontmatter and bundled scripts/references. It is complementary to AGENTS.md, not a competitor.

What is AGENTS.md?

AGENTS.md is a single, conventionally-named Markdown file placed at the root of a code repository. It contains operational context for AI coding agents: the build pipeline, the test command, the directory layout, the code-style conventions, the things that will get a junior engineer fired if they violate them. Any agent that supports the format reads it on task start and treats the contents as system-prompt-level guidance.

The official spec describes it as "a simple, open format for guiding coding agents" and the analogy is exactly right: AGENTS.md is to coding agents what README.md is to humans. The two files coexist because they serve different audiences. A README.md answers "what is this project, how do I clone it, what does it do." An AGENTS.md answers "if you're an agent about to modify code in this repo, here is what you need to know that the README would never bother to spell out."

The format is intentionally radical in its simplicity:

• Plain Markdown.
• No required headings.
• No mandatory YAML frontmatter.
• No custom syntax.
• No build step.
• No vendor SDK.

You write Markdown. Agents read Markdown. The simplicity is the feature — the format only works as a cross-vendor standard if no vendor is incentivised to fork it.

Why AGENTS.md matters

Three structural problems forced the industry toward a single standard:

Context windows are finite

Every byte of repo context a coding agent loads competes with the byte of diff it could be writing. Without AGENTS.md, agents either over-read (open every file under src/ to "understand the project") or under-read (skip the file with the test command and run the wrong one). A 200-line AGENTS.md at the root eliminates both failure modes. The agent loads it once, knows the test command, knows the file layout, and spends the rest of its context budget on actual code.

Agents need to be portable between tools

In 2024 every coding tool had its own config format: .cursorrules for Cursor, .continuerules for Continue, .copilot-instructions.md for Copilot, CLAUDE.md for Claude Code, custom YAML for Aider, and so on. Teams using more than one tool had to maintain N parallel files that drifted apart over time. AGENTS.md is the convergence point: write one file, every agent reads it, switching tools is a no-op.

Onboarding an agent is onboarding

The best AGENTS.md files read like the README of a well-run engineering team — the document you'd hand a new hire on day one. That overlap is not accidental. Anything that helps an LLM understand a repo also helps a human understand it. Teams that take AGENTS.md seriously end up with better-documented codebases as a side effect.

Which coding agents support AGENTS.md

The list below reflects native support — meaning the agent reads AGENTS.md from the repo root automatically, without a wrapper script or config flag. It is current as of May 2026.

The practical takeaway: if you commit one file, commit AGENTS.md. It is read by the broadest set of tools. If your team standardises on Claude Code, also commit a one-line CLAUDE.md that imports it.

Picking the right coding agent before you write AGENTS.md? Our AI coding agents complete guide compares Cursor, Claude Code, Codex, Gemini CLI, Aider, Cline, Continue, and the rest head-to-head — pricing, autonomy, IDE vs terminal, and where each one wins.

Spec deep-dive: format and (optional) frontmatter

The shape of the file

A canonical AGENTS.md is plain Markdown with H2 sections. There is no required ordering, no required heading set, no required heading text. The spec's only normative guidance is "use whatever headings make sense for the project."

That said, the popular sections — the ones GitHub identified across 2,500+ analysed repositories and that the spec lists as recommended — are:

• Project overview — one paragraph on what this code does and the architectural shape (monolith, monorepo, microservices, etc.).
• Setup and build commands — every command needed to get from git clone to a running build. Include flags and options.
• Test commands — how to run the test suite, how to run a single test, how to run a single suite.
• Code style guidelines — formatter, linter, naming conventions, file-layout expectations. Cite the config file if one exists.
• Project structure — directory tree (top 2–3 levels) with one-line descriptions per top-level folder.
• Git / PR conventions — branch naming, commit message format, PR description template.
• Security and secrets — what must never be committed, which paths are protected, where to put env vars.
• Boundaries — three tiers: always do, ask first, never do. This is the section that prevents agent runaway.

Optional YAML frontmatter (v1.1 proposal)

The current 1.0 spec defines no YAML frontmatter. Issue #135 proposes a 1.1 revision that adds two optional fields:

---
description: Short summary (<200 chars) of what this AGENTS.md governs.
tags: [backend, api, python]
---

The rationale is progressive disclosure: in monorepos with dozens of nested AGENTS.md files, harnesses want to index them at session start without paying the token cost of reading every body. Frontmatter lets the agent see "there is an AGENTS.md at packages/api/AGENTS.md, it covers the backend API, it has the python tag" without loading the file.

Status as of May 2026: open, not merged. Some harnesses (notably Copilot's custom-agent profiles and parts of Codex) already parse optional frontmatter for forward-compatibility; most agents simply ignore it. Don't depend on frontmatter for correctness. Do feel free to include it — it costs nothing and pays off when v1.1 ships.

Parser behaviour

Different agents parse with subtly different rules:

• Codex concatenates root-down, joined with blank lines; skips empty files; caps total at project_doc_max_bytes (32 KiB default).
• Factory walks nearest-first; closest file in the directory tree wins on conflict.
• Cursor applies the file as rules alongside .cursor/rules/*.mdc; explicit rules override AGENTS.md guidance.
• Kilo Code places AGENTS.md third in its priority stack: agent-specific prompts > project-level custom instructions > AGENTS.md > global custom instructions > skills.
• Claude Code reads CLAUDE.md by default; the import syntax @AGENTS.md at the top of CLAUDE.md pulls the AGENTS file inline.

The differences are minor enough that they don't change how you author the file — write a single, well-structured AGENTS.md and every tool will do something reasonable with it.

AGENTS.md vs .cursorrules vs CLAUDE.md vs system prompts

Most teams end up with two or three of these files in the same repo. The right decomposition is:

Concrete rule of thumb: if you would tell every new engineer this, it belongs in AGENTS.md. If you would tell only the engineer using Claude Code, it belongs in CLAUDE.md. If it is a packaged, reusable capability with code, it belongs in a SKILL.md. If it changes every task, it stays in the prompt.

Five real-world AGENTS.md examples worth studying

The patterns below come from AGENTS.md files in production repositories. They are not the only valid shapes, but they are representative of what high-quality engineering teams ship.

Example 1: The minimal canonical example

From the official agents.md spec page. Useful as a starter for any repo:

# MyApp

## Dev environment tips
- Use `pnpm dlx turbo run where <project_name>` to jump to a package instead of scanning with `ls`.
- Run `pnpm install --filter <package_name>` to add a package to your workspace.

## Testing instructions
- Find the CI plan in the `.github/workflows` folder.
- Run `pnpm turbo run test --filter <project_name>` from the package root.
- Always add or update tests for the code you change.

## PR instructions
- Title format: `[<project_name>] <Title>`
- Always run `pnpm lint` and `pnpm test` before committing.

Example 2: GitHub's spec-kit (real, large)

The github/spec-kit AGENTS.md documents an "integration architecture" for adding new AI agents to a CLI toolkit. Sections include About Spec Kit and Specify, Integration Architecture, Adding a New Integration (a seven-step playbook), Command File Formats (Markdown vs TOML vs YAML), Argument Patterns ($ARGUMENTS vs {{args}} vs {SCRIPT}), Branch Naming Convention, and Common Pitfalls. The file is dense, opinionated, and treats the agent like a teammate who needs to know the team's conventions on day one.

Example 3: Node monorepo with scoped boundaries

Factory's documentation shows a Node monorepo with this shape:

# Acme Platform

## Stack
- TypeScript 5.4, pnpm 9, Turbo 2, Vite 5, Postgres 16.

## Layout
- packages/api    → Express server (only edit code here for API changes)
- packages/web    → React + Vite (only edit code here for UI changes)
- packages/shared → cross-cutting types and zod schemas

## Commands
- Install:  `pnpm install`
- Dev:      `pnpm dev`
- Test:     `pnpm test --filter <package>`
- Lint:     `pnpm lint`
- Build:    `pnpm build`

## Boundaries
- Never edit `prisma/migrations/`; generate via `pnpm db:migrate`.
- Never commit `.env*` files.
- Ask before adding a new top-level dependency.

## PRs
- Conventional commits.
- Squash on merge.
- Include a `Testing` section in the PR body.

Note the Layout section's "only edit code here for X" — this is one of the highest-leverage patterns. A single sentence per package eliminates the most common monorepo agent failure: cross-package edits that shouldn't exist.

Example 4: Polyglot repo with language-specific blocks

# DataPlatform

## Languages
This repo is Python + Go + TypeScript. Each top-level service is single-language.

### Python services
- Format: `ruff format`, then `ruff check --fix`.
- Type-check: `mypy --strict`.
- Test: `pytest -x`.

### Go services
- Format: `gofumpt -w`.
- Vet:    `go vet ./...`.
- Test:   `go test -race ./...`.

### TypeScript services
- Format: `biome format --write`.
- Lint:   `biome check`.
- Test:   `vitest run`.

## Boundaries
- Never call a Go service from a Python service directly; always go through the gRPC contracts in `protos/`.
- Never edit generated protobuf code in `gen/`. Regenerate via `buf generate`.

Example 5: Framework-specific (Next.js)

# MyShop

## Stack
Next.js 16 (Pages Router for marketing, App Router for /shop), Tailwind v4 in /shop only, styled-components in marketing only.

## Setup
- Node 22.x, pnpm 9.
- `pnpm install`
- `pnpm dev` → http://localhost:3000

## Test
- `pnpm test`         → vitest unit
- `pnpm e2e`          → Playwright
- `pnpm lint:check`   → ESLint
- `pnpm type:check`   → tsc --noEmit

## Conventions
- Pages Router files: kebab-case (`product-detail.tsx`).
- App Router routes: lowercase, no underscores.
- Server components by default; mark client components with the `'use client'` directive at the top.
- Tailwind classes only in `app/shop/**`; styled-components only in `pages/**`.

## Don't
- Don't mix Tailwind and styled-components in the same file.
- Don't add new Pages Router routes; new routes go in App Router under `app/shop/`.
- Don't commit `.env.local` or anything in `secrets/`.

Patterns that actually change agent behaviour

The reason AGENTS.md works is not because LLMs are great at following instructions — they aren't. It's that certain phrasings dramatically improve adherence. Patterns we've seen consistently move the needle:

• Imperative voice, not descriptive. "Run pnpm test before every commit" works better than "this project uses pnpm test for testing."
• Three-tier boundaries. Group rules into always do, ask first, and never do. The explicit hierarchy gives the agent a clean classification problem instead of an open-ended judgement call.
• Concrete commands with flags. "Run pytest -x --tb=short tests/unit" beats "run the unit tests."
• Tech stack with version numbers. "Node 22.x, pnpm 9, Vite 5" beats "modern JS stack."
• Real code examples. A 5-line example of your preferred error-handling pattern is worth a paragraph of prose.
• Scope sentences per directory. "Backend code only in packages/api/src/" eliminates a class of failures by itself.
• Generated-file guards. List every directory that is regenerated by a build step (gen/, __generated__/, migrations/, dist/) and tell the agent never to edit them.

Anti-patterns: ten things not to do

1. Don't write a persona. "You are a helpful AI assistant who loves clean code" wastes tokens and changes nothing. The agent already knows it is an agent.
2. Don't paste your README. Duplicating README.md content in AGENTS.md doubles maintenance and signals nothing new to the agent.
3. Don't include marketing copy. "Acme Platform is the leading developer-first observability solution" is text the agent does not need.
4. Don't write essays. If a section is over ~30 lines, it is probably reference documentation that belongs in docs/ and should be linked, not inlined.
5. Don't restate language defaults. "Use Python 3" is implicit from pyproject.toml. "Use Python 3.12 with the uv package manager, not pip" is useful.
6. Don't conflict with .cursorrules / CLAUDE.md. If you keep more than one rules file, treat AGENTS.md as the source of truth and have the others @import it.
7. Don't include secrets. Real API keys, real DB connection strings, real internal URLs. The file is in version control; assume it leaks.
8. Don't be vague about "good code". "Write clean, idiomatic code" is signal-free. "Use Result<T, E> for fallible operations, never raise unchecked exceptions" is signal.
9. Don't ship a 2000-line file. Codex caps at 32 KiB. Most agents start ignoring after the first few thousand tokens. Keep it under ~500 lines; push the rest into nested per-package files or docs/.
10. Don't forget to update it. Stale AGENTS.md is worse than no AGENTS.md — the agent will confidently follow rules that no longer apply. Treat it like the README: update in the same PR as the change it documents.

Building an AGENTS.md for a Cursor-heavy team? Read our Cursor IDE complete guide for the deeper story on how Cursor parses AGENTS.md alongside .cursor/rules/*.mdc, when path-scoped MDC rules beat a global AGENTS.md, and which Project Rules to set for a 10-engineer team.

Monorepo patterns: nested AGENTS.md files

The single biggest scale lever in the spec is nested AGENTS.md. You can put one at the repo root and one inside packages/api/ and one inside packages/web/. Agents walk up the directory tree from the file they're editing and combine every AGENTS.md they encounter, with the closest one winning on conflicts.

OpenAI's own Codex monorepo ships 88 nested AGENTS.md files — one per service or package. The shape is:

repo/
├── AGENTS.md               # global: stack, root commands, branch naming
├── packages/
│   ├── api/
│   │   ├── AGENTS.md       # api: Express, Postgres conventions, test command
│   │   └── src/...
│   ├── web/
│   │   ├── AGENTS.md       # web: React, Tailwind, Vite, component conventions
│   │   └── src/...
│   └── shared/
│       ├── AGENTS.md       # shared: zod schemas, no DB imports allowed
│       └── src/...
└── tools/
    └── etl/
        ├── AGENTS.md       # etl: Python, pandas, sqlmodel; different lint rules
        └── ...

A few practical rules:

• Defaults at the root, overrides at the leaf. Put the stack, the branch naming, the security boundaries at the root. Put the per-package test command and the per-package conventions at the leaf.
• Don't re-state inheritance. If the root says "pnpm 9," the leaf shouldn't say "pnpm 9" again. The agent already has the root context.
• Codex-only escape hatch: AGENTS.override.md at any level replaces rather than extends parent instructions. Use sparingly; other tools don't honour it.
• Keep nested files short. 30–80 lines each is the sweet spot. The root file can be longer (~200 lines).

SKILL.md: a complementary, not competing, standard

SKILL.md is Anthropic's separate spec for packaging reusable agent capabilities. It is more structured than AGENTS.md, with mandatory YAML frontmatter, a defined directory layout, and a three-level loading model (metadata always loaded, body loaded on trigger, bundled scripts and references loaded on demand).

The shape of a SKILL.md

my-skill/
├── SKILL.md              # required: frontmatter + instructions
├── scripts/              # optional: executable code Claude runs via bash
│   └── validate.py
└── references/           # optional: docs loaded only when explicitly referenced
    └── schema.json

The SKILL.md itself:

---
name: pdf-processing
description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
---

# PDF Processing

## Quick start

Use pdfplumber to extract text from PDFs:

```python
import pdfplumber

with pdfplumber.open("document.pdf") as pdf:
    text = pdf.pages[0].extract_text()
```

For advanced form filling, see [FORMS.md](FORMS.md).

Required frontmatter fields

• name — lowercase, hyphens-only, max 64 characters, cannot contain "anthropic" or "claude" or XML tags.
• description — non-empty, max 1024 characters, no XML tags. This is the primary triggering signal; Anthropic explicitly advises making it "pushy" about use cases to combat under-triggering.

Optional: license. The spec is published in the open at anthropics/skills and at agentskills.io.

When to use SKILL.md vs AGENTS.md

The two formats overlap in spirit (both are filesystem-resident instructions for AI agents) but solve different problems. AGENTS.md answers "how does this repo work?" SKILL.md answers "how does this reusable capability work, and when should you trigger it?" A serious team will use both: AGENTS.md at the repo root, and one or more SKILL.md bundles in .claude/skills/ (Claude Code) or uploaded via the API.

Migrating from .cursorrules to AGENTS.md

.cursorrules is the legacy Cursor format. As of 2026 Cursor still reads it, but the official guidance is to migrate. The mechanical conversion is straightforward:

1. Audit what's in .cursorrules. Most files are 80% universal ("use TypeScript, format with Prettier, prefer functional components") and 20% Cursor-specific ("in Agent mode, ask before deleting files").
2. Move the universal 80% verbatim to AGENTS.md. Same Markdown, same headings — just rename and relocate.
3. Keep Cursor-specific rules in .cursor/rules/*.mdc. The MDC format supports YAML frontmatter (description, globs, alwaysApply) for path-scoped rules. Use MDC for "when editing **/migrations/*.py, always include a down-migration" type rules; use AGENTS.md for "use Postgres parameterised queries" type rules.
4. Delete .cursorrules once AGENTS.md is live, or keep it as a thin pointer that says "see AGENTS.md."
5. If you also use Claude Code, create a one-line CLAUDE.md that opens with @AGENTS.md to import the file into Claude's context.

Teams that complete this migration end up with one source of truth (AGENTS.md), one tool-specific surgical override location per tool, and zero drift between formats.

Comparing Claude Code, Codex, and Cursor head-to-head? Our Claude Code vs OpenAI Codex deep dive walks through how each one reads AGENTS.md in practice, where their fallback behaviours differ, and which to pick for an extended remote team.

AGENTS.md and MCP: how they fit together

A common confusion: does AGENTS.md replace MCP (Model Context Protocol) server configuration? No — they sit at different layers.

• AGENTS.md is project-level instructions: what to do, what not to do, how to test, how to commit.
• MCP servers are project-level tools: an HTTP/stdio endpoint the agent can call to read your database, query your monitoring system, fetch a Jira ticket, or run a custom script.

A well-configured repo has both. AGENTS.md at the root tells the agent "run the test command before committing." A .mcp.json (Claude Code, Codex) or .cursor/mcp.json (Cursor) tells the agent how to call your in-house MCP servers. The instructions in AGENTS.md can reference MCP tools by name ("use the db-readonly MCP server for schema questions, never query the prod DB directly").

Rollout checklist for a 10-engineer team

1. Day 1. Audit every existing tool-specific rules file (.cursorrules, .continuerules, .github/copilot-instructions.md, CLAUDE.md). Note what's universal vs tool-specific.
2. Day 1. Write a 100–200 line AGENTS.md at the repo root covering the 8 recommended sections (overview, setup, test, style, structure, git, security, boundaries).
3. Day 1. Have one engineer who uses each tool (Cursor, Claude Code, Codex, Copilot) run a real task with the new file and report drift. Iterate.
4. Day 2. Add @AGENTS.md at the top of CLAUDE.md, plus any Claude-Code-specific subagent / slash-command guidance.
5. Day 2. Move Cursor-specific path-scoped rules into .cursor/rules/*.mdc; delete or thin .cursorrules.
6. Week 1. Add nested AGENTS.md files for the top 3 packages in the monorepo.
7. Week 2. Wire AGENTS.md updates into the PR template. Any structural change (new test command, new lint rule, new boundary) requires an AGENTS.md edit in the same PR.
8. Month 1. Review the rate of agent rule-violations in code review. Common patterns of violation are signals for new AGENTS.md sections.

FAQ

Is AGENTS.md officially a standard?

Yes — it is stewarded by the Agentic AI Foundation under the Linux Foundation, which gives it vendor-neutral governance. The format originated from collaboration between OpenAI, Amp (Sourcegraph), Google (Jules), Cursor, and Factory, and is now adopted by more than 60,000 public repositories.

Does Claude Code read AGENTS.md natively?

Not directly. Claude Code reads CLAUDE.md by convention. The recommended workaround is to put @AGENTS.md as the first line of CLAUDE.md — Claude Code's @-import syntax pulls the contents of AGENTS.md into its context. Some installs also recognise the singular AGENT.md filename.

Should I write AGENTS.md or .cursorrules?

Write AGENTS.md. .cursorrules is Cursor-only and officially in deprecation. Anything you'd put in .cursorrules works in AGENTS.md and is portable to every other tool.

How long should AGENTS.md be?

Aim for 100–300 lines at the repo root. Codex caps at 32 KiB; other tools start ignoring after the first few thousand tokens. For larger projects, split into nested AGENTS.md per package rather than letting the root file grow past ~500 lines.

Do I need YAML frontmatter?

No. The 1.0 spec defines none. The 1.1 proposal (open, not merged) adds optional description and tags fields. Including them is forward-compatible and costs nothing; depending on them for correctness is not safe yet.

AGENT.md or AGENTS.md?

Always uppercase. Plural is the canonical form (AGENTS.md); singular (AGENT.md) is a fallback that some tools (Kilo, certain Claude Code installs) accept. Don't ship lowercase — case-sensitive filesystems treat agents.md as a different file.

Can I put secrets in AGENTS.md?

Never. The file is committed to version control. Treat it as fully public — anything you wouldn't put in README.md should not be in AGENTS.md. For secrets, document the names of the env vars and where to fetch their values from (Vault, AWS Secrets Manager, 1Password), not the values themselves.

How does the monorepo precedence work exactly?

Tools walk from the file being edited up to the repo root and load every AGENTS.md they pass. The nearest file's instructions take precedence on conflict. Codex concatenates root-down; Factory walks nearest-first; Cursor combines them with explicit MDC rules winning. The differences rarely matter as long as your nested files don't actively contradict the root.

Is SKILL.md the same as AGENTS.md?

No. AGENTS.md is project-level conventions read by 20+ coding agents. SKILL.md is Anthropic's separate spec for packaging reusable capabilities (with required YAML frontmatter, scripts, references, and a progressive-disclosure loading model) read by Claude products. Use both: AGENTS.md for repo conventions, SKILL.md for reusable capability bundles.

Does AGENTS.md affect cost?

Yes, mildly. A 200-line file is ~1–2k tokens, loaded on every agent task. The savings (fewer wrong-direction edits, fewer test-command retries, fewer "what's the lint command?" exchanges) more than offset the load cost in any non-trivial repo. Don't bloat the file past usefulness, but don't optimise for token-thrift either.

What if my agent ignores AGENTS.md?

First, check that the filename is AGENTS.md (uppercase, plural) at the actual working directory. Second, check that the file is under 32 KiB. Third, restart the agent session — most tools load the file on session start, not on every prompt. Fourth, check tool docs for known fallbacks (Claude Code reads CLAUDE.md; Gemini CLI reads both; Cursor needs MDC rules to be enabled in settings).

Should our public OSS repo have AGENTS.md?

Yes. External contributors increasingly use agents to draft PRs against your repo. An AGENTS.md at the root sharply improves the quality of agent-generated contributions, reduces CI cycle waste, and gives human contributors a parallel reading of "how this project actually works." It is now table-stakes for any public repo expecting external contribution.

What this means for engineering leadership

The bar for "AI-ready engineering team" has moved up. Two years ago, having any rules file at all was enough. Today, the teams getting the most out of coding agents have invested in a layered structure: a universal AGENTS.md at the root, nested AGENTS.md per package in monorepos, tool-specific overrides for the agents they standardise on, MCP server configuration alongside, and a process discipline that updates AGENTS.md in the same PR as the change it documents.

For hiring, the signal we look for at Codersera is exactly this orchestration fluency. The engineers who deliver in 2026 don't write the most code by hand — they write the rules files, design the MCP integrations, scope the agent runs, and review the diffs critically. When we vet engineers for client teams, comfort with AGENTS.md authoring, monorepo nesting strategy, and the AGENTS-vs-SKILL.md-vs-MCP decomposition is now part of the technical-fit conversation, not a "nice to have."

References and further reading

• agents.md — official spec page
• agentsmd/agents.md — Linux Foundation repo
• AGENTS.md v1.1 proposal (Issue #135)
• OpenAI Codex — Custom instructions with AGENTS.md
• Factory CLI — AGENTS.md configuration
• Kilo Code — AGENTS.md docs
• GitHub Blog — How to write a great AGENTS.md (lessons from 2,500+ repos)
• anthropics/skills — Anthropic SKILL.md reference repo
• Anthropic — Agent Skills overview
• github/spec-kit — real-world AGENTS.md example
• Codersera — Cursor IDE complete guide 2026
• Codersera — AI coding agents complete guide 2026
• Codersera — Claude Code vs OpenAI Codex (2026)
• Codersera — Best MCP servers for Claude Code and Cursor
• Codersera — Grok Build vs Claude Code vs Codex CLI

Next steps

If you're scaling an engineering team in 2026, the gap between "team with a working AGENTS.md playbook" and "team without one" shows up in code-review velocity, agent-failure rate, and onboarding time within a single sprint. Get the foundation right, and the rest of the AI-coding-agent stack (Cursor, Claude Code, Codex, Copilot, MCP, SKILL.md) compounds on top of it.

If you're extending your engineering team and want senior, vetted, remote engineers who already work this way in production — engineers fluent in AGENTS.md authoring, monorepo nesting, MCP integration, and the agent-orchestration discipline this guide covers: Hire a Codersera-vetted senior engineer. Risk-free trial, faster hiring, lower hiring risk, and engineers who can extend your team without extending your context-switching cost.