Writing a Great AGENTS File

TL;DR (Read This First)

1. Keep AGENTS.md/CLAUDE.md short and high-signal: use it as an index and rule sheet, not a full handbook.
2. Put always-needed context in AGENTS.md/CLAUDE.md; use skills and scoped rules for task-specific instructions.
3. Be concrete and project-specific; cut generic advice that the model can infer from code and tooling.
4. Treat the file as living documentation: bootstrap, review, and refine it regularly (/init, /insights, /memory).
5. Skills are best for vertical workflows (migrations, deploys), not for foundational context every session needs.

🔗 Vercel: AGENTS.md outperforms skills in our agent evals

AGENTS vs Skills vs Rules vs Imports

If you only remember one model, use this:

• AGENTS.md / CLAUDE.md (global, always loaded): put durable project contract here. Include stack/version context, non-negotiable constraints, and a compact index to deeper docs.
• Skills (on-demand): use for vertical workflows with clear triggers (migrations, deploys, incident triage), not baseline project knowledge you need every session.
• Rules (scoped instructions): use for file/path-specific behavior. In practice this is often nested memory files or rule files that apply to part of a repo, not global policy.
• @imports (indirection): keep the root file short by importing deeper docs when needed, instead of inlining long procedures.

Best-practice split:

• Put always-relevant guidance in AGENTS.md/CLAUDE.md.
• Put specialized task playbooks in skills.
• Put local conventions close to where they apply (scoped rules/nested memory).
• Put long reference material in docs and pull it in via @imports.

Built-in Tools for Bootstrapping

Claude Code includes a practical loop for maintaining this file over time:

• /init for initial setup
• /insights for suggested changes
• /memory to open and edit memory files quickly

Where the Sources Diverge

The big tension is between brevity and comprehensiveness.

Vercel and Anthropic’s docs both push hard toward minimalism — load only what’s needed, compress aggressively, save tokens. The gist takes the opposite approach: it’s a sprawling ~2,000-word document covering workflow orchestration, task management, communication guidelines, error handling, engineering practices, git hygiene, and templates. It’s essentially a complete operating manual for an AI coding agent.

These aren’t necessarily contradictory — they’re answering different questions. Vercel is asking “how do we teach an agent about framework APIs?” and found that a compressed index beats skills. The gist is answering “how do I define the behavioral contract for an AI agent working in my codebase?” which is a broader concern. But if you took the gist literally and put it all in CLAUDE.md, you’d be burning a lot of context window on instructions that may not be relevant to every task.

The practical reconciliation: keep always-needed behavioral contract in CLAUDE.md (lean), keep scoped rules in repo-local rule/memory files, put reference material in separate files with @imports, and use skills for action-specific workflows.

Skills: dead or complementary? Vercel’s data is strong evidence against skills as a primary knowledge-delivery mechanism. But Vercel also notes skills can still work well for vertical workflows like migrations or deployments. Anthropic’s docs position skills as autonomous or explicitly invoked tools (/skill-name). Net: don’t rely on skills for foundational context, but use them for specialized, triggerable workflows.

Example / Reference Material

• 🔗 Anthropic - Claude Code best practices docs
• 🔗 Anthropic - Claude Code memory docs (CLAUDE.md, imports, and memory hierarchy)
• 🔗 Anthropic - Claude MD management plugin
• 🔗 A viral gist with an opinionated CLAUDE.md example (TypeScript-focused)a

HumanLayer’s guide:

• The system-reminder wrapper: Claude Code tells the model your CLAUDE.md “may or may not be relevant,” so anything that isn’t universally applicable gets actively deprioritized.
• ~150-200 instruction ceiling: Frontier thinking models degrade linearly past this point, and Claude Code’s system prompt already burns ~50 of those slots.
• Don’t use /init: CLAUDE.md is the highest-leverage artifact in the harness — auto-generating it means you haven’t thought carefully about every line.
• Don’t put style guidelines in CLAUDE.md: LLMs learn patterns from your existing code; use linters, formatters, and hooks instead of wasting instruction slots.
• Under 60 lines: HumanLayer’s own root CLAUDE.md is under 60 lines — proof that aggressive brevity is practical even in production.
• Progressive disclosure over inlining: Tell Claude how to find information (pointers to docs files), not the information itself.