From an AGENTS.md Guide to AgentsMD-GEN

I recently read Matt Pocock's "A Complete Guide To AGENTS.md." It's about a small thing that everyone who programs with AI can't avoid: writing a rules file for the Agent. This article is my reading recap—first what the original said, then what I learned from it, and finally a clear account of how these ideas step by step became the AgentsMD-GEN Skill. If you also have an AGENTS.md that keeps getting longer, I hope this path from reading to hands-on work is useful to you.

AgentsMD-GEN GitHub repository:https://github.com/Niall-Young/AgentsMD-GEN

A file that grows with every addition

This is usually how it starts. The AI programming Agent makes a mistake—for example, using the wrong package manager, or running a command that doesn't exist in the project at all. Our first reaction is natural: add a rule to AGENTS.md so it won't make that mistake again. Two days later it makes another mistake, and we add another rule. Every time it's well-intentioned, and every time we add just one or two lines.

In "A Complete Guide To AGENTS.md," Matt Pocock gives this file a definition: it's a Markdown file committed to Git, used to customize the behavior of AI programming Agents within a repository—a configuration layer between base instructions and the specific codebase. This positioning itself is not a problem at all; what goes wrong is how we use it.

In the author's view, rules added one by one will eventually accumulate into a mutually conflicting, hard-to-maintain "mud ball"; and the more hidden cost is that a large number of instructions unrelated to the current task consume the model's context and attention on every request. Disk space is cheap, but rules that must be carried along on every request have a cost.

This is an engineering judgment, not a rigorously proven law, but it explains a common confusion: as the file grows thicker, why might the Agent become less and less obedient.So the real question is not "should we write rules," but "how should this file be governed." The original article provides a whole set of diagnoses and prescriptions; below, I first explain what it says.

Configuration Layers and Progressive Disclosure

One of the most explanatory concepts in the original article is the instruction budget. It cites HumanLayer's claim: frontier reasoning models can follow roughly 150 to 200 instructions with reasonable consistency, and as instructions continue to increase, adherence quality declines. It should be noted that HumanLayer itself states clearly: this topic has not yet been subjected to extremely rigorous research, and this number is a summary of engineering experience and related research, not a guarantee from any model vendor, and certainly not a precise upper limit. But it provides a useful mental model—AGENTS.md is not free,every rule spends from the same budget. In other words, the bottleneck of the budget is not on disk, but in the number of instructions the model can reliably absorb per request.

From this perspective, the original article offers several very specific suggestions for subtraction. A minimal root AGENTS.md mainly contains: a one-sentence project description, a note about a non-npm package manager, and non-standard build or type-check commands. All other details should be placed in other files as needed. This is the author's suggestion rather than a mandatory standard, but the direction is clear: the root file should retain only what is needed for almost every task.

Where should details go? The mechanism given in the original article is progressive disclosure: keep the always-loaded entry point lean, providing only topic clues and pointers; when the current task requires it, the Agent then loads more detailed specifications, runbooks, or Skills. However, the original article also reminds us that this is not a free lunch—discovering, selecting, and reading those detail files still consumes tool calls and context. On-demand loading saves resident cost but spends retrieval cost.

For monorepos, the original article recommends using both root-level and package-level files: the root level stores the purpose of the entire repository and shared tooling, while the package level stores that package's purpose, tech stack, and local conventions. As for whether multi-level files are merged and how, that depends on each host's implementation,the article provides structural suggestions. This is actually the same idea as progressive disclosure applied at different scales: each layer answers only the questions that belong to that layer.

There is one more point worth remembering: the original article has a clear inclination—it does not advocate using an initialization script to automatically generate AGENTS.md. This inclination seems to directly collide with what I am going to do later; I will leave this foreshadowing for Chapter 4.

Four Things I Learned

Operational suggestions can be copied directly, but what truly remains are a few transferable insights.Operational suggestions will become outdated as tools evolve; insights will not. After reading the whole article, what settled with me were four insights, and they later became design decisions in the Skill one by one.

First, AGENTS.md is configuration, not an encyclopedia. The value of the configuration layer lies in restraint—it should only contain instructions that can change Agent behavior, rather than stuffing project background, directory structure, and historical decisions all into it. Writing everything into it is equivalent to configuring nothing. Later, the design goal in the Skill of "not writing the root file as a project encyclopedia" directly originated from this.

Second, what is truly scarce is context and attention, not disk space. Every resident instruction is attached to every request; the concept of instruction budget reminds me that the number of rules itself is a cost. This understanding later determined the admission criteria for the Skill: for a rule to enter the root file,it must prove that it has long-term residency value. This understanding also explains a counterintuitive phenomenon: why the more carefully supplemented rules there are, the more unstable the Agent's performance becomes.

Third, good instructions must have evidence, scope, and long-term value. This is the triple criterion I distilled from the original text's subtraction suggestions: rules should correspond to currently verifiable facts in the repository (evidence), take effect only within the scope where they apply (scope), and be worth occupying the budget for the long term (long-term value). These three points later became the core of the Skill's rule policy.

