Why Your AI Agent Keeps Getting Dumber (And How I Cut 80% of the Token Waste)

More instructions do not make smarter agents. Here is why massive prompt wikis choke LLM reasoning, and how I cut 80% of the token waste by splitting monolith skills into lean micro-packs.

Published 2026-09-12T00:00:00.000Z

A token-optimized agent skill is a procedure the model loads only when the job starts - not an encyclopedia dumped into SKILL.md.

Git is the clean case. “Commit this” should not pay for Git Flow, branch protection, and reflog. Init, commit, PR, and ops are different verbs, different tools, and different definitions of done. Split them and the agent reads 2–3k tokens, not 12k.

This is the 8-minute build: criteria, the load model, the pack, the files, and the evals.

Why Git, not design

Why use Git as the benchmark case study instead of something familiar like a design system?

Because not all domains should be split. A design skill often shares one “done”: hierarchy, type, spacing, and motion. If you ask an agent to style a button or layout a hero section, it needs colors, typography, and spacing all at once. Splitting “color” from “type” only forces the model to co-activate both files on every single task, defeating the split entirely. With design, you thin the body and park the style guide in references/.

Git does not work like that. Git is not a unified style guide; it is a set of mutually exclusive workflows. Public skills already argue with each other:

netresearch/git-workflow-skill is the monolith - branching, Conventional Commits, PRs, Actions, hooks, and rebase - with references/ as an appendix.
softaworks commit-work is one job: inspect → split → stage → message → verify.
Copilot setups install a conventional-commit skill and a create-PR skill as two packages.
Addy Osmani’s pack parks git-workflow-and-versioning in Ship, next to CI, not as the whole SDLC.

Same instinct you already had: init, commit, PR, other. Design is a style guide where everything is needed at once. Git is a set of isolated procedures where you only pay for the verb you run.

Metric / Aspect	Monolith (`git-workflow`)	4-Skill Modular Pack
Token Load on "Commit"	~12,000 tokens dumped every turn	~2,400 tokens on the job
Context Scope	Branching, commits, PRs, hooks, CI, rebase	Only `git-commit` body loads
Startup Cost	1 massive prompt entry	4 × ~100 token descriptions
Behavioral Risk	Hallucinations & displaced defaults	Fast, deterministic execution

What a skill is

A skill is a folder: YAML frontmatter, a Markdown body, and optional scripts/, references/, and assets/.

It is not a prompt (this session). Not a tool (an action). Not RAG (changing facts). It is the playbook for a class of tasks.

Write one only when the base model keeps failing the same house procedure: staging rules, secret scanning, “never force-push main,” or PR risk blocks. SkillsBench showed that compact and standard skills lifted pass rates about 19–21.5 points. Comprehensive docs were almost flat at +0.7. Self-generated skills hurt versus no skill. Encode a human procedure, then eval-gate edits.

If you cannot answer these in the body, you do not have a skill yet. You have a topic:

When does this load?
What is the ordered path, including stops?
Which invariants never move?
What does done look like?
Which file opens only on the side path?

Layer	File / Location	Primary Role	In Context?
Frontmatter	`name` & `description`	High-precision classifier (max 1,024 chars)	Always (~100 tokens)
Body	`SKILL.md` (2–3k tokens)	Ordered checklist & non-negotiable stop rules	On Trigger Only
Resources	`references/` & `scripts/`	Heavy templates, schemas, and automation scripts	Only When Explicitly Called

The load model is the budget

The Agent Skills spec loads in three tiers. Those tiers are the token budget.

Tier	What	When	Token Budget
Tier 1: Metadata	`name` + `description`	Every session, every installed skill	~100 tokens each
Tier 2: Instructions	Full `SKILL.md` body	When description matches the task	Target 2–3k (spec recommends under 5k)
Tier 3: Resources	`references/`, `scripts/`, `assets/`	Only when body tells the agent to open	Unbounded. Pay per read

Two optimizations, stacked:

Inside a skill. SKILL.md is a router. Anthropic’s PDF skill keeps form-filling in forms.md so it is read only when filling a form. Keep the body under ~500 lines. References one hop deep.
Across skills. Do not activate “git workflow” for a commit message. Split exclusive jobs so the wrong wiki never enters context.

A 196-skill dump still lost to a small ordered shortlist (29.3% vs 45.3% pass rate, ~23% more input tokens). SkillsBench’s best default was one to three skills per task. Bigger bundles cut the gain almost in half.

Skill Length (SkillsBench)	Pass-Rate Lift vs. No Skill	Token Efficiency
Standard (2–3k tokens)	+21.5%	Optimal sweet spot
Compact (under 2k tokens)	+19.0%	Fast, high recall
Detailed (5–10k tokens)	+14.5%	Marginal drop-off
Comprehensive (10k+ wiki)	+0.7%	Near-zero lift, pure token waste

When to split

Progressive disclosure inside one skill is necessary and not sufficient. Split when all three are true:

Trigger language differs (“commit this” vs “open a PR” vs “set up Git Flow”).
Definition of done differs (message vs gh pr create vs hooks installed).
A merged body would blow 3k tokens.

Keep together when the second file would always open. Commit types belong in git-commit, not a fifth skill. The Conventional Commits table is a reference, not a sibling workflow.

Task Prompt: "Commit this change"
      │
      ├──► git-commit  [LOADED: ~2.4k tokens]
      ├──► git-pr      [COLD: 0 tokens]
      ├──► git-init    [COLD: 0 tokens]
      └──► git-ops     [COLD: 0 tokens]

Design skills usually fail this test. Git passes it.

The pack

Four skills. Exclusive jobs. Startup cost is four descriptions - about 400 tokens - not 20k of Git wiki.

git-init

Loads when: new repo, branching model, hook install, branch protection.
Done: strategy chosen, hooks installed, default branch protected.
Stays out: commit copy, PR templates, rebase internals.

Put hook installation in scripts/install-hooks.sh. The body says when to run it; it does not paste bash into context. Deterministic code is cheaper than regenerating a pre-commit file every session.

Cover Git Flow vs GitHub Flow vs trunk-based as a short decision table, then link references/branching-strategies.md for the diagrams. Most repos need one paragraph, not three strategies.

git-commit

Loads when: commit, stage, split hunks, amend an unpushed commit, write a message.
Done: atomic Conventional Commit. No secrets. No git add ..
Stays out: PR body, CI YAML, history rewrite.

This is the daily path. Keep it lean. commit-work already has the shape: git status / git diff → split by concern → git add -p → git diff --cached → what/why → Conventional Commits → smallest verify.

Iron laws belong here because they fail in production, not because they sound wise:

Never git add .
Never commit .env, id_rsa, *.pem
Never amend a commit that left the machine
Subject ≤ 72 characters. Body explains why.
Prefer feat(scope): over inventing a type

Move the type table to references/commit-message-template.md. Tell the agent to open it only if the staged diff does not name its own type.

git-pr

Loads when: open or update a PR, review checklist, merge.
Done: gh pr create with tests, risk, rollback.
Stays out: rebase pedagogy, hook YAML.

The body is a checklist: branch is pushed, commits are already conventional, template filled, test plan, risk, rollback, reviewers. Merge strategy is one line pointing at repo policy - squash vs merge vs rebase - not a blog post about GitHub.

If the working tree is dirty, the description should allow co-activating git-commit. That is the rare legitimate two-skill load. Still under ~5k combined if both bodies are lean.

git-ops

Loads when: conflict, rebase, cherry-pick, reflog, incident recovery.
Done: recovered history. Shared main not rewritten.
Stays out: daily commit style, PR templates.

This is the skill you want cold for months. When it fires, you want the recovery path, not a lecture. Keep “never force-push shared branches” as an iron law. Park the reflog cookbook in references/conflict-recovery.md.

skills/
├── git-init/
│   ├── SKILL.md
│   └── scripts/install-hooks.sh
├── git-commit/
│   ├── SKILL.md
│   └── references/commit-message-template.md
├── git-pr/
│   ├── SKILL.md
│   └── references/pr-template.md
└── git-ops/
    ├── SKILL.md
    └── references/conflict-recovery.md

