Back to blog
Your AI agent doesn't need explanations. It needs rules.
We spent the last few weeks building a Next.js application alongside an AI coding agent. The code came together quickly. The conventions did not.
Some decisions took several rounds of back-and-forth before the agent and the developer were working from the same assumptions: our preferred Bun, Turborepo and Next.js foundation; global Clerk RBAC without Organizations; React Hook Form with integrated controls rather than loose inputs; calling a second model as an independent reviewer before merging. None of these are complicated. They are simply ours, and the agent had no way of knowing them.
So we stopped re-explaining them every session and wrote them down as skills—instruction files the agent loads when the work calls for them.
Writing for a colleague is not writing for a model
The first version of each skill read the way an onboarding document reads. Full sentences. Background on how we arrived at the decision. A paragraph of "the reason we do this is..." before every rule.
That style is good for people and expensive for models. Every sentence of framing costs input tokens, and worse, it buries the actual constraint somewhere in the middle of a justification. The agent has to reconstruct a rule that we could have simply stated.
The fix was not to write less. It was to write two things.
Two layers per skill
Each skill now has a compact operational layer and a human layer.
SKILL.md is written for the agent. Dense notation: conditions, constraints, commands, invariants. No connective prose, no justification, no restating the obvious.
HUMAN.md keeps the original readable explanation—why the decision was made, what we tried first, what the trade-off was. It is never loaded into the agent's context. It exists so that a person joining the project six months from now understands the reasoning instead of inheriting a list of rules with no history.
Full rationale and context. Read occasionally, by humans.
- no self-demote
- no self-delete
- preserve ≥1 admin
- demotion → revoke sessions
Compact operational contract. Loaded every session, by the agent.
Before and after
Here is a rule about admin user management, written the way a person would naturally write it:
1When managing admin users, please make sure that admins are never 2able to demote themselves, and they also shouldn't be able to delete 3their own account. It's important that there is always at least one 4admin left in the system. Also, when an admin is demoted, remember 5that their active sessions should be revoked.
And the same rule as a contract:
1Admin invariants: 2- no self-demote 3- no self-delete 4- preserve ≥1 admin 5- demotion → revoke sessions
The second version is not a summary. Nothing was dropped. The four constraints are identical—only the packaging changed.
What it measured out to
We rewrote four skills this way and compared the before and after:
- skill bodies went from 13,062 to 7,282 characters, a 44% reduction;
- word count went from 1,880 to 996, a 47% reduction;
- the always-loaded descriptions—the short text the agent sees for every skill in every session, whether or not it activates—went from 796 to 485 characters, a 39% reduction.
Extrapolating with standard English character-to-token ratios, and assuming roughly one relevant skill activation per session, that works out to about 35,000 input tokens saved over 100 sessions. This is an estimate derived from text length, not a figure read off a billing dashboard. We include it because the order of magnitude is the useful part, not the precision.
−44%
skill body size
−39%
always-loaded descriptions
~35K
tokens saved over 100 sessions
Before and after, per metric
Skill body · characters
Skill body · words
Description · characters
Why the gain compounds
Faster. Less context to process means quicker responses and more headroom before the context window becomes a constraint on a long session.
Cheaper. Input tokens are the bulk of what an agent costs. Trimming what loads on every session lowers the baseline rather than the peak.
More focused. This is the underrated one. Agents follow short, hard rules more reliably than long explanations. Compressing the skills did not only reduce cost—it improved instruction-following. The rules stopped competing with the prose around them.
There is a quieter benefit as well. Once a decision is written as a constraint, future sessions start with it already settled. Less repeated clarification at the beginning of a task. Less implementation churn in the middle. And no drift back into patterns we had already rejected.
Distilling your own
If you want to try this on instructions you already have:
- keep the invariants, constraints, commands and file paths;
- cut connective prose, hedging and anything that explains why;
- move the "why" into a human-facing document that sits beside the skill;
- prefer notation over sentences—lists, arrows, comparisons;
- measure the before and after, so the compression is a fact rather than an impression.
Signal over noise
We build tools that reduce friction and irrelevant context, for people and for agents. It turns out the same principle applies to how we talk to machines: signal over noise is not a cost optimization, it is a quality strategy. The cheaper output and the better output arrive together, because they have the same cause.
Keep the rationale for humans. Give the agent the contract.