Fourth, on-demand loading is the direction, but it is not a free lunch. Progressive disclosure solves the problem of "too much resident content," but discovery and reading themselves have costs, so the ideal form is not to split files into a hundred pieces,but to make the entry point sufficiently concise while allowing details to be reliably found. Splitting files itself is never the goal; a reliable entry point is.This understanding directly influenced the direction of a key mechanism upgrade for this Skill later—its outcome is left to Chapter 5.

A surface contradiction

Now we must honestly face a contradiction. The original text leans against automatic generation, wary of those one-click generated large templates—the moment a file is generated is often the moment it begins to rot. And the AgentsMD-GEN I made is, from its name, a "generator." This contradiction cannot be avoided: if I do not even address the original text's objections, the engineering details that follow are just talking to myself.

My answer is: the objects of opposition on both sides are actually the same. What the original text opposes is crude automatic generation that is evidence-free, boundaryless, and a one-time dump; AgentsMD-GEN does not oppose automation itself, and what it opposes is also this kind of crudeness. This Skill requires every rule to have repository evidence, correct scope, and long-term value,and writing must be constrained by acceptance gates. Automation here is only a tool; discipline is the line that separates it from crude generation.In other words, the question has never been "whether machines should participate," but "whether, when machines participate, they abide by the same discipline as careful manual maintenance."

So this is not a rebuttal of the original text, but an engineering extension that follows its philosophy: turning "the discipline a person should follow when writing files" into "a process that must also be followed when a machine executes." Of course, to be honest, this is my personal engineering judgment based on the original text's philosophy, and this Skill cannot prove that it outperforms other approaches in all real projects.

From Principles to Mechanisms

A philosophy only counts once it is turned into a mechanism. The design goal of AgentsMD-GEN can be stated in one sentence: treat AGENTS.md as scarce persistent context to be governed—every rule must have repository evidence, the correct scope, and long-term value, and the root file must not be written as a project encyclopedia or a filesystem map. This maps exactly onto the first three insights from the previous chapter.

The first mechanism is the placement of instructions. The Skill uses two axes—"coverage scope × activation condition"—to decide where an instruction goes: global rules needed for almost every task go into the root AGENTS.md; stable rules for an independent subproject go into that subproject's own local AGENTS.md; rules triggered only by specific tasks such as testing, security, or release go into the corresponding scope's .agent-guides. To be clear, .agent-guides is this Skill's own engineering convention, not a native standard of all Agent hosts.

The second mechanism is restraint. This Skill does not "rewrite whenever it sees an AGENTS.md." It distinguishes three situations—create, maintain, and audit—and explicitly specifies: pure discussion, research, planning, or read-only inspection always skips the maintenance gate;ordinary feature implementation, and the usual result is "AGENTS.md: no changes needed." Only when verifiable facts have appeared in the repository and the existing instructions are genuinely missing or inaccurate does it propose a minimal change. This fulfills the promise made in the previous chapter—automation is constrained by discipline.

The third mechanism is a read-only checker. The Skill ships with a check script that summarizes in JSON the instruction hierarchy, Git status, manifests, independent subproject candidates, command sources, path references, document links, and Agent Guide issues; the current schema version is 1.2. Its role must be stated accurately: the checker only provides a list of facts and risk signals; whether to ultimately create, update, or block is still judged by the Agent in light of the rule policy—it is a collector of evidence, not an authoritarian judge.

The fourth is verification. In the current repository, the Skill's quick validation passes, and all 14 unit tests pass. What this proves is: the current structure meets the validator's requirements, and every behavior listed by the checker has test coverage. It cannot prove more—no defects, compatibility with all hosts, effectiveness in all real repositories—none of these are within the scope of the evidence.

Finally, look at evolution. The repository's public commit history has four commits: the initial lifecycle Skill, adding general installation hints, implementing progressive layered instructions, and adding the layered Agent Guide protocol—three of which are feature commits that constitute a clear mechanism evolution. Most interesting is the last step: the earlier design still relied on the root file explicitly maintaining entry points pointing to detailed documents, and such pointers carry drift risk as files are added or removed. The latest Agent Guide protocol upgrades this to dynamic discovery: the root file no longer maintains a drift-prone list of guide files, but instead lets the Agent discover the current entry points when needed. This is exactly a step from static organization toward dynamic organization in progressive disclosure—the hook planted by the fourth insight in the third chapter is closed here.

Making Discipline Executable

Back to the question from the first chapter. The value of AGENTS.md has never been in thickness, but in governance: rules must have evidence, scope, and long-term value, and details must be disclosed on demand. These things that sound like personal cultivation can actually be distilled into executable rules—AgentsMD-GEN is one such attempt,It turns "conscientiously maintaining a configuration file" from a matter of self-discipline into a process: you don't need to memorize how many principles, just answer those three questions every time you write—is there evidence? Is the scope right? Is it worth keeping long-term?

The boundaries should also be stated honestly: this is just one repository, an engineering practice within one commit history, not a universal standard; passing validation and tests does not mean zero defects. Automation won't think for people; what it does is make "conscientiousness" no longer depend entirely on self-discipline.

So in the end, the question goes back to you: how long has your AGENTS.md gone without being governed?