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:

1. Setup: the blessed install and run commands.

2. Checks: the smallest reliable test, lint, or typecheck commands.

3. Boundaries: files, data, or actions the agent should not touch.

4. Done criteria: what evidence the agent should provide before it stops.

5. 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.

You ask it to summarize something, draft a note, write some code, plan a trip, or reason through a problem, and it gives you something useful in seconds.

That first spike is real.

But it is also partly novelty.

The Slump

After the first few wins, many people hit a lull.

The agent forgets what matters. It does not know your standards. It misses the backstory. You have to explain the same things again: who you are, what you care about, what “good” looks like, what projects are active, what tone you prefer, and which constraints are non-negotiable.

That phase can feel disappointing.

The agent is still useful, but the interaction cost is higher than expected. You start to realize that intelligence without context is not the same thing as leverage.

Where The Curve Changes

The curve changes when durable context starts to accumulate.

When an agent has access to your previous work, it can infer more than facts. It starts to pick up the way you write, the way you structure ideas, the kinds of arguments you find persuasive, and the level of precision you expect.

Your past work also reveals your priorities.

It shows what you care about deeply, what you treat as secondary, where you are willing to make tradeoffs, and where you are not.

That changes the next prompt.

The agent is no longer responding only to the words you typed in the moment. It is also drawing from the pattern of your prior decisions, drafts, edits, preferences, and examples.

It can make a better first guess at what you want.

It can skip explanations you no longer need.

It can ask sharper questions.

It can produce work that is closer to your bar on the first pass.

Tools Supercharge The Agent

Durable context helps the agent understand you.

Tool access helps it operate in your world.

If the agent can see your Slack conversations, documents, calendar, codebase, tickets, notes, or Drive folders, it no longer depends entirely on what you remembered to paste into the chat window.

It can look at the actual state of your work.

It can connect a conversation from last week to a document you wrote yesterday. It can turn scattered context into a coherent recommendation, draft, plan, or next action.

That is where the ROI starts compounding.

The unlock is not just “better models.” It is capable models plus durable context plus access to the tools where work actually happens.

Context helps the agent understand your operating system.

Tools let it act inside that operating system.

The Takeaway

If your experience with AI agents has followed this pattern, I think that is normal:

1. The wow phase: “This is incredible.”

2. The slump: “Why do I have to keep explaining everything?”

3. The compounding phase: “Now it understands enough to actually help me move faster.”

The mistake is quitting in the slump.

The better move is to treat context as an investment. Save examples. Keep project notes. Connect the tools that matter. Let the agent see your previous work and the current state of your world.

The ROI curve is not linear.

It starts with novelty, dips into friction, and then rises as context and tool access compound.

Subscribe now