The Hook

Your AI Skills are running. The results are there. But have you noticed? You blow through your token limits fast and find yourself locked out because of Claude Code's "rate limit."

Picture this: a skill that runs regularly, burning 200,000 tokens on every execution. With the 5-hour sliding window on the Pro plan, you hit the ceiling in 3-4 runs. Locked out, waiting 5 hours.

Token auditing is the tool that keeps you from slamming into that ceiling so soon — and lets you keep building without waiting for the reset.

1. What Is a Token, Really?

A token = a tiny piece of information that the AI model has to process.

• Hello = 1 token
• An average sentence = 10-15 tokens
• A page of documentation = 500-1,500 tokens
• An entire database = millions

The cost is twofold: - Input (what you give the model) = 1 credit - Output (what the model generates) = 5 credits

So if a skill reads 100,000 tokens and generates 20,000, the real cost = 100,000 + (20,000 × 5) = 200,000 units.

2. The Traps: Why You Hit Your Limits So Fast

Trap 1: Reading a Lot to Use Very Little

Real scenario: you have 500 customer records. Your skill needs to analyze 3. But for lack of a filter, it reads all 500.

• Impact: +150,000 pointless input tokens per run
• Risk: you exceed your limit in 5 hours (instead of 8), locked out until the reset
• Fix: query the database intelligently, not in bulk

Trap 2: Doing by Hand What Python Could Do

Real scenario: the AI model turns JSON into CSV. It generates text. Python could have done it in 1 ms.

• Impact: +40,000 wasted output tokens (which cost 5× more)
• Risk: 200,000 extra tokens per run
• Fix: hand off to code whatever doesn't need reasoning

Trap 3: Rereading and Rewriting on Every Run

Real scenario: on Tuesday, you generate an analysis of one of your competitors. On Friday, a new document arrives. You reread ALL 500 prior analyses to regenerate the record.

• Impact: +200,000 input tokens on every update (instead of 5,000 for just the new analysis)
• Risk: you needlessly double your consumption
• Fix: incremental mode — process only the new data

Trap 4: Bloating the System Context

Real scenario: the skill's "prompt" (instructions, templates, examples) grows from 5 KB to 25 KB. That's 5,000 tokens of fixed context on every call.

• Impact: +5,000 input tokens × 100 runs = 500,000 tokens/month lost
• Risk: quota saturated faster with every change to the skill
• Fix: externalize heavy templates, load them on demand

Trap 5: Using an Over-Powered Model for a Simple Task

Real scenario: you use Opus 4.6 to extract numbers from a list. Haiku would have done the job.

• Impact: 2-3× higher consumption for the same result
• Risk: quota needlessly saturated
• Fix: match the model to the actual complexity

3. The Risks of Not Auditing

📊 Quota Risk

• A costly skill × a few runs = saturated in 5 hours
• Without an audit, you don't know where to cut back — so you stop working
• You waste your time waiting for the sliding window to reset

⏱️ Productivity Risk

• Heavy skills → you slam into the rate limit every 5 hours
• You can no longer test, iterate, or experiment smoothly
• You're stuck mid-project, waiting for the reset

🚀 Scalability Risk

• As long as you're alone, it's fine. But what if others join and share the limit?
• Conflict over the shared quota → everyone blocks everyone else

⚙️ Operational Risk

• You deploy a new skill without measuring its impact on your quota
• You don't know why you're blocked the next time around

4. How It Works: Auditing in 3 Phases

What is an auditor? It's an automated script that analyzes your skill like an inspector examining a house: it looks at each step ("are you reading this file? how many tokens?"), runs the numbers, and tells you where you're wasting.

Phase 1: Map

The skill scans every step of your workflow: - Which files are read? - Which calculations are performed? - What gets generated?

Phase 2: Measure

For each step, it estimates the tokens consumed: - Real files in the project → measured with wc for precision - No real data? → conservative estimate - Context accumulation → counted in (often 15-40% of the cost)

Phase 3: Recommend

The skill identifies the costly steps > 15% of the total and proposes optimizations:

Every optimization is quantified: "this action saves you 45,000 tokens = -8% of the total cost."

5. A Real Example: competitor_analyze

Our competitor_analyze skill handles competitive intelligence.

Current state: - 478,000 tokens consumed per run - Required model: Opus 4.6 (heavy) - Frequency: ~2-3 times/week during active periods - Quota impact: heavily impacts the session quota, and you hit the "rate limit" on the 5-hour sliding window that much sooner

Where do the tokens go? (see chart below)

Proposed optimizations: 1. Read the analyses incrementally → -14% (saves 67,000 tokens) 2. Incremental mode for the themes → -10% (saves 48,000 tokens) 3. Externalize the SKILL templates → -4% (saves 19,000 tokens)

Impact: - Tokens consumed (optimized): 271,000 (-43%) - Gain per run: 207,000 tokens saved - Result: instead of hitting the ceiling in 5-6 runs, you can launch 8-10 within the 5-hour window - In concrete terms: you go from "blocked after 2 runs" to "freed up for 3-4 extra runs"

