Agents md Token Auditor

The Problem

You wrote a 1,000-line AGENTS.md because you wanted your agent to be thorough. Now every turn loads those 7,000–10,000 tokens into context whether the task needs them or not. By turn 20, context is at 78%, compaction kicks in, and the agent starts "forgetting" architectural decisions you established an hour ago. You restart the session, re-explain everything, and lose momentum. The root cause isn't the model — it's that your instruction file treats every instruction as always-on when most of them should be on-demand.

What You Get

• Per-section token cost breakdown — exact token estimates for every section in AGENTS.md, CLAUDE.md, and .cursorrules, so you can see which 200-line section is eating 3,000 tokens per turn.
• Always-on vs on-demand classification — a three-bucket sort (Always Load / Load on Demand / Remove) with reasoning for each, so you know what belongs in the instruction file vs a skill.
• Context cost calculator — multiply per-turn cost by session length to see the real token bill: "This 8,000-token instruction file costs 160,000 tokens over a 20-turn session."
• Step-by-step migration plan — specific instructions for moving on-demand content into skills with progressive disclosure (skill name + description in context, full content only when triggered).
• Before/after context budgets — projected token usage at turn 10, 20, and 30, pre- and post-migration, so you can quantify the improvement before making changes.
• Anti-rot checklist — a recurring audit template to prevent context file bloat from creeping back after you've cleaned it up.

Why This Beats Prompting It Yourself

Ask an LLM "is my AGENTS.md too long?" and it reads the whole file once, says "it looks fine," and moves on. It can't tell you that the 40-line Docker section costs 280 tokens per turn across 25 turns (7,000 tokens total) when you haven't written Docker in three weeks. This skill applies a fixed audit taxonomy: inventory, cost, classify, migrate. The output is a prioritized action list with exact token deltas, not vibes.

Example Session

You: "My Claude Code sessions compact at turn 15 and the agent loses track of our API conventions. Here's my AGENTS.md."

Agent: Scanned 3 files, 1,247 lines total.

TOKEN AUDIT — AGENTS.md (1,247 lines / ~8,400 tokens)

Section                  Lines  Est. Tokens  Classification
───────────────────────  ─────  ───────────  ────────────────────────
API Conventions          85     580          ALWAYS (you reference
                                             this every session)
Docker Deployment        200    1,340        ON DEMAND (last used 12
                                             days ago)
Testing Standards        95     640          ALWAYS
Git Workflow             180    1,210        ON DEMAND (agent already
                                             knows git basics)
Error Handling Patterns  70     470          ALWAYS
Security Checklist       240    1,610        ON DEMAND (only needed
                                             for auth/payment work)
Database Conventions     60     400          ALWAYS
Performance Guidelines   150    1,010        ON DEMAND (rarely
                                             relevant)
Code Style Rules         120    810          REMOVE (your linter
                                             handles this)
Contributing Guide       47     315          REMOVE (belongs in
                                             README.md)

TOTAL PER TURN: ~8,375 tokens
SESSION COST (20 turns): ~167,500 tokens

MIGRATION PLAN:
1. Move Docker Deployment (1,340 tok) → docker-deployment.md skill
2. Move Git Workflow (1,210 tok) → git-workflow.md skill
3. Move Security Checklist (1,610 tok) → security-checklist.md skill
4. Move Performance Guidelines (1,010 tok) → performance-guidelines.md skill
5. Remove Code Style Rules (810 tok) → already handled by linter
6. Remove Contributing Guide (315 tok) → belongs in README.md

POST-MIGRATION:
Per-turn tokens: 8,375 → 3,100 (63% reduction)
20-turn session cost: 167,500 → 62,000 tokens saved
Estimated compaction delay: turn 15 → turn 28+

Use Cases

• Preparing a large monorepo for a multi-day refactor where session continuity is critical.
• Onboarding a new team member who inherited a bloated AGENTS.md and needs to understand what's load-bearing vs noise.
• Quarterly context hygiene — scheduled audit to catch bloat before it degrades session quality.
• Migrating from a single giant instruction file to a progressive-disclosure skill architecture.
• Justifying a context optimization initiative with concrete token-cost numbers for your team.

Known Limitations

This skill audits token economics, not instruction quality — it won't tell you if your Docker instructions are wrong, just that they're expensive. It estimates token counts using heuristics (chars / 4), not a tokenizer, so actual counts may vary ±10%. The migration plan is a recommendation; you review and approve each move.