Token Coach Skill
Relevant source files
The following files were used as context for generating this wiki page:
The Token Coach skill is an interactive context window advisor designed for Claude Code and Codex environments. Its primary purpose is to help users make token-efficient architectural decisions by analyzing setup overhead, historical usage trends, and session habits. Unlike the Token Optimizer, which automatically applies fixes, the Token Coach focuses on providing personalized, data-driven advice to prevent context bloat before it occurs.
Sources: skills/token-coach/SKILL.md:1-12, skills/token-coach/references/coaching-scripts.md:1-25
Architecture and Execution Flow
The Token Coach operates through a multi-phase execution model that progresses from environment initialization and data collection to interactive coaching and final action planning.
Execution Lifecycle
The following diagram illustrates the high-level logic flow when the Token Coach skill is invoked.
The execution begins by resolving the measure.py script and detecting the current runtime (Claude or Codex). It then gathers a snapshot of current measurements and historical trends using the coach --json and quality current --json commands.
Sources: skills/token-coach/SKILL.md:15-120, skills/token-coach/SKILL.md:162-225
Data Collection and Metrics
The skill relies on the measure.py utility to extract a comprehensive set of metrics from the local environment.
| Data Category | Metrics Collected |
|---|---|
| Snapshot | Current setup overhead (CLAUDE.md, Skills, MCP Servers, MEMORY.md). |
| History | 7-day quality scores, session duration trends, prompt cache hit rates, and total cost (USD). |
| Context Quality | Session-level issues, "stale" file reads, and bloated tool results. |
| Patterns | Detected anti-patterns like "Session Duration Creep" or "Compression Opportunity Gap." |
Sources: skills/token-coach/SKILL.md:112-132, skills/token-coach/references/coaching-scripts.md:160-185
Coaching Scenarios (Intake Options)
The skill provides four specialized coaching paths based on user goals. This "Intake" phase ensures the advice is relevant to the user's immediate technical context.
Option A: Building New Projects
Focuses on "Zero-Cost" architectural patterns. It encourages moving heavy domain knowledge into reference files and maintaining a minimal SKILL.md orchestrator to keep startup overhead low.
Example Actions:
- Keeping skill descriptions under 80 characters.
- Using subagents for context isolation during verbose tasks (e.g., running tests).
- Moving criteria/templates to
references/(zero tokens until read).
Sources: skills/token-coach/examples/coaching-session-new-project.md:12-45, skills/token-coach/references/coaching-scripts.md:27-46
Option B: Sluggish Existing Projects
Identifies "waste sources" in current setups that consume the context window before work begins. It targets overhead from global configs, skills, and MCP servers.
Sources: skills/token-coach/references/coaching-scripts.md:48-65
Option C: Multi-Agent System Design
Calculates the multiplier effect of configuration overhead across multiple agents. It recommends model routing strategies (e.g., using Haiku for data gathering) and context isolation via coordination folders.
Sources: skills/token-coach/references/coaching-scripts.md:67-85
Option D: Quick Health Check
Provides a "Token Health Score" (0-100) and identifies the top three highest-impact actions to recover context immediately.
Sources: skills/token-coach/references/coaching-scripts.md:87-100
Architecture Patterns and Anti-Patterns
The Token Coach identifies specific structural issues and recommends established patterns to optimize the context window.
Common Anti-Patterns
| Anti-Pattern | Description | Fix |
|---|---|---|
| 50-Skill Trap | 50+ skills causing ~5,000 tokens of startup overhead. | Archive unused skills outside the skills/ directory. |
| Opus Addiction | Using high-cost models for simple file-reading tasks. | Implement model routing: default subagents to Haiku. |
| CLAUDE.md Novel | Verbose global config (>200 lines) loading on every message. | Move workflows to skills; target <800 tokens. |
| Import Avalanche | @imports in CLAUDE.md pulling large files every turn. | Move imports to demand-loaded reference files. |
Sources: skills/token-coach/references/coach-patterns.md:55-110
Recommended Patterns
- Skill Design: Keep
SKILL.mdunder 500 lines and usereferences/for heavy content. - Layering: Use Global vs. Project-specific
CLAUDE.mdfiles to isolate concerns. - Rules Scoping: Use
paths:frontmatter in rules to prevent them from loading in irrelevant directories. - Progressive Loading: Move content from
CLAUDE.mdto Skills, which only load full bodies on invocation.
Sources: skills/token-coach/references/coach-patterns.md:7-53
Initialization and Environment Logic
The skill uses a robust bash-based resolver to ensure it uses the most recent version of the measurement engine across different runtimes.
Sources: skills/token-coach/SKILL.md:24-60
Action Plan Generation
At the conclusion of a coaching session, the skill generates a prioritized Action Plan. This plan includes estimated token savings based on documented benchmarks.
- Quick Wins: Archiving unused skills (~100 tokens/skill) or scoping rules.
- Behavioral Changes: Batching requests or using
/compactat 50-70% context fill. - Implementation: Recommendations to run Token Optimizer Phase 4 for automated restructuring.
Sources: skills/token-coach/SKILL.md:205-220, skills/token-optimizer/references/implementation-playbook.md:1-20
The Token Coach Skill serves as the proactive, educational component of the Token Optimizer suite. By combining real-time environmental metrics with a deep library of architectural patterns, it enables developers to maintain high-performance, cost-effective AI development environments.