agents-md-guide

Original：🇺🇸 English

Translated

Guide for creating, refactoring, and optimizing AGENTS.md files (and CLAUDE.md files) for AI coding agent repositories. Use when the user wants to create a new AGENTS.md, refactor an existing one, audit their AGENTS.md for bloat or staleness, apply progressive disclosure principles, set up AGENTS.md in a monorepo, or improve how their AI coding agents behave via repository configuration files. Also applies to CLAUDE.md files (Claude Code's equivalent).

1installs

Sourcehexoplon/skills

Added on2026-02-08

NPX Install

npx skill4agent add hexoplon/skills agents-md-guide

SKILL.md Content

View Translation Comparison →

AGENTS.md Guide

AGENTS.md is a markdown file checked into Git that customizes how AI coding agents behave in a repository. It sits at the top of the conversation history, below the system prompt. Claude Code uses CLAUDE.md instead — symlink between them:

bash

ln -s AGENTS.md CLAUDE.md

Core Principle: Minimize Token Cost

Every token in AGENTS.md loads on every single request, regardless of relevance. Frontier LLMs can follow ~150-200 instructions consistently. Keep the file as small as possible.

What Belongs in Root AGENTS.md

Only include what is relevant to every single task in the repo:

One-sentence project description — anchors the agent's understanding of scope
Package manager — only if non-standard (e.g., pnpm, yarn)
Build/typecheck commands — only if non-standard

Everything else goes elsewhere via progressive disclosure.

Example Minimal AGENTS.md

markdown

This is a React component library for accessible data visualization.
This project uses pnpm workspaces.

Progressive Disclosure

Point the agent to other resources instead of inlining everything. Agents navigate documentation hierarchies efficiently.

Move domain-specific rules to separate files:

markdown

For TypeScript conventions, see docs/TYPESCRIPT.md

Nest references (keep one level deep from root):

docs/
├── TYPESCRIPT.md → references TESTING.md
├── TESTING.md → references specific test runners
└── BUILD.md → references esbuild configuration

External docs (Prisma, Next.js, etc.) can also be linked.

Monorepo Strategy

Place AGENTS.md files in subdirectories — they merge with root level.

Level	Content
Root	Monorepo purpose, navigation, shared tools
Package	Package purpose, specific tech stack, local conventions

Root example:

markdown

This is a monorepo containing web services and CLI tools.
Use pnpm workspaces to manage dependencies.
See each package's AGENTS.md for specific guidelines.

Package example (

packages/api/AGENTS.md

):

markdown

This package is a Node.js GraphQL API using Prisma.
Follow docs/API_CONVENTIONS.md for API design patterns.

Anti-Patterns to Avoid

Documenting file paths — paths change constantly and poison context when stale; describe capabilities and project shape instead
Auto-generated AGENTS.md — prioritizes comprehensiveness over restraint; never use initialization scripts to generate these
Accumulating rules reactively — adding a rule every time the agent misbehaves creates contradictions and a "ball of mud"
Redundant instructions — don't tell the agent things it already knows (e.g., "write clean code")
Vague instructions — not actionable; wastes tokens
Stale documentation — especially dangerous for agents that read docs on every request; domain concepts are safer to document than file paths

Refactoring a Bloated AGENTS.md

When the user wants to refactor an existing AGENTS.md, follow the process in references/refactoring.md.

agents-md-guide

NPX Install

Tags

SKILL.md Content

AGENTS.md Guide

Core Principle: Minimize Token Cost

What Belongs in Root AGENTS.md

Example Minimal AGENTS.md

Progressive Disclosure

Monorepo Strategy

Anti-Patterns to Avoid

Refactoring a Bloated AGENTS.md