What AGENTS.md Gives Coding Agents That README Files Do Not

Anil Muppalla — Sun, 05 Jul 2026 21:29:00 +0000

Here's the failure mode I keep running into.

A team gives a coding agent a repo, a task, and maybe a README. The agent can find files and write code, but it still has to guess the operating rules.

It guesses the package manager.

It guesses which checks matter.

It guesses whether generated files are safe to edit.

It guesses what "done" means.

A README is usually for humans: what the project is, how to run it, and where the important docs live. A coding agent needs different context. Setup rules. Test commands. Boundaries. Completion criteria.

That's the gap AGENTS.md fills.

The official AGENTS.md guidance describes it as a predictable place for coding-agent instructions: setup commands, test commands, code style, security considerations, and nested instructions for large monorepos.

I find the split useful in a more boring way. The README answers, "What is this project?" AGENTS.md answers, "What should an agent know before touching it?"

That second question is where the work usually gets fragile.

Where Goose Fits

Goose makes this less theoretical because it isn't just a chat box. It's an open source local AI agent with a desktop app, CLI, API, MCP extensions, and skills.

Without AGENTS.md, I find myself writing prompts like this:

Update the docs, but don't touch generated files, use pnpm, run the lint and test commands, keep the PR small, and tell me what you couldn't verify.

With AGENTS.md, the prompt can get shorter:

Update the quickstart docs for the new config flag.

Goose can run the task in the repo. The repo can carry the standing instructions.

I noticed this on a small docs/config update where generated files sat near source files. Without repo instructions, the prompt had to carry the package manager, generated-file boundary, checks, and the "tell me what you could not verify" rule.

Once those rules lived in AGENTS.md, the prompt became just the task.

Not magic. Just fewer chances to forget the boring parts.

Where Skills Fit

I would add one more layer once AGENTS.md starts doing real work: skills.

The file should not become the place where every repeated workflow gets pasted. That's how it turns into a junk drawer.

A cleaner split:

AGENTS.md says the standing rules.
Skills describe repeatable task routines.
MCP and extensions give the agent access to tools and data.

That maps cleanly to Goose too. Goose has a Skills Marketplace for reusable instruction sets with optional supporting files.

For a backend service, AGENTS.md might route migrations, API changes, and releases to separate skills.

The AGENTS.md file stays short, and the task routine can be as detailed as it needs to be somewhere else.

The distinction is simple: if the rule should apply to almost every task in the repo, put it in AGENTS.md. If it's a repeatable routine for one kind of work, make it a skill and route to it from AGENTS.md.

A Small Workflow Worth Trying

Try this on one low-risk repo where you already use an agent.

Add an AGENTS.md file with five sections:

Setup: the blessed install and run commands.
Checks: the smallest reliable test, lint, or typecheck commands.
Boundaries: files, data, or actions the agent should not touch.
Done criteria: what evidence the agent should provide before it stops.
Skills: task-specific routines the agent should use instead of guessing.

Then try the same task twice:

Task: Add an example for a new config flag.

First, do it with no AGENTS.md and watch what you have to explain.

Then add the file and ask again.

The useful test:

Did the agent run the right checks?
Did it avoid generated files?
Did your prompt get shorter?

If the answer is no, the file is probably too vague, too long, or full of instructions the agent can't act on.

A Good First `AGENTS.md`

Start here:

# AGENTS.md

## Project Map

- `src/` contains application code.
- `tests/` contains tests.
- `docs/` contains user-facing docs.
- `generated/` is produced by tooling; do not edit it manually.

## Commands

- Install: `pnpm install`
- Test: `pnpm test`
- Lint: `pnpm lint`
- Typecheck: `pnpm typecheck`

## Working Rules

- Keep changes scoped to the user's request.
- Prefer existing helpers before adding abstractions.
- Do not deploy, publish, migrate, or delete data without explicit approval.
- Do not include secrets, private data, or local-only paths in committed files.

## Completion

- Run the relevant checks or explain why they were not run.
- Summarize changed behavior.
- List remaining risk or follow-up.

## Skills

- For database migrations, use the migration review skill.
- For API changes, use the contract-checking skill.
- Before a release, use the release-notes skill.

That's enough to be useful. It's also short enough that someone might maintain it.

Avoid architecture essays, aspirational values, every command in the repo, and private context you wouldn't want in a prompt transcript. If the instruction doesn't change the agent's behavior, cut it.

The Takeaway

AGENTS.md is not a magic safety layer.

It's a simple place to put the instructions you were already repeating: setup, checks, boundaries, and what done means.

For me, the practical bar is this: can the agent do a small task with less prompting and still show the checks it ran?

If yes, the repo got less ambiguous.

If no, the file needs more work.