AGENTS.md for Teams: One Standard, Every AI Tool

AGENTS.md is the one instructions file that nearly every AI coding agent can read — and for teams, that's the whole point. Instead of five developers maintaining five tool-specific rules files that slowly drift apart, you commit a single AGENTS.md at the repo root, review changes to it like code, and every agent on the team works from the same playbook.

The team playbook is short: keep one root AGENTS.md as your shared, reviewed team AI instructions; add nested AGENTS.md files in monorepo packages where conventions genuinely differ; bridge the couple of tools that don't read it natively; and move anything long or procedural into skills so the file stays lean. This post walks through each step. If you want the full format reference and migration path first, start with our complete AGENTS.md guide.

Why One AGENTS.md Beats Per-Tool Configs

Here's the failure mode every mixed-tool team eventually hits. One developer runs Cursor with .cursor/rules/. Another runs Claude Code with a CLAUDE.md. A third uses Codex CLI, a fourth GitHub Copilot. Each file started as a copy of the same conventions — then someone updated the test command in one of them and forgot the rest.

Now the agents disagree. Cursor generates code that passes one lint config, Claude Code follows an outdated import convention, and code review becomes the place where the differences get caught — the most expensive possible place.

A single AGENTS.md fixes the structural problem:

• One source of truth. There is exactly one file to update when a convention changes.
• One review surface. Changes to agent behavior go through one PR, visible to everyone.
• Tool-agnostic onboarding. A new hire clones the repo and their agent — whichever one — picks up the rules immediately.
• No proprietary syntax. It's plain markdown, so it's reviewable by humans and readable by any tool without a parser.

Per-tool files still have a place for genuinely tool-specific settings, but the shared conventions — stack, commands, style, boundaries — belong in one file.

What Belongs in a Team's Root AGENTS.md

Treat the root file as the minimum context an agent needs on every task, in any part of the repo. A good target is under 150 lines. Five sections cover most teams:

1. Project overview — what the repo is, how it's laid out, one or two sentences each.
2. Commands — install, dev, test, lint, typecheck. Exact commands, not prose.
3. Conventions — the rules that apply everywhere: language settings, import style, naming, error handling.
4. Boundaries — what agents must never touch: generated files, secrets, infra directories.
5. PR expectations — commit format, scope, what must be updated alongside code.

A realistic root file:

# AGENTS.md

## Project
Monorepo for Acme's storefront. pnpm workspaces + Turborepo.
Apps live in apps/, shared packages in packages/.

## Commands
- Install: pnpm install
- Dev: pnpm dev
- Test: pnpm test (Vitest — run before every commit)
- Lint + typecheck: pnpm lint && pnpm typecheck

## Conventions
- TypeScript strict mode; no `any` without a comment explaining why
- Named exports only; no default exports outside Next.js pages
- Server code never imports from apps/web/src/components

