AGENTS.md vs README.md vs Skills: What Goes Where

README.md is for people: what the project is, why it exists, how to install and use it, and where to get help. AGENTS.md is for coding agents: the exact commands, the conventions that differ from the defaults, and what never to touch, read at the start of every session. Skills hold procedures an agent needs only sometimes, a release checklist or a migration routine, loaded when the task calls for one. Tool-specific files such as CLAUDE.md carry only what one tool needs. Long-lived knowledge goes in docs, and the work itself, what to do next and what was done, goes on a task board. Each has a different reader and a different loading rule, and most confusion comes from putting content in the file with the wrong one.

Why the split exists

The AGENTS.md site↗ (opens in a new tab) calls the format a README for agents, and gives the reason for keeping it separate: agents get a clear, predictable place for instructions, and READMEs stay concise and focused on human contributors. A new colleague needs to know what the project does and how to run it; an agent needs pnpm test --filter api exactly, and to know that the generated client must never be edited by hand. Mixing the two makes the README noisy for people and the instructions vague for agents.

Skills exist for a different reason: cost. Anything in AGENTS.md or CLAUDE.md is loaded into every session, whether the task needs it or not. Anthropic’s skills documentation↗ (opens in a new tab) puts the contrast plainly: unlike CLAUDE.md content, a skill’s body loads only when it is used, so long reference material costs almost nothing until you need it. At startup the agent sees only each skill’s name and description.

This content goes in this file

• What the project is, why it matters, screenshots, install and usage for users → README.md.
• How to get help, who maintains it, how to contribute → README.md, or CONTRIBUTING.md beside it.
• Exact setup, build, test and lint commands, as agents must run them → AGENTS.md.
• Conventions that differ from the language defaults, folder layout, what never to edit → AGENTS.md.
• How work is tracked and where to find the next task → one short section of AGENTS.md pointing at the board.
• A multi-step procedure used now and then: releasing, adding a migration, rotating a key → a skill, SKILL.md in its own folder.
• Long reference an agent consults for one kind of task: an API style guide, a schema description → a skill’s references/ folder, or a doc the skill points to.
• Rules for one tool only, or for files matching a path → CLAUDE.md, .claude/rules/, .github/copilot-instructions.md or .cursor/rules/, kept short.
• Architecture, design decisions, specs, runbooks → docs/, read by people and linked from AGENTS.md when an agent needs them.
• What to do next, who is doing it, what was tested, what was decided → the task board.
• Your personal preferences in every project → your user-level file, such as ~/.claude/CLAUDE.md or ~/.junie/AGENTS.md, never the repository.

Which file each tool reads, and which wins when several apply, is the subject of AI context files compared; this page is only about what goes where.

README.md: for people first

GitHub’s page about READMEs↗ (opens in a new tab) lists what one usually covers: what the project does, why it is useful, how users get started, where they get help, and who maintains and contributes to it. That is a good test. If a line helps a person decide whether to use the project or get it running for the first time, it belongs in the README. Agents may read the README too, and some teams tell them to, so keep it accurate; but do not write it for them.

AGENTS.md: the rules for every session

AGENTS.md holds what an agent must know before touching anything, in every session: commands, conventions, boundaries. It is plain Markdown with no required fields, and a nested AGENTS.md in a package adds that package’s rules. Keep it to facts that are always true. Anthropic’s memory documentation↗ (opens in a new tab) gives the rule for its own file, and it applies here too: if an entry is a multi-step procedure or only matters for one part of the codebase, move it to a skill or a path-scoped rule. Annotated files for three kinds of project are in AGENTS.md examples.

Skills: procedures on demand

A skill is a folder with a SKILL.md file: YAML frontmatter with a name and a description, then the instructions, and optionally scripts/, references/ and assets/. The Agent Skills specification↗ (opens in a new tab) describes the loading in three steps: name and description at startup, the full SKILL.md when the skill is activated, and other files only when needed. It recommends keeping SKILL.md under 500 lines and moving detail into separate files.

The description does the work. It decides whether the agent ever loads the skill, so it should say what the skill does and when to use it, with the words a request would contain. A skill named release with the description “Release helper” will sit unused. Where each tool looks for skills is in agent skills; writing one for Claude is in how to create a Claude skill.

CLAUDE.md, CONTEXT.md and other names

Tool-specific files should add to AGENTS.md, not repeat it. A CLAUDE.md that starts with @AGENTS.md and then lists only Claude-specific lines keeps one source of truth; whether Claude Code reads AGENTS.md on its own is answered in does Claude Code read AGENTS.md?. Junie has its own twist: a .junie/AGENTS.md, if present, replaces the root file for Junie, as described in JetBrains Junie vs Claude Code.

There is no CONTEXT.md standard. A file with that name is read only by a tool you have configured to read it. Goose, for example, reads AGENTS.md and .goosehints by default, and reads other names only if you list them in its CONTEXT_FILE_NAMES variable, as covered in the Goose AI agent. If you are choosing a name for agent instructions, choose AGENTS.md; it is the one most tools look for without being told.

Common mistakes

• Copying the README into AGENTS.md. The agent pays for the marketing paragraph in every session, and the two copies drift apart.
• Procedures in AGENTS.md. A forty-line release checklist loads into every bug fix. Make it a skill and leave one line saying it exists.
• A task list in AGENTS.md. A “current work” section is wrong within a week, and an agent will treat stale work as instructions.
• Hand-synced copies: the same rules pasted into CLAUDE.md, AGENTS.md and the Copilot file. Import or point instead.
• Vague skill descriptions. The agent never loads the skill, and you conclude skills do not work.
• Secrets or customer data in any of these files. They are committed, and every agent sends them to a model.
• Decisions buried in chat. Why the team chose Postgres over DynamoDB belongs in docs/ or with the work, where the next person and the next agent can find it.

A worked layout

README.md                          # people: what, why, install, usage, help
CONTRIBUTING.md                    # people: how to propose a change
AGENTS.md                          # agents: commands, conventions, never-touch, where the work lives
apps/api/AGENTS.md                 # agents: extra rules inside apps/api
CLAUDE.md                          # @AGENTS.md, then Claude-only lines
.agents/skills/release/SKILL.md    # procedure: cut a release, loaded on demand
.agents/skills/db-migration/
  SKILL.md                         # procedure: add a migration
  references/conventions.md        # long reference, read only when needed
docs/architecture.md               # people and agents: how the system fits together
docs/decisions/0007-postgres.md    # why a choice was made

Not every tool looks in .agents/skills/; Claude Code looks in .claude/skills/, for example, so check agent skills for where to place or link each folder. The root AGENTS.md then needs only a few lines about the rest: “Release and migration procedures are skills; architecture is in docs/architecture.md; tasks are on the board.”

The work goes on the board

None of these files is a good home for the work itself. On fenbs, each task has a note saying what is wrong and where, a plan for how it will be done, and a test status with notes, in the lanes To Do, Next Up, In Progress and Completed, and every change is signed by the person or AI assistant who made it. The board also keeps AI context, short notes for every connected assistant that it reads with fenbs_get_context, and decisions, so a lesson one agent learned or a choice the owner made reaches the next agent whatever tool it runs in. The line in AGENTS.md that connects them is short.

## Work tracking
- Tasks live on the fenbs board, project "acme". Call fenbs_get_context first.
- Move a task to In Progress when you start and Completed when you finish,
  with the commit and how it was tested.