token-coach — Claude Code skill: token spend review
A skill that talks through where your tokens go in a Claude or Codex setup, then proposes changes based on numbers measured on your machine.
npx skills add alexgreensh/token-optimizer --skill token-coach -a claude-codeWhat token-coach does
token-coach ships inside the Token Optimizer bundle. It calls measure.py to read your usage and holds a coaching conversation instead of dumping a report. Expect one or two findings, then a question, and the rest follows your answers.
The skill first identifies the harness: Claude, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode and others. After that it runs measurement commands. coach --json returns a snapshot, named patterns and a 7-day history; quality current --json scores the session you are in. On Claude you also get the subagent cache check, compact-window advice and the daily recommendations record. Codex gets a codex-doctor pass over the current project. Commands that older installs do not have are simply skipped.
Every figure it cites comes from those outputs or from the bundled quick reference. Thin data means the skill says so and works from your own account of the problem. Want the setup actually edited? That job goes to token-optimizer, the neighbouring skill. Token Optimizer has to be installed beforehand, because without measure.py token-coach cannot start.
What it helps with
- see which parts of a session burn tokens
- find why context fills up too fast
- plan a new build that stays cheap on tokens
- work out which workflow steps need a model
- turn raw usage numbers into a short list of fixes
Example prompts for the agent
- Look at my token usage and tell me what to fix first
- Why does context fill so quickly in this session?
- I'm starting a new project and want it token-efficient from day one — where do I begin?
How to install token-coach
1Skills CLI (Vercel)
npx skills add alexgreensh/token-optimizer --skill token-coach -a claude-code2Manually: put the files in place
~/.claude/skills/token-coach/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/token-coach/
1Skills CLI (Vercel)
npx skills add alexgreensh/token-optimizer --skill token-coach -a codex2Manually: put the files in place
.agents/skills/token-coach/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add alexgreensh/token-optimizer --skill token-coach -a cursor2Manually: put the files in place
.cursor/skills/token-coach/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install alexgreensh/token-optimizer token-coach2Manually: put the files in place
.github/skills/token-coach/SKILL.md1Skills CLI (Vercel)
npx skills add alexgreensh/token-optimizer --skill token-coach -a gemini-cli2Platform CLI
gemini skills install https://github.com/alexgreensh/token-optimizer --path skills/token-coachManually: put the files in place
.devin/skills/token-coach/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add alexgreensh/token-optimizer --skill token-coach -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about token-coach
How do I install token-coach in Claude Code?
Run npx skills add alexgreensh/token-optimizer --skill token-coach -a claude-code, then check that ~/.claude/skills/token-coach/SKILL.md exists.
What does token-coach do?
It examines how tokens are spent in your setup and turns that into a prioritised action plan. You steer the conversation and agree on what to change.
How is token-coach different from token-optimizer?
token-coach advises through a conversation; token-optimizer performs a full audit and edits the setup. When changes to config are needed, the coach hands over to it.