6. Action Plan for Your Team (or for You, if You're Alone)

Step 1: Which Skills to Audit?

• List all your skills in production
• Rank them by usage frequency: "the one you run 10 times/week has to be efficient"
• Start with the top 3 most frequent skills

Step 2: Run the Audit

/token_audit <skill_name>

→ Report generated automatically, zero effort

Step 3: Read the Report

You can read it directly: - Summary Table: tokens consumed, most expensive step, recommended model - Optimizations Table: what to change, estimated gain, complexity

Step 4: Decide What to Optimize

Simple rule: - Gain > 100,000 tokens AND low complexity? → Do it now - Gain > 50,000 tokens AND medium complexity? → Schedule it when you have time - Gain < 50,000 tokens? → Skip it, no ROI

Step 5: Implement and Validate

• Implement the optimization
• Rerun the audit a few weeks later to confirm the gains

PS: you can also build an "Software Architect" Skill (more on that another time) that uses this audit report along with other inputs to propose an advanced optimization plan.

Recommended Frequency (Realistic for One Person)

• When you launch a new skill: audit as soon as you deploy it
• When your quota saturates too fast: audit the suspects
• Every quarter: audit the heaviest skill (to track data growth)

7. ROI: Why It's Worth It

Investment

• Time: a few hours to audit your 3-5 big skills
• Tools: free (built into Claude Code)
• Implementation: depends on the chosen optimizations (1-20 days depending on complexity)

Return

• Short term (a few days): -20% to -40% on the top 3 priority skills = freeing up 3-5 runs per 5-hour window
• Medium term (1-3 months): full portfolio optimized = going from "blocked after 2-3 runs" to "5-6 free runs"
• Long term: you can experiment, test, and iterate without slamming into the rate limit every 5 hours

Concrete example: - You run 3 heavy skills in production - Initial consumption: saturated after 2 runs on the 5-hour window - After audits and optimizations: -40% consumption - Result: instead of getting blocked, you have 3-4 extra runs = productivity regained - Time invested: 1-2 days for the audits + 5-10 days for the priority optimizations - ROI: you get to work smoothly instead of managing constant lockouts

8. The Attachments to This Article

1. Appendix A: How to Use the /token_audit Skill

→ spec_token_audit.md

Everything you need to know to: - Install the skill in your project - Use it (even without knowing how to program) - Interpret the generated report - Understand the limits (it only measures static usage, not real execution telemetry)

2. Appendix B: A Concrete Case — Auditing the competitor_analyze Skill

→ token_audit_competitor_analyze.md

Read the real report to see: - A detailed cost table by step - Where the tokens are "wasted" - 5 proposed optimizations with quantified gains - Before/after comparison

⚠️ The Auditor's Limits (Worth Knowing)

Token auditing is powerful, but it has important boundaries. Being honest about them is how you use the tool correctly.

1. It's a Static Analysis, Not a Real One

The audit reads your code (SKILL.md, referenced files) and estimates the tokens consumed. It doesn't actually run the skill.

Implication: - The estimates are usually close to reality (±15%), but not exact - If your skill contains a conditional loop ("process the analyses only if they're less than 7 days old"), the audit assumes the worst case (process everything) - Real volumes depend on the day's data → variable

When it's a problem: - A skill with lots of conditional branches → the audit may overestimate - A skill that makes external API calls (WebFetch) → the real volume depends on page size

2. No Real Execution Telemetry

The audit has no access to real execution metrics (how many tokens did the last run actually cost?).

Implication: - You only have estimates, not certified measurements - Impossible to validate an optimization with certainty before/after without instrumenting the code

When it's a problem: - If you need precise financial validation → you have to instrument your code (add real-cost logging) - If a skill exceeds 1M units → the discrepancies become significant in euros

3. The Token → Euro Conversion Ratio Is an Estimate

The audit estimates "output = 5× the cost of input" (Claude's rule). That's only true on average.

The nuanced reality: - It's accurate for Sonnet 4.6 and Opus 4.6 - But pricing changes over time (new models, pricing changes) - And your client contracts might have different rates

4. It Doesn't Improve the Skill's "Business" Choices

The audit can say "you read 140 analyses, you could read 50 and go incremental."

But: "should you really go incremental?" That's a business decision, not a technical one.

Example: a skill that revalidates ALL competitors every month (not incremental): that's a choice. The audit flags it, but "it's safer" might be a valid answer.

5. Real Complexity Can Be Underestimated

The audit classifies optimizations by complexity (low / medium / high), but: - An optimization the audit calls "low" could be "high" in your codebase (old code, dependencies) - The estimates assume clean, modular code

Summary of the Limits:

Conclusion on the Limits:

The audit is a flashlight, not a prediction machine. Its estimates are good enough to prioritize, but not enough to say "this will cost exactly X€."

Use the audit: - ✅ To spot the obvious leaks (> 100k tokens) - ✅ To prioritize optimizations (gain ÷ effort) - ✅ To justify architectural changes - ❌ For cost estimates down to the last cent - ❌ To validate results (that requires real logging)

Conclusion

Auditing your skills means going from "why am I blocked every 5 hours?" to "I know where to cut."

It's the equivalent of an energy audit for your quota: you find out where the leaks are, you plug them, and suddenly you have 5-6 smooth runs instead of 2-3 before getting blocked.

3 things to remember: 1. Wasted tokens add up fast and lock you out every 5 hours 2. Without an audit, the waste is invisible — you just lose the ability to work 3. The optimizations are simple and the impact is immediate (longer productive windows)

Ready to start? Run an audit on your most frequent skill. You'll have a report in 5 minutes. The gains will come after.

Frequently Asked Questions

Q: Does the audit slow down my skills? A: No. The audit is a static analysis (it reads your code), not an actual execution.

Q: What if I only have small skills? A: Auditing small skills (< 1,500 tokens) isn't worth it. Focus on your 3-5 biggest consumers.

Q: Can I audit competitors' skills? A: Impossible (you don't have access to their code). The audit only makes sense for your own skills.

Q: What if a skill exceeds 500,000 tokens per run? A: That's a red flag. Priority audit. There are often 40-50% of savings to be had.

Q: How much does an audit cost? A: Zero (it's free, built into Claude Code). Implementing the optimizations takes 1-20 days depending on complexity.

Q: Is it worth it if I'm working alone? A: Yes, even more so! You're directly affected by the quota. An optimized skill = 2-3 weeks of work instead of 1.