Agents Standard

Specification

One file convention. Five-tier loading. All agents.

The standard unifies project instructions by separating what/why (Project PRD) from how (Behavioral Rules):

Loading Model: Scoped Concatenation

Each tier's file is concatenated into the agent's context — not replaced. The project root acts as a ceiling — agents never traverse above it. Your security practices in ~/.agents/AGENTS.md always apply; the project PRD in llms.txt sets functional scope; project base conventions build on top; active task instructions direct the session; and folder-specific rules apply locally. Never read files from parent directories outside the project.

Project Root Detection & Ceiling

Agents detect the project root from the shell's initial $PWD at launch time — the directory the terminal was opened in. Optionally, $AGENTS_ROOT can be set to override this. Agents must never traverse above this ceiling. If a user cd .. past the project root, only ~/.agents/AGENTS.md applies — no parent directory AGENTS.md files are picked up. This prevents accidentally reading unrelated rules (e.g. a github repo management AGENTS.md one level up).

Resolution Order

1. Load ~/.agents/AGENTS.md (global base — always loaded first, user-specific rules)
2. Detect project root from inherited shell $PWD or $AGENTS_ROOT
3. Load {project_root}/llms.txt (project PRD, functional roadmap)
4. Load {project_root}/.agents/AGENTS.md (project base rules, committed)
5. Load {project_root}/AGENTS.md (project active rules, symlinked)
6. Load {cwd}/AGENTS.md if cwd is within project boundary (component rules, optional)
7. Concatenate in order: global → project base → project active → folder
8. Never traverse above the detected project root

Singular Rules File Fallback

If an agent only supports a single rules file, it should read the project root AGENTS.md (or the symlinked file like CLAUDE.md) to get the active task context. This is the canonical touchpoint for active task instructions. Alternatively, it can read the global ~/.agents/AGENTS.md. Tools that only read one file are first-class citizens.

Dual-Layer MCP Configuration

MCP servers follow a two-layer model — global shared, agent-specific extended:

~/.agents/ — One Directory, Everything Agents Need

~/.agents/
├── AGENTS.md              ← Behavior rules (this standard — the canonical global path)
├── mcp-settings.json      ← MCP servers shared across all agents
└── skills/                ← Agent Skills (capabilities)
    └── **/SKILL.md        ← Skills discovered by all agents

Tools using ~/.config/AGENTS.md should move to ~/.agents/AGENTS.md. Users shouldn't have to wonder if their rules are in the right place or if they're overprompting. One directory. Three concerns (behavior, tools, skills). Zero confusion.

AGENTS_DEPTH

Control how many levels of AGENTS.md are loaded downward from project root (never upward) with the AGENTS_DEPTH environment variable:

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.md files by walking from the current working directory upward to the project root. The global ~/.agents/AGENTS.md is always loaded first regardless of working directory. The .agents/ directory at project level holds tooling configuration (MCP servers and skills) and project base rules (in .agents/AGENTS.md).

Cascade Visualization

~/.agents/AGENTS.md                     ← Global Base (user preferences & safety, loaded first)
│  "Always use TypeScript strict mode"
│  "Never commit secrets"
│
└── ~/projects/my-app/
   ├── llms.txt                          ← Project PRD (active requirements, tech stack, APIs)
   │  "App: Next.js 15 template. Focus: implement JWT auth."
   │  "Goal: add /api/auth/register and /api/auth/login endpoints."
   │
   ├── .agents/AGENTS.md                 ← Project Base (tech stack, deployment, committed guidelines)
   │  "This project uses Next.js 15 with App Router"
   │  "Deployment check: run build and verify security headers"
   │
   ├── AGENTS.md                         ← Project Active Rules (active task/feature behavior constraints)
   │  "Ensure all JWT tokens expire in 15 minutes"
   │  "Do not use external auth packages — write vanilla Node cryptography"
   │
   ├── src/AGENTS.md (optional)          ← Folder / Component (directory-scoped guidelines)
   │  │  "React components use function declarations"
   │  │  "CSS modules only — no Tailwind in src/"
   │  │
   │  └── components/AGENTS.md (optional)
   │     "All components must have TypeScript props interface"
   │     "Use forwardRef for DOM-wrapping components"
   │
   ├── api/AGENTS.md (optional)          ← Folder / Component
   │  "All endpoints validate input with Zod schemas"
   │  "Return typed responses, never any"
   │
   ├── tests/AGENTS.md (optional)         ← Folder / Component
   │  "Test files mirror src/ structure"
   │  "Use describe/it blocks, not test()"
   │
   └── .agents/                          ← Tooling (MCP + Skills)
      ├── mcp-settings.json              ← project MCP servers
      └── skills/**/SKILL.md             ← project skills

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. Each path is verified against the agent's official documentation.

MCP Config Map

Each agent also has its own location for MCP server configurations. Here's where every agent stores its MCP settings, verified against official documentation.

The Problem This Standard Solves

LLM Providers

