On this page
Best AGENTS.md Templates
This guide compares four proven AGENTS.md template patterns for 2026, covering routing tables, memory persistence, identity decomposition, and domain-specific guardrails. We break down each template's ideal use case, key tradeoffs, and which pattern offers the best balance of portability and low overhead for most engineering teams.
Best AGENTS.md Templates: What Actually Works in 2026
OpenAI’s own Codex repository ships 88 AGENTS.md files across its directory tree. That isn’t minimalism—it’s an admission that one-size-fits-all context fails at scale. If you’re hunting for the best AGENTS.md templates, the real question isn’t which template looks cleanest in a README screenshot. It’s whether the template matches your team’s actual fragmentation problem: single agent or many, single repo or monorepo, portable conventions or deep institutional memory.
The Template Landscape: Four Patterns That Actually Exist
Drop-in templates cluster into four recognizable shapes, each solving a different layer of the context problem.
The routing-table template treats AGENTS.md as an orchestration entry point. The itshig/AGENTS-template pattern puts specialist files in .agents/rules/, .agents/personas/, and .agents/workflows/, with AGENTS.md itself containing only when to load each. This keeps the root file small while preserving discoverability. The discipline required: split files by kind (rule vs. persona vs. workflow), never mix them, and cap each at ~200 lines.
The memory-persistence template adds agent_memory/ directories for context that survives across sessions. TateZhouSiu/agents-md-kit provides context.md, progress.md, and bugs.md templates, with an explicit archive/ directory for rotation. The value proposition here is session continuity—agents that can read where things left off, what failed before, and what constraints have already been established.
The identity-decomposition template splits what an agent does from how it thinks. ExpertVagabond/agent-template uses AGENTS.md for operational instructions, SOUL.md for persona and values, and HEARTBEAT.md for self-maintenance protocols, plus a MEMORY/ directory with decisions.md, lessons.md, and blockers.md. This is the most philosophically ambitious pattern: it encodes not just conventions but organizational memory in a forkable structure.
The domain-specialist template bakes in vertical expertise. suhail39ahmed/agents-md-production-ai provides DevSecOps, Terraform, and Pipeline agent templates for Azure, with hard constraints like “NEVER disable security scanning in pipelines” and “ALWAYS use managed identities over service principals.”
Here’s how they compare on the dimensions that matter for adoption:
| Template | Structure | Best For | Key Tradeoff |
|---|---|---|---|
| itshig/AGENTS-template | .agents/ subdirectories with routing tables | Teams using 3+ tools who need consistent behavior | Requires discipline to maintain splits; easy to let files bloat |
| TateZhouSiu/agents-md-kit | agent_memory/ for session persistence | Long debugging sessions, complex tasks with state | Adds file count; agents must be trained to read memory files |
| ExpertVagabond/agent-template | AGENTS.md + SOUL.md + HEARTBEAT.md + MEMORY/ | Multi-agent workflows where identity matters | Most complex; overkill for single-agent, single-repo setups |
| suhail39ahmed/agents-md-production-ai | Domain-specific rule files (DevSecOps, Terraform) | Teams in regulated environments with strict guardrails | Narrow; Azure-centric, not easily portable to AWS/GCP |
The pattern I’ve observed—the Context Stack—matters here. AGENTS.md functions best as a declarative identity layer. The templates that win are the ones that resist the temptation to dump entire documentation into the root file and instead point to specialized context that loads only when needed.
When Templates Help and When They Backfire
Not every team benefits from a template. Vercel’s evaluation found that a compressed 8KB docs index embedded directly in AGENTS.md achieved a 100% pass rate, while Skills maxed out at 79% because the Skill was never invoked in 56% of cases. That’s the progressive disclosure problem: context that doesn’t load automatically can fail to load at all.
But the counter-evidence is equally sharp. ETH Zurich researchers’ “Evaluating AGENTS.md” (Feb 2026) reports that context files tend to reduce task success rates and raise inference cost by over 20% on their benchmark. The variable isn’t whether you use a template—it’s whether the template is any good.
Augment Code’s framing captures the reconciliation: “A good AGENTS.md is a model upgrade. A bad one is worse than no docs at all.”
The failure mode I watch for: templates that ship with too much generic advice. A 2024 Princeton study found poorly structured agent configs increase task failure rates by 31%, and GitHub Octoverse 2024 reported 54% of developers use AI-assisted coding while only 23% feel their agent configuration is “mostly reliable.” Templates that don’t account for this— that present themselves as finished products rather than starting points—compound the problem.
Generators vs. Hand-Crafted: The Automation Tension
Several tools now generate AGENTS.md automatically, and the quality varies dramatically.
AgentUp CLI generates AGENTS.md and provider-specific scaffolding for Claude, Codex, Cursor, Gemini, and Antigravity with auto-detected project context and reusable role workflows (plan, review, test, code). It offers two modes: template (fully offline, built-in templates) and ai (Gemini-based review to improve generated context). The auto-detection covers language, framework, database, and package manager—useful for greenfield projects, less reliable for legacy codebases with idiosyncratic structures.
Google’s agents-cli, released April 21, 2026, takes a different approach. It injects seven structured Markdown files into a coding assistant’s skill directory, formatted according to the SKILL.md open specification now supported across 32 coding tools. These aren’t generic templates—they’re machine-readable knowledge bundles for Google’s entire agent development stack (ADK, Cloud Run, GKE, Cloud Trace, Terraform, Gemini Enterprise). The skill loads only when relevant, keeping startup context minimal.
The generator approach solves the blank-page problem. It introduces a new one: generated context that looks correct but encodes assumptions that don’t match your team’s actual practices. I’ve found generators most useful as first drafts, with the real work being the editing pass that removes generic advice and adds the specific constraints that matter for your codebase.
The Emerging Complementary Formats
AGENTS.md isn’t staying still as a standard. Two adjacent formats are worth tracking because they may reshape what “AGENTS.md template” even means.
QUALITY.md is a complementary open format for project quality standards that works alongside AGENTS.md. It consists of a QUALITY.md file, a /quality agent skill, and a qualitymd CLI. Where AGENTS.md typically covers how to build and test, QUALITY.md encodes why certain tradeoffs matter—“a payments service should favor auditability over clever abstraction.” The format is vendor-agnostic by design, and the workflow includes an explicit improvement loop: run /quality evaluate, act on findings, then run /quality improve to refine the rubric.
This matters for template design because it suggests AGENTS.md is being hollowed out into a routing table pointing to specialized files. The template that includes only AGENTS.md may soon look as incomplete as a project with only a README and no CONTRIBUTING.md.
The second pressure comes from proprietary context engines. Cloudflare uses AGENTS.md across roughly 3,900 repositories with 3,683 internal AI coding tool users in a 30-day window (60% of company, 93% of R&D), but its AI Code Reviewer handled 5.47 million requests and 24.77 billion tokens—processing that AGENTS.md alone cannot replicate. Augment Code and similar platforms are building deep, platform-embedded reasoning that indexes history and cross-repo dependencies. AGENTS.md templates don’t compete with this; they coexist as the portable baseline while proprietary layers add depth.
Choosing a Template: A Decision Framework
The right template depends on where your team sits on three axes:
Tool heterogeneity. If you run Cursor alongside Codex alongside Claude Code, you need the routing-table or identity-decomposition patterns. Claude Code does not natively read AGENTS.md as of April 2026; the standard workaround is a symlink or a CLAUDE.md file that imports AGENTS.md. The more tools you use, the more you pay for not having a single source of truth.
Task delegation depth. Developers use AI in roughly 60% of their work but report being able to “fully delegate” only 0-20% of tasks, per Anthropic’s 2026 Agentic Coding Trends Report. If you’re in that 0-20% range with mostly assisted coding, a minimal AGENTS.md with build commands and style rules suffices. If you’re pushing toward higher delegation with long-running agents, the memory-persistence or identity-decomposition templates become worth the complexity.
Compliance environment. The domain-specialist templates (DevSecOps, Terraform) only make sense when you have hard constraints that must not be violated. They’re not general-purpose starting points.
Cost enters the picture too, though not in the obvious way. The Dirr AI Agent Pricing Index (verified May 30, 2026) analyzed 114 tools, finding a median entry plan of $29/mo, 53% offering free tiers, 17% quote-only, and 7 distinct billing models with 47% using hybrids. But the real cost of templates is inference tokens, not subscription fees. Bloated AGENTS.md files raise inference costs by over 20% on benchmark. The template that includes everything is the template that costs you at scale.
For teams already exploring OpenAI’s ecosystem, OpenAI AgentKit is free to build with usage-based pricing (~$0.20/1M input tokens for GPT-5.4-nano, $2.50/1M input and $15/1M output for GPT-5.4, plus tool fees like Web Search at $10/1K calls). The pricing model is pure usage—no platform subscription—which means template efficiency directly translates to cost savings.
My Recommendation
Start with the itshig/AGENTS-template routing-table pattern for any team using two or more AI coding tools. It’s the most forgiving of the lightweight options and enforces the discipline of splitting context by kind. Add TateZhouSiu/agents-md-kit memory files only after you’ve hit the specific pain point of lost session state—don’t preemptively adopt the complexity.
For teams already committed to Claude Code as primary, the symlink approach to AGENTS.md is fine, but consider whether you’re building portability debt. The AI Prime Directive Framework—one master file, thin pointer files for non-compliant tools, and a build log—addresses this directly, though it’s more process than template.
For regulated environments, fork suhail39ahmed/agents-md-production-ai and strip it to your actual constraints, not Azure’s. The hard constraints pattern is valuable; the specific cloud provider less so.
The template that will serve you best in 2027 is likely one that doesn’t exist yet—one that treats AGENTS.md as a routing layer to QUALITY.md, to agent_memory/, and to tool-specific skills, while keeping the root file small enough that ETH Zurich’s cost penalty never applies. The standards are converging on a three-layer architecture: AGENTS.md for identity, MCP for connectivity, A2A for coordination. The knowledge layer is where the fragmentation is happening, and templates that don’t account for this will age poorly.
What specific constraint in your current codebase would you encode first if you were writing AGENTS.md from scratch today—the build command that always breaks, the file no one remembers not to touch, or the security rule that once got violated in production?