Stop Overloading Your AGENTS.md

Call it AGENTS.md, copilot-instructions, CLAUDE.md, GEMINI.md, or whatever your coding harness happens to name it. Whatever the label, it's the same thing: the global instructions that ride along with your agent. I want to talk about it — but mostly I want to talk about how not to use it, and why using it too much is actually dangerous.

What everyone uses it for

Let's start with the common practice, because that's what makes the case easier to explain.

If you own a code repository, your instructions file probably holds naming conventions, testing best practices, how to run the build, how to install dependencies, how to get started, a sketch of the system architecture, maybe some pointers to external docs. Maybe you've got an internal knowledge base, so the file acts as an index — telling any agent when and what to load.

If you own a docs, knowledge, or PM repository, it looks similar: which agents to use, which skills to load for which task, where the document templates live, an index into your knowledge.

This is all common, and it's all squarely within what these files were designed to do. And I'd still suggest you don't use them for most of it. Here's why.

Reason one: every token travels

Your instructions file ships with every single agent request. So you should think long and hard about every token in it — for two reasons.

First, it's pure weight. Every token enlarges the context and costs you on every call.

Second, and more important, every token is an instruction competing for the model's attention. Models — even the good ones — can only hold so many instructions before they start to buckle. Pile on too many and you confuse the model, you push earlier context out, and you lower the quality of whatever the agent produces.

So the bar for putting anything in that file should be high. And even when something clears the bar, lean on gradual exposure: leave a pointer to where the thing lives, and let the agent go fetch it if it decides it needs it. Keep the file as thin as you can.

That's the basic, technical reason. There's a bigger one.

Reason two: you're forcing everyone to work like you

When you write these instructions, you're forcing every consumer of your repository to work exactly the way you — the author — imagined. Not everyone wants that.

Say you tuned your instructions around your favorite harness and the models it's optimized for. Along comes a teammate who prefers a different tool, running different models tuned differently. Your carefully crafted rules aren't helping them anymore — they're in the way.

Or say you encoded your flow: naming, best practices, architecture, the works. Then someone shows up running their own loop — custom agents, custom orchestration, modern loop-engineering. Your file insists on running tests every cycle. But they test in a separate agentic loop, not inside every coding cycle. What made perfect sense for your flow now wreaks havoc on theirs.

Another example is someone using your repository for a purpose you never intended. The classic case is deriving business understanding from a codebase. At the end of the day, the codebase is the real source of truth for what a product does. Documentation drifts. Specs drift. Customer-facing content drifts. The code is what actually ships.

So a PM points an agent at your repo — not because they care about your architecture or your implementation details, but because they want to derive real product value straight from the source of truth. Once upon a time this meant finding an engineer and burning days of reading and dissecting. Now the PM just sends an agent: go read this.

Except somewhere in your global instructions is a rule that says always make sure the tests run — plus who knows what else you wrote for coders. The PM doesn't want to code. They don't care if it compiles. They just want to read. And even if your team agreed on those instructions together, and even if you were right for coders, you still never had the PM in the room.

You can extend this indefinitely. Anything you try to force, someone else will eventually want to do differently. So use these files carefully, and don't be too opinionated.

So what do you do instead?

The objections are fair. You do want to explain how to run the build. You do want a global pointer to your knowledge base. You do want to say something about quality. There are a few better ways to get there.

Use the file as an index. Instead of inlining your coding best practices, add a line: best practices live in this document — load it if you're doing a coding task. You don't force it into every session. You save tokens and you save confusion. The tradeoff is that the agent won't always listen.

Package things as skills. This doesn't make the agent any more obedient, but it buys you real structure. One of the beautiful things about a skill is that it's a harness-native way to gradually expose context. A skill doesn't have to load a capability — it can load knowledge, best practices, architecture. Write a good description — the description is effectively the search terms the agent uses to find it — and the skill only loads when it's actually relevant.

Distribute skills as plugins. Once your knowledge and practices are skills, you can lift them out. What if your coding standards apply across many teams? What if your knowledge base is shared across repositories? Put the skills in a dedicated repository and install them through the plugin mechanisms every standard harness ships with today. Now you've solved distribution and gradual exposure. What you haven't solved is forcing the agent to load the right thing at the right moment. In a reasonably clean environment, without a pile of conflicting skills and instructions, a good description and good instructions are often enough. There is still no guarantee the skill actually gets loaded. The description makes it discoverable, not mandatory — the agent decides, and sometimes it decides wrong.

You can still keep a light global note — when you run, be aware there may be a skill for knowledge or architecture; use it if it helps — hinting at what exists without forcing it to load. Not too opinionated. That helps a little.

When you truly must force it, reach for custom agents. If something genuinely has to happen, that's what a custom agent is for. A custom coding agent can hard-code the rules — the practices, the knowledge — or, if you want it to stay generic, it can explicitly say which skills to load and when. In coding mode it loads what coding needs. In debugging mode it loads what debugging needs. The forcing lives inside the agent, where someone opted into it, instead of in a global file everyone inherits by default.

What you gain

Here's what you get out of it. A leaner, lighter instructions file that keeps your repository clean and keeps your agents from getting confused. A more flexible repository, where the PM reading code isn't fighting your test rules and the teammate with a custom loop isn't fighting your flow. Nobody gets bitten by something you decided was important — that may not be important to them at all, and might actively get in their way.

Use these files. Just use them carefully.