Every agent needs a model. Here are all the LLM API providers, their endpoints, auth patterns, free tiers, and referral links. Plug these into any agent's config.

Referral Links

Sign up through these links to support the Agents Standard project:

Using Providers With Any Agent

Most coding agents support OpenAI-compatible endpoints. Point any agent at a provider by setting the base URL and API key:

# Example: Point Claude Code at OpenRouter
export ANTHROPIC_BASE_URL="https://openrouter.ai/api/v1"
export ANTHROPIC_API_KEY="sk-or-..."

# Example: Point Codex at z.ai
export OPENAI_BASE_URL="https://api.z.ai/api/coding/paas/v4"
export OPENAI_API_KEY="zai-..."

Full structured data: providers.json — machine-readable provider endpoints, auth patterns, and referral codes.

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

# Agy / Gemini CLI
mkdir -p ~/.gemini
ln -sf ~/.agents/AGENTS.md ~/.gemini/GEMINI.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

# Windsurf
mkdir -p ~/.codeium/windsurf
ln -sf ~/.agents/AGENTS.md ~/.codeium/windsurf/rules

# 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

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

# 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

# Crush
mkdir -p ~/.config/crush
ln -sf ~/.agents/AGENTS.md ~/.config/crush/crush.md

# Hermes Agent
mkdir -p ~/.hermes
ln -sf ~/.agents/AGENTS.md ~/.hermes/SOUL.md

# MiniCC
mkdir -p ~/.minicc
ln -sf ~/.agents/AGENTS.md ~/.minicc/AGENTS.md

# Deep Agents (dcode)
mkdir -p ~/.deepagents
ln -sf ~/.agents/AGENTS.md ~/.deepagents/AGENTS.md

echo "Done. Edit ~/.agents/AGENTS.md — all symlinked agents follow your rules."
echo "See https://agentsstandard.com for project-level setup."

Project-level setup

Create llms.txt at your repo root for the Project PRD (functional requirements, scope, tech stack), .agents/AGENTS.md for static project base rules (framework choice, deployment checklists, static guidelines), and create AGENTS.md at your repo root for active task instructions (symlinked to agent-specific configs):

# In your project root:
# 1. Write your Project PRD
cat > llms.txt <<'EOF'
# Project PRD: JWT Authentication
- Stack: Next.js 15, TypeScript, PostgreSQL
- Features: User registration and login with JWT tokens
- APIs: /api/auth/register and /api/auth/login
EOF

# 2. Write your static project rules
mkdir -p .agents
cat > .agents/AGENTS.md <<'EOF'
# Project Base Rules
- Tech stack: Next.js 15 (App Router)
- Linting: ESLint strict mode
- Deployment check: run npm run build and check bundle sizes
EOF

# 3. Write your active session rules
cat > AGENTS.md <<'EOF'
# Active Session
- Focus on JWT cryptography implementation in Node.js
- Do not use external auth packages — write vanilla crypto
- Refer to llms.txt for API schema requirements
EOF

# Symlink agent-specific files to the root AGENTS.md
ln -sf AGENTS.md CLAUDE.md
ln -sf AGENTS.md .cursorrules
ln -sf AGENTS.md .windsurfrules
ln -sf AGENTS.md .clinerules
ln -sf AGENTS.md .roorules
ln -sf AGENTS.md GEMINI.md
ln -sf AGENTS.md CODESTRAL.md
ln -sf AGENTS.md QWEN.md
ln -sf AGENTS.md CRUSH.md

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

# Use .agents/ for tooling configuration and project base rules
mkdir -p .agents/skills
# .agents/AGENTS.md          — project base rules
# .agents/mcp-settings.json  — project MCP servers
# .agents/skills/**/SKILL.md — project agent skills

Adopt the Standard

For agent tool developers:

1. Search for ~/.agents/AGENTS.md at startup — load as global user rules (loaded first)
2. Load llms.txt at repo root — project-wide PRD context (loaded second)
3. Load .agents/AGENTS.md at repo root — project base rules (loaded third)
4. Load AGENTS.md at repo root — project active / session rules (loaded fourth)
5. Walk from cwd upward collecting AGENTS.md files within the project boundary — folder-scoped rules (optional, loaded last)
6. 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.

Beyond Rules: A Complete Agent Configuration Directory

The ~/.agents/ directory can serve as a single source of truth for all agent configuration — not just behavior rules:

~/.agents/
├── AGENTS.md              ← Behavior rules (global base, loaded first)
├── mcp-settings.json      ← MCP server configs (all agents read from here)
└── skills/                ← Agent Skills (reusable capabilities)
    └── **/SKILL.md        ← Skills discovered by all agents

{project}/.agents/             ← Tooling & project base rules
├── AGENTS.md              ← Project base rules (tech stack, deployment)
├── mcp-settings.json      ← Project-specific MCP servers
└── skills/**/SKILL.md     ← Project-specific agent skills

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
• mcp-settings.json = what external tools are available

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)