## Boundaries
- Never edit generated files (src/gen/**, *.d.ts)
- Never commit .env* files; ask before touching infra/

## PRs
- Conventional commits; one logical change per PR
- Update the relevant package README when behavior changes

Notice what's not there: no release runbooks, no API reference, no ten-step migration procedures. Every line in this file is loaded into the agent's context on every task, so every line has to earn its place. We'll come back to where the heavyweight content goes.

Nested AGENTS.md in Monorepos: Precedence in Practice

The AGENTS.md monorepo story is where the standard earns its keep for larger teams. A root file can't honestly describe both your Next.js frontend and your Go billing service — so you don't make it try. You nest.

repo/
  AGENTS.md              ← universal: layout, commands, global conventions
  apps/
    web/
      AGENTS.md          ← Next.js specifics: routing, styling, data fetching
    api/
      AGENTS.md          ← service specifics: error handling, DB access rules
  packages/
    ui/
      AGENTS.md          ← component library: props conventions, a11y bar

Precedence in practice comes down to four rules:

1. Closest file wins. Tools that support nesting (Codex CLI reads root and nested files natively) apply the AGENTS.md nearest to the files being edited, layered on top of the root. Work in apps/api and the agent sees the root file plus apps/api/AGENTS.md.
2. Nested files hold deltas only. Don't restate the root — every duplicated line is a future contradiction. A nested AGENTS.md should read like a diff: "in this package, additionally…"
3. Override explicitly, never silently. If a package breaks a repo-wide rule, say so: "Unlike the repo default, this package uses default exports because the plugin loader requires them." Agents handle explicit exceptions well; they handle silent contradictions badly.
4. Stay shallow. Root plus one level covers almost every real codebase. Three levels of nested AGENTS.md files means humans can no longer predict what an agent will read.

Monorepos have more context problems than instruction files alone can solve — scoping rules per package, keeping generated code off-limits, per-team conventions. Our guide to AI rules for monorepos goes deeper on the full setup.

Cross-Tool Coverage: Which Agents Honor It

As of mid-2026, most agents read AGENTS.md natively, and the holdouts are easy to bridge:

The Claude Code bridge is a one-liner — keep AGENTS.md as the source of truth and make CLAUDE.md delegate:

# Option 1: import (CLAUDE.md stays a real file you can extend)
echo "@AGENTS.md" > CLAUDE.md

# Option 2: symlink (identical content, zero maintenance)
ln -s AGENTS.md CLAUDE.md

Either way, commit the bridge files to the repo. The goal is that a teammate's tool choice never determines whether they get the team's instructions.

The Review Workflow: PRs on Your Team AI Instructions

Your team AI instructions change agent behavior for everyone, on every task, in every tool. That's a production configuration file, and it deserves the same discipline as one. Four steps:

1. Assign ownership with CODEOWNERS

# .github/CODEOWNERS
AGENTS.md          @acme/platform
**/AGENTS.md       @acme/platform

Someone has to be accountable for the file's quality, and nested files shouldn't be a back door around review.

2. Change it only via PR

No direct commits to instructions, ever. In the PR description, state the behavior change in before/after terms: "Agents currently suggest fetch wrappers; after this change they must use the shared apiClient." That framing forces the author to articulate what the edit actually does.

3. Test the change before merging

Instructions are code that runs inside a language model — so run it. Check out the branch, give your agent a representative task in the affected area, and confirm the new rule actually changes the output. A rule an agent ignores isn't a rule; it's wishful thinking in markdown.

4. Keep diffs small and dated

One convention change per PR. Six months later, git blame on any line of AGENTS.md should lead to a PR that explains why the rule exists — which is exactly how your team already treats lint configs and CI pipelines. History is documentation.

What Doesn't Belong — Use Skills Instead

AGENTS.md is always-on context. That makes it the wrong home for anything long, procedural, or situational:

• Runbooks and procedures — "how we do a release," "how to add a database migration"
• Reference material — API docs, schema descriptions, style guides with dozens of examples
• Scripts and templates — anything that's a file, not an instruction
• Tool- or task-specific workflows — needed for one job in twenty, dead weight the other nineteen

Stuff those into the root file and it balloons to 800 lines, taxes every request, and buries the ten rules that actually matter. The better model: instructions that apply always live in AGENTS.md; capabilities an agent needs sometimes live in skills that load only when relevant.

That's the model localskills.sh is built around. Each skill is a package with a root SKILL.md — and it can carry docs, scripts, and templates alongside it as a multi-file folder package. Skills are versioned with rollback, so an instruction change that misfires is a one-command revert rather than a git archaeology session. Publish once, and the CLI writes each tool's native format from the same source:

localskills install acme/release-runbook --target cursor claude windsurf
# → .cursor/rules/*.mdc, .claude/skills/, .windsurf/rules/

Organizations get folders, member roles, and folder-level access restrictions on top — and GitHub sync mirrors the whole skill library to a repo, so skill edits go through the same PR review workflow as your AGENTS.md. If you're formalizing this for a whole engineering org, the team standardization guide covers the rollout end to end.

FAQ

AGENTS.md vs CLAUDE.md: do we still need both?

Keep AGENTS.md as the single source of truth and make CLAUDE.md a one-line @AGENTS.md import or a symlink. That resolves the agents.md vs claude.md question without maintaining two files: Claude Code stays fully supported, and there's still only one document to review and update.

How long should a team's AGENTS.md be?

Under roughly 150 lines for the root file. If it's growing past that, the overflow is usually either package-specific (move it to a nested AGENTS.md) or procedural (move it to a skill). Length isn't just aesthetics — everything in the file consumes context on every single task.

Do nested AGENTS.md files replace the root file?

No. They layer. Tools apply the nearest file on top of the root, so nested files should contain only what's different about that package. If a nested file restates half the root, drift is already underway.

How do we share the same instructions across many repos?

Committing AGENTS.md works per-repo; the cross-repo copies are where drift returns. Publish the shared conventions as a skill in a central registry and install it in each repo instead — every repo pulls the same versioned source, and updates roll out with an install rather than forty copy-pastes. Our guide to sharing AI rules across remote teams covers the distribution patterns.

---

One AGENTS.md keeps every agent on your team reading from the same page — skills carry everything that doesn't fit.

npm install -g @localskills/cli
localskills login
localskills publish

Set up your team's shared skill library on localskills.sh.