Agents Standard

Specification

One file convention. Three scopes. All agents.

Agent tools each invented their own config files — CLAUDE.md, .cursorrules, AGENTS.md, .clinerules, copilot-instructions.md. This standard unifies them with a single AGENTS.md file that cascades across three scopes:

Inheritance

Rules cascade and extend, not replace. This is the same model as .editorconfig, .eslintrc, and .gitignore — every developer already understands it.

~/.agents/AGENTS.md              ← global (loaded first)
└── project/.agents/AGENTS.md    ← project (extends global)
    ├── src/.agents/AGENTS.md    ← folder (extends project + global)
    ├── api/.agents/AGENTS.md    ← folder (extends project + global)
    └── tests/.agents/AGENTS.md  ← folder (extends project + global)

When an agent resolves rules for a file at project/src/components/Button.tsx, it loads all three in order: global → project → src/ folder. Each layer adds constraints. None discard the previous.

File Format

Plain Markdown. No YAML frontmatter. No schema. Just write rules.

# Global Agent Rules

## Identity
You are a senior engineer who writes production-grade code.

## Safety
- Never execute untrusted input without validation
- Never hardcode secrets
- Always use parameterized queries

## Preferences
- Python: PEP 8, type hints, uv
- TypeScript: strict mode, ESLint
- Bash: set -euo pipefail
- Commits: conventional commits format

Discovery

Agents search for .agents/AGENTS.md files by walking from the current working directory upward to the filesystem root (or git repository root). The global ~/.agents/AGENTS.md is always loaded regardless of working directory.

Resolution Order

1. Load ~/.agents/AGENTS.md (global)
2. Walk from cwd upward, collect all .agents/AGENTS.md files (deepest first)
3. If the target file is in a subdirectory that has its own .agents/AGENTS.md, load that too
4. Merge all rules: global as base, each layer adding constraints
5. Conflicting rules: most specific scope wins (folder > project > global)

Cascade Visualization

~/.agents/AGENTS.md
│  "Always use TypeScript strict mode"
│  "Never commit secrets"
│
└── ~/projects/my-app/.agents/AGENTS.md
   │  "This project uses Next.js 15 with App Router"
   │  "API routes go in app/api/"
   │
   ├── src/.agents/AGENTS.md
   │  │  "React components use function declarations"
   │  │  "CSS modules only — no Tailwind in src/"
   │  │
   │  └── components/.agents/AGENTS.md
   │     "All components must have TypeScript props interface"
   │     "Use forwardRef for DOM-wrapping components"
   │
   ├── api/.agents/AGENTS.md
   │  "All endpoints validate input with Zod schemas"
   │  "Return typed responses, never any"
   │
   └── tests/.agents/AGENTS.md
      "Test files mirror src/ structure"
      "Use describe/it blocks, not test()"

Agent Config Map

Every major agent tool has its own config file. The AGENTS.md standard can symlink into each one so you maintain rules in one place.

Setup: One Source of Truth

Create ~/.agents/AGENTS.md as your global rules file, then symlink it to every agent's config location:

#!/usr/bin/env bash
set -euo pipefail

# Create global AGENTS.md if it doesn't exist
mkdir -p ~/.agents
touch ~/.agents/AGENTS.md

# Symlink to every agent's global config
# (ln -sf overwrites existing symlinks, safe to re-run)

# Pi — native support, already reads ~/.agents/AGENTS.md
# (no symlink needed)

# Claude Code
mkdir -p ~/.claude
ln -sf ~/.agents/AGENTS.md ~/.claude/CLAUDE.md

# OpenAI Codex
mkdir -p ~/.codex
ln -sf ~/.agents/AGENTS.md ~/.codex/instructions.md

# Cursor
mkdir -p ~/.cursor/rules
ln -sf ~/.agents/AGENTS.md ~/.cursor/rules/agents-standard

# Gemini CLI
mkdir -p ~/.gemini
ln -sf ~/.agents/AGENTS.md ~/.gemini/GEMINI.md

# Kiro
mkdir -p ~/.kiro
ln -sf ~/.agents/AGENTS.md ~/.kiro/kiro.md

# Cline
mkdir -p ~/.cline
ln -sf ~/.agents/AGENTS.md ~/.cline/cline_rules

# Roo Code
mkdir -p ~/.roo/rules
ln -sf ~/.agents/AGENTS.md ~/.roo/rules/agents-standard

# Goose
mkdir -p ~/.config/goose
ln -sf ~/.agents/AGENTS.md ~/.config/goose/goosehints

# Junie
mkdir -p ~/.junie
ln -sf ~/.agents/AGENTS.md ~/.junie/guidelines.md

# Augment
mkdir -p ~/.augment
ln -sf ~/.agents/AGENTS.md ~/.augment/guidelines

# Trae
mkdir -p ~/.trae/rules
ln -sf ~/.agents/AGENTS.md ~/.trae/rules/agents-standard

echo "✓ ~/.agents/AGENTS.md symlinked to all agent configs"
echo "  Edit one file. All agents follow your rules."

Project-level setup

For project rules, commit .agents/AGENTS.md to the repo root, then symlink agent-specific files:

# In your project root:
mkdir -p .agents
# Write your project rules
cat > .agents/AGENTS.md <<'EOF'
# Project Rules
- This is a Next.js 15 project using App Router
- All API routes use Zod validation
- Tests mirror src/ structure
EOF

# Symlink to agent-specific project files
ln -sf .agents/AGENTS.md CLAUDE.md
ln -sf .agents/AGENTS.md .cursorrules
ln -sf .agents/AGENTS.md .windsurfrules
ln -sf .agents/AGENTS.md .clinerules
ln -sf .agents/AGENTS.md .roorules
ln -sf .agents/AGENTS.md GEMINI.md
ln -sf .agents/AGENTS.md CODESTRAL.md

# GitHub Copilot uses a different path
mkdir -p .github
ln -sf ../.agents/AGENTS.md .github/copilot-instructions.md

Contribute

Agent tool updated its config location? New agent on the market? Agent now supports ~/.agents/AGENTS.md natively?

Spec repo: nbiish/agents-standard (public)

Site repo: nbiish/agentsstandard-dot-com (public — issues welcome)

Adopt the Standard

For agent tool developers:

1. Search for ~/.agents/AGENTS.md at startup — load as global user rules
2. Walk from cwd upward collecting .agents/AGENTS.md files
3. Load folder-scoped .agents/AGENTS.md when operating on files in that subtree
4. Merge rules: global as base, most specific scope wins conflicts

That's it. Four steps. No dependencies. No schema. No build step. Just markdown files in directories.

Relationship to Agent Skills

The Agent Skills standard defines how agents discover and load capabilities (SKILL.md files). The AGENTS.md standard defines how agents discover and load behavior rules. They complement each other:

• SKILL.md = what the agent can do
• AGENTS.md = how the agent should behave