# token-coach

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.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 389 installs · ★ 2710
- Author: alexgreensh
- License: LicenseRef-Unknown · policy=link-only · description only; the file stays with the author
- Source: https://github.com/alexgreensh/token-optimizer/tree/HEAD/skills/token-coach/SKILL.md
- Updated: 2026-10-23
- HTML: https://affpapa.org/en/nevibecode/skills/token-coach

## What it 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.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add alexgreensh/token-optimizer --skill token-coach -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/token-coach/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/token-coach/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add alexgreensh/token-optimizer --skill token-coach -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/token-coach/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add alexgreensh/token-optimizer --skill token-coach -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/token-coach/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install alexgreensh/token-optimizer token-coach
```

2. **Manually: put the files in place**
- File: `.github/skills/token-coach/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add alexgreensh/token-optimizer --skill token-coach -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/alexgreensh/token-optimizer --path skills/token-coach
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/token-coach/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add alexgreensh/token-optimizer --skill token-coach -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/alexgreensh/token-optimizer/tree/HEAD/skills/token-coach/SKILL.md

## When to use it
- 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
- 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?

## Similar
- [setup-matt-pocock-skills](https://affpapa.org/en/nevibecode/skills/setup-matt-pocock-skills.md) — skill · 1052851 installs
- [ask-matt](https://affpapa.org/en/nevibecode/skills/ask-matt.md) — skill · 766587 installs
- [to-tickets](https://affpapa.org/en/nevibecode/skills/to-tickets.md) — skill · 711230 installs
- [writing-plans](https://affpapa.org/en/nevibecode/skills/writing-plans.md) — skill · 282859 installs
- [caveman-review](https://affpapa.org/en/nevibecode/skills/caveman-review.md) — skill · 411800 installs
- [caveman-compress](https://affpapa.org/en/nevibecode/skills/caveman-compress.md) — skill · 411500 installs

From the same set: [alexgreensh/token-optimizer](https://affpapa.org/en/nevibecode/by/alexgreensh/token-optimizer.md) — 3 cards

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md