Token coach

Skill build-with-dhiraj/ai-workflow-framework-portability-kit/Skills/token-coach

Portable, self-contained snapshot of a complete Claude Code setup — 36 specialist agents, 134 skills, plugins, MCP servers & host tooling. Clone, claude login, run one script, restore the whole orchestration stack in ~20 min.

Install

npx -y skills add build-with-dhiraj/ai-workflow-framework-portability-kit --skill token-coach

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

4 stars4 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Context window coach — token-efficiency guidance for Claude Code/Codex, multi-agent systems, and skill architecture.

SKILL.md

6.8 KB, ~1.8k tokens by cl100k_base, as published. Nobody here has run it

Token Coach: Plan Token-Efficient Before You Build

Interactive coaching for Claude Code or Codex architecture decisions. Analyzes your setup, identifies patterns (good and bad), and gives personalized advice with real numbers.

Use when: Building something new, existing setup feels slow, designing multi-agent systems, or want a quick health check.

Phase 0: Initialize

Resolve runtime and measure.py path (same as token-optimizer):

RUNTIME="${TOKEN_OPTIMIZER_RUNTIME:-}"
if [ -z "$RUNTIME" ]; then
  if [ -n "$CLAUDE_PLUGIN_ROOT" ] || [ -n "$CLAUDE_PLUGIN_DATA" ]; then
    RUNTIME="claude"
  elif [ -n "$CODEX_HOME" ] || [ -d "$HOME/.codex" ]; then
    RUNTIME="codex"
  else
    RUNTIME="claude"
  fi
fi

MEASURE_PY=""
for f in "$HOME/.codex/skills/token-optimizer/scripts/measure.py" \
         "$HOME/.codex/plugins/cache"/*/token-optimizer/*/skills/token-optimizer/scripts/measure.py \
         "$HOME/.claude/skills/token-optimizer/scripts/measure.py" \
         "$HOME/.claude/plugins/cache"/*/token-optimizer/*/skills/token-optimizer/scripts/measure.py \
         "$PWD/skills/token-optimizer/scripts/measure.py"; do
  [ -f "$f" ] && MEASURE_PY="$f" && break
done
[ -z "$MEASURE_PY" ] || [ ! -f "$MEASURE_PY" ] && { echo "[Error] measure.py not found. Is Token Optimizer installed?"; exit 1; }
export TOKEN_OPTIMIZER_RUNTIME="$RUNTIME"

Collect coaching data:

python3 "$MEASURE_PY" coach --json

Parse the JSON output. This gives you: snapshot (current measurements), detected patterns, coaching questions, and focus suggestions.

Check context quality (v2.0):

python3 "$MEASURE_PY" quality current --json 2>/dev/null

If available, parse the quality score and issues. This enriches coaching with session-level insights (not just setup overhead). If the command fails (pre-v2.0 install), skip gracefully.

For Codex, check setup readiness:

if [ "$RUNTIME" = "codex" ]; then
  python3 "$MEASURE_PY" codex-doctor --project "$PWD" --json 2>/dev/null
fi

Use this to tell the user whether balanced hooks, compact prompt guidance, dashboard refresh, and status-line support are installed.

Phase 1: Intake

Ask ONE question:

What's your goal today? a) Building something new, want it token-efficient from the start b) Existing project feels sluggish / context fills too fast c) Designing a multi-agent system, want architecture advice d) Quick health check with actionable tips

Wait for the answer. Don't dump info before they choose.

Phase 2: Load Context (based on intake)

Resolve the token-coach skill directory:

COACH_DIR=""
if [ -d "$HOME/.codex/skills/token-coach" ]; then
  COACH_DIR="$HOME/.codex/skills/token-coach"
elif [ -d "$HOME/.codex/skills/token-optimizer/../token-coach" ]; then
  COACH_DIR="$HOME/.codex/skills/token-optimizer/../token-coach"
elif [ -d "$HOME/.claude/skills/token-coach" ]; then
  COACH_DIR="$HOME/.claude/skills/token-coach"
elif [ -d "$HOME/.claude/skills/token-optimizer/../token-coach" ]; then
  COACH_DIR="$HOME/.claude/skills/token-optimizer/../token-coach"
else
  COACH_DIR="$(find "$HOME/.codex/plugins/cache" "$HOME/.claude/plugins/cache" -path "*/token-coach" -type d 2>/dev/null | head -1)"
fi

Load references based on intake choice:

Option a or b: Read $COACH_DIR/references/coach-patterns.md + $COACH_DIR/references/quick-reference.md
Option c: Read $COACH_DIR/references/agentic-systems.md + $COACH_DIR/references/quick-reference.md
Option d: Read $COACH_DIR/references/quick-reference.md only (fast path)

Read the matching example from $COACH_DIR/examples/ as a few-shot template:

Option a: coaching-session-new-project.md
Option b: coaching-session-heavy-setup.md
Option c: coaching-session-agentic.md
Option d: Skip example (keep it fast)

Read $COACH_DIR/references/coaching-scripts.md for conversation structure.

Phase 3: Coach (conversation, not report)

This is a CONVERSATION. Not a wall of text.

Lead with the 1-2 most impactful findings from the coaching data
If quality data is available and score < 70, lead with that instead: "Your current session quality is [X]/100. [Top issue] is eating [Y tokens]."
Reference their actual numbers ("You have 47 skills costing ~4,700 tokens at startup")
Ask a follow-up question. Don't dump everything at once.
For agentic systems (option c): walk through their architecture step by step
Use the coaching scripts for structure, but keep it natural

For Codex specifically, translate all advice to native Codex concepts:

AGENTS.md instead of CLAUDE.md
Codex memories instead of MEMORY.md
balanced Codex hooks instead of Claude hooks
Intelligence levels (Low/Medium/High/Extra High) and model selection (GPT-5.5, GPT-5.4, GPT-5.4-Mini, GPT-5.3-Codex, GPT-5.2) instead of Opus/Sonnet/Haiku routing
Reasoning effort settings instead of model-per-agent routing
compact prompt guidance instead of PreCompact/PostCompact lifecycle hooks
Never reference Claude-specific concepts (Opus, Sonnet, Haiku, CLAUDE.md) when coaching a Codex user

Tone: Knowledgeable friend, not corporate consultant. Be direct about what matters and why. Use real numbers from their data.

Anti-patterns to call out: Reference the anti-patterns from coach-patterns.md. Name them ("You've got the 50-Skill Trap going on").

Continue the conversation for 2-4 exchanges. Let the user ask questions. Adjust advice based on what they tell you about their workflow.

Phase 4: Action Plan

After the conversation, generate a prioritized action plan:

Summarize 3-5 concrete actions, ordered by impact
Include estimated token savings for each action (use the numbers from quick-reference.md)
If quality score < 70 in Claude Code: include "Set up Smart Compaction" as a recommended action (python3 $MEASURE_PY setup-smart-compact)
If quality score < 70 in Codex: include "Install balanced Codex hooks and compact prompt guidance" (TOKEN_OPTIMIZER_RUNTIME=codex python3 $MEASURE_PY codex-install --project .)
If quality score < 50: recommend immediate /compact or /clear before continuing
Flag which actions are quick wins vs deeper changes
Offer to run /token-optimizer for the full audit + implementation if they want to go beyond coaching

Format: Keep it scannable. Numbered list with bold action names, one-line description, estimated savings.

Phase 5: Dashboard (optional)

If measure.py generated a coach dashboard tab, mention it: "Your Token Health Score and pattern analysis are in the dashboard. Run python3 $MEASURE_PY dashboard to see it."

For Codex, also give the generated file location: ~/.codex/_backups/token-optimizer/dashboard.html.