When you write instructions for an AI agent, you're spending a budget you can't see. Every sentence of context, every repeated explanation, every hedged caveat — it all goes into the context window. And context window space is the same space the agent uses to reason, plan, and produce output.
This isn't just a token cost issue. It's a structural attention problem. The longer your instructions, the less cognitive headroom the agent has when it reaches the actual task. Detail feels like thoroughness. In practice, it's often noise that crowds out signal.
Where I Noticed This
I run a system of scheduled agents — tasks that fire on a weekly cadence and produce structured output. Each task has a SKILL.md file that describes what it should do. Over several months of iteration, those files grew. Every time something went wrong, I added a clarifying paragraph. Every time an edge case appeared, I documented it inline.
The result was SKILL.md files that were 300+ lines long. Thorough. Comprehensive. And noticeably worse at producing good output than earlier, shorter versions.
The agent would spend the first half of its context window processing the instructions. By the time it reached the actual work, it had less room to think. Instructions that were meant to improve quality were degrading it.
Estimated context allocation — instructions vs. actual reasoning space
The Pattern: Detail as Debt
Adding detail to agent instructions feels like adding precision. You're covering more cases, preventing more misunderstandings. But each addition has a compounding cost: it pushes the real task further from the top of the agent's working context, and it creates a larger surface area for the agent to lose track of what actually matters.
There's a specific failure mode I've seen repeatedly: the agent reads a long instruction set, finds a low-priority section near the beginning, and fixates on it — spending the first several turns resolving a minor edge case before reaching the core task. The instruction was correct. The prioritization was wrong, and the agent had no way to know it.
Long instructions also make it harder to update the system. When everything is inline, a change to one behavior risks invalidating context that surrounds it. You end up afraid to edit. The file grows by accretion and never shrinks.
What Actually Works
The principle I've converged on: SKILL.md files should be routing hubs, not encyclopedias. The core file contains only what the agent needs every time it runs — the essential phases, the critical constraints, the starting point. Conditional or rarely-needed detail lives in separate module files that get loaded only when the relevant condition is met.
Before adding anything to a SKILL.md, I now ask: "If I remove this, does the agent fail to do the task?" If the answer is no, it goes in a module or gets cut entirely. The test is function, not coverage.
A useful heuristic I've started applying: if a section exists to handle a case that's happened once in six months, it probably shouldn't be in the main file. Edge cases that appear in primary instructions get the same weight as core behavior — and they shouldn't.
What I Don't Know Yet
I'm observing this in a specific system — scheduled tasks running weekly in a particular configuration. I don't have a clean way to measure attention quality directly, so I'm inferring from output quality and session transcripts. It's possible the causation here is different from what I think. Maybe shorter SKILL.md files correlate with better output for some other reason — like the fact that rewriting a file forces you to think through what actually matters.
I'm also not sure where the cutoff is. "Shorter is better" can't be right all the way down. There's some minimum instruction density below which the agent doesn't have enough context to do the task correctly. I haven't found a principled way to identify that threshold yet. Gut feel and output quality are the current instruments.
This is marked Single Case because I've systematically tested this in one project. The pattern feels general, but I'd want to see it hold across different agent configurations before calling it established.
Evolution Log
- 2026-04-21 — Initial observation. Pattern sourced from ECOSYSTEM_PROTOCOL.md documentation principles and SKILL.md growth trajectory over 16 weeks. Modular SKILL.md structure adopted in Atreus, Sheldon, and LifeContext scheduled tasks.