Write the classifier first

Start from real prompts, not an outline. Ten that should fire git-commit. Ten that should not.

Should fire: “commit this”, “split these hunks”, “conventional message”, “amend the last commit” (unpushed).
Should not: “open a PR”, “set up Git Flow”, “explain rebase”, “protect main”.

Put those verbs in description (max 1,024 characters). Vague copy is why skills never load. Frontmatter is the only thing every session pays for. Make it a classifier.

---
name: git-commit
description: >
  Inspect, split, stage, and commit local Git changes using
  Conventional Commits. Use when the user asks to commit, stage,
  amend an unpushed commit, split mixed hunks, or write a commit
  message. Do not use for pull requests, branching strategy,
  hooks, or history rewrite.
---

The body is a checklist the agent can execute. Delete anything the model already knows. “Write a clear message” is sludge. “Subject ≤ 72, body = why, footer Closes #123 when an issue exists” is a skill.

# git-commit

## Path

1. `git status` && `git diff`
2. Split mixed hunks. Never `git add .`
3. `git add -p` → `git diff --cached`
4. Subject ≤ 72. Body = why. No secrets.
5. Open `references/commit-message-template.md` only if type is still ambiguous.
6. `git commit` then `git status`

## Stop

- Secrets in the diff → unstage, report, do not commit.
- Commit already pushed → do not amend. Open git-ops if they asked to rewrite.

After a week of traces: fold any reference the agent always opens back into the body (ten lines). Trim anything it never consulted. If two skills always co-activate, merge them.

Failure modes

These are how token budgets die:

Topic skill. “Everything Git.” Description matches every Git noun. You are back to the monolith with extra folders.
Encyclopedia body. Type tables, Git Flow diagrams, and Actions YAML in SKILL.md. You ignored tier 3.
Polite sludge. “Be careful. Write clearly. Follow best practices.” Zero routing value. Positive token cost.
Too many skills. Four Git skills is a pack. Forty Git skills is a catalog the classifier cannot use. Metadata is cheap per skill and expensive in aggregate. One to three loaded per task.
Generated playbooks. Dumping docs into an LLM and asking for SKILL.md produces comprehensive skills. Comprehensive skills score +0.7. Write the output by hand once. Encode that.
Wrong layer. If the facts change every week, that is retrieval. If it is a CLI with a stable schema, that is a tool. If it is house procedure, that is a skill.

Prove it

A prettier SKILL.md is not an optimized skill. Hold model, harness, tools, and budget fixed.

[ Baseline: No Skill ] ──► [ Control: Monolith ] ──► [ Candidate: 4-Skill Pack ]
                                                              │
                                                              ▼
                                                     [ Keep the Winner ]
                                            (Hold model, tools, and budget fixed)

Measure four things, separately:

Routing. Did the right skill load? “Commit this” firing git-pr is a description bug, not an execution bug.
Trajectory. git add -p or git add .? Amend after push?
Tokens. Commit traces stay in the 2–3k instruction band. PR traces do not contain hook YAML. Reference files appear only on side paths.
Pass rate. Same tasks: mixed-hunk commit, secret in the tree, “commit this” that must not open a PR, PR that must not rewrite history, init on a repo that already has main.

SkillsBench saw negative deltas on 13 of 87 tasks when a skill prescribed a heavy pipeline or displaced a better default. If the pack loses to no skill on a task, delete that instruction. Do not add a paragraph.

Token success: Four metadata blobs in the system prompt, one lean body on the job, cold skills stay cold.
Quality success: Conventional Commits without a 15k Git manual in context.

Ship this

Write the output by hand once. Encode that procedure. Split on exclusive jobs. Keep each body at 2–3k. Move tables to references/. Run hooks as scripts. Eval against the monolith. Keep the winner.

That is a token-optimized skill.

Sources. Agent Skills spec · Anthropic: Equipping agents with Agent Skills · Arize / SkillsBench · git-workflow-skill · commit-work · Progressive disclosure ~22×