AGENTS.md

Define specialized AI agent behaviors for your project

An AGENTS.md file defines specialized AI agent personas — each tuned for a specific workflow like code review, debugging, testing, or documentation. Instead of one generic assistant, your AI coding tool activates the right agent with the right context, tools, and instructions for each task. Caliber generates this file by analyzing your codebase patterns and common workflows.

What AGENTS.md contains

Each agent definition in AGENTS.md includes:

• Agent name — a clear identifier like code-reviewer, tdd-guide, or doc-updater
• Role description — what the agent specializes in and when it should be activated
• Tools allowed — which tools and capabilities the agent can use (file editing, terminal, web search, MCP servers)
• Context scope — which files, directories, or patterns the agent should focus on
• Instructions — task-specific rules, quality standards, and behavioral guidelines

Why use specialized agents

A general-purpose AI assistant tries to do everything at once — it reviews code, writes tests, and drafts docs all with the same context and priorities. Specialized agents are different. A code review agent focuses on bugs, security, and style. A testing agent enforces test-first development and coverage thresholds. A documentation agent knows your doc format and keeps descriptions accurate. Each agent carries only the context it needs, which means better results and fewer distractions.

How Caliber generates AGENTS.md

Instead of defining agents by hand, Caliber analyzes your project and creates agents matched to your actual workflows:

1. 1Scans your codebase — identifies your language, framework, test runner, linter, and project structure
2. 2Detects workflows — finds patterns like test directories, CI configs, doc folders, and review processes
3. 3Generates agent definitions — creates agents for each workflow with appropriate tools, context, and instructions
4. 4Keeps agents current — run caliber refresh to update agent definitions as your project evolves

Quick start

Caliber also generates CLAUDE.md for project-wide context, skills for reusable workflows, and MCP configs from the same scan. See the Claude Code setup guide or the AI setup overview for the complete configuration workflow.

Frequently asked questions

What is an AGENTS.md file?

AGENTS.md is a configuration file that defines specialized AI agent behaviors for your project. Each agent entry specifies a name, role description, allowed tools, context scope, and task-specific instructions. AI coding tools like Claude Code read AGENTS.md to activate the right agent persona for different workflows — code review, debugging, testing, documentation, and more.

How is AGENTS.md different from CLAUDE.md?

CLAUDE.md provides general project context — architecture, conventions, setup commands — that applies to all interactions. AGENTS.md defines multiple specialized agents, each tuned for a specific task. For example, a 'code-reviewer' agent focuses on finding bugs and style issues, while a 'tdd-guide' agent enforces test-first development. Caliber generates both files from the same codebase scan.

Do I need to write AGENTS.md manually?

No. Caliber analyzes your codebase patterns and common workflows to generate AGENTS.md automatically. Run 'npx @rely-ai/caliber bootstrap' in your project root, and Caliber produces agent definitions tailored to your stack — including the tools each agent should use, what context it needs, and how it should behave. You can then customize the generated file as needed.