AGENTS.md is an open standard recognized by almost all modern agents — Copilot, Claude, Cursor, opencode, and others. It works as a repository contract: it defines the rules of the game once, and every agent working on the project respects them without you having to repeat them each session.

The difference between a “naked” repo and one with a well-written AGENTS.md is immediate: in the first case the agent asks, guesses, and gets it wrong; in the second it operates with clear constraints and generates output consistent with your conventions.

A good AGENTS.md is not a manual: it is a set of operational constraints that the agent applies without needing repeated instructions.

The AGENTS.md standard 📜

An effective AGENTS.md follows a structure that can be adapted to any project, but revolves around four areas:

1. Environment: languages, frameworks, versions, main dependencies. The agent must know what it is working with before touching a line of code.
2. Conventions: style, naming, architectural patterns, commit formats. The rules that make code consistent with the rest of the project.
3. Tests: how to run them, what to cover, which framework. The validation phase depends on this information.
4. Boundaries: what NOT to touch, deprecated modules, sensitive areas. The negative constraint is often more important than the positive one.

The ideal length? Under 1000 lines. A file longer than that is a sign you are putting too much in: overly specific rules are better placed in dedicated skills.

The file should be treated as code: versioned, reviewed, iterated. Every time the agent does something you did not want, add or update a rule. Every time a rule is no longer needed, remove it.

Hierarchy and monorepos 🏗️

In a complex project, a single AGENTS.md in the root is not enough. The solution is hierarchy:

• Root AGENTS.md: general project rules — stack, conventions, global boundaries.
• Subdirectory AGENTS.md: module-specific rules. An AGENTS.md in src/api/ can define REST conventions, while one in src/auth/ defines token management rules.
• Cross-references: files in subdirectories can reference the root one with @relative/path/AGENTS.md to inherit general rules without duplicating them.

In a monorepo, hierarchy becomes essential. Each package has its own rules but shares a core of conventions. Hierarchy allows defining common elements once and specializing what is specific.

Context hierarchy is not an architectural luxury: it is the only way to maintain coherence in projects with multiple modules and multiple teams.

The .ignore file 🔒

The .ignore file (or your tool’s equivalent) controls what the agent must not see. This is critical for three reasons:

1. Security: configuration files with secrets, credentials, API keys. The agent must never have access to these.
2. Cleanliness: dependencies (node_modules/, vendor/), build artifacts, logs. This material is pure noise for context.
3. Performance: the more files the agent must process, the slower and more expensive the work cycle becomes.

What to typically exclude:

• Dependency and build folders
• Log and temporary files
• Test snapshots and fixtures (unless relevant)
• Configuration files with secrets
• Large binary assets

The syntax follows .gitignore, so no new format to learn. The conceptual difference: .gitignore protects the repository from the environment; .ignore protects the agent from noise.

Instructions vs skills 🧩

A common point of confusion: what is the difference between AGENTS.md and SKILL.md?

• AGENTS.md contains rules that are always valid — conventions, constraints, structural information. It is the base contract of the project.
• SKILL.md contains specialist procedures activated on-demand — specific workflows, advanced patterns, instructions for particular use cases.

A concrete example: AGENTS.md says “tests run with npm test and all must pass.” A skill says “when doing TDD, follow this specific cycle: write the test, make it fail, implement, refactor.”

The practical rule: if the rule applies to every task, it goes in AGENTS.md. If it applies to a specific type of task, it goes in a skill. Skills can be loaded only when needed, reducing unnecessary context.

AGENTS.md is the constitution; skills are special laws. The first defines principles, the second defines procedures.

When NOT to use the agent ⛔

• Repository without a configured .ignore: the agent sees everything, including what it should not.
• Nonexistent or empty AGENTS.md: the agent operates without constraints, generating potentially incoherent output.
• Too many or contradictory rules: a 5000-line AGENTS.md with conflicting rules is worse than no file at all.

Final checklist ✅

• Does AGENTS.md exist in the root and define environment, conventions, tests, and boundaries?
• Is the length under 1000 lines?
• In a monorepo, do subdirectories have their own files with cross-references to the root?
• Does .ignore exclude dependencies, secrets, logs, and build artifacts?
• Are always-valid rules in AGENTS.md, specialist procedures in dedicated skills?
• Is the file versioned and treated as code?

Further reading 📚

• Blog: The collective mind — how shared context builds collective knowledge.
• Blog: Maintain a rich context — keeping context dense over time.
• Managing context as a resource — the previous level: how to manage context during work.