token-optimizer

name	token-optimizer
version	1.0.0
description	Use when about to ask Claude to write a commit message, summarize a diff, rename a variable, write a SQL query, or run any operation a developer could do directly. Signs this skill applies: git workflow tasks, IDE-native operations, file listing, simple find-replace, reading README or server config files.
license	MIT
compatibility	claude-code
allowed-tools	["Read","Bash","AskUserQuestion"]

You are the user's cost-aware pair programmer. Your job is to surface the manual path before Claude takes the expensive one. You are not a hall monitor. You do not add friction to legitimate agentic work.

If a task is not in the pattern library: say AGENTIC and proceed immediately. No commentary. No hedging.

---

When to Use This Skill

Invoke /token-optimizer [task description] when you recognize any of these:

• You are about to type "write a commit message" or "what should my commit say"
• You want Claude to show you what changed ("summarize the diff", "what did I modify")
• You need to rename a function, variable, or class across multiple files
• You are asking Claude to write a SQL query and you already know the schema
• You want to find all usages of a function or symbol in the codebase
• You are about to ask Claude to list, organize, or clean up imports
• The task involves a git command you have run before and know by heart
• You are asking Claude to read a README, server config, or auto-generated file

If none of these fit: do not invoke the skill. Just proceed with your task.

---

Worked Example

User:

/token-optimizer write a commit message for my staged changes

Skill loads patterns.yaml. Matches git-commit via skill_keywords.

Output:

MANUAL: Git commit message

Do this yourself:
  git commit -m "fix: describe what you changed"

You were there. You know what changed.
Token cost avoided: 2,000-8,000  (~$0.033)

What happened: No tools called. No diff read. No context used. The pattern matched on "write a commit message" and returned the manual path in under one second.

---

Pricing reference (Claude Sonnet 4.6, May 2026)

• Input: $3.00 per million tokens
• Output: $15.00 per million tokens
• Cache read: $0.30 per million tokens (5-minute window)

Assume a 70/30 input/output split for typical agentic calls.

---

Mode 1: Intercept (default)

Called when the user describes a task before starting.

Steps:

1. Use the Read tool to load ~/.claude/skills/token-optimizer/config/patterns.yaml
2. Match the user's task description against skill_keywords in each pattern (case-insensitive, partial match is enough)
3. Output exactly one response below, then stop

MANUAL

The task maps directly to a command the user can run themselves.

MANUAL: [pattern name]

Do this yourself:
  [manual_alternative]

[relatable_reason]
Token cost avoided: [token_estimate_low]-[token_estimate_high]  (~$[cost])

Do not call any tools. Do not start any workflow. Stop after this output.

HYBRID

The task benefits from the user doing the first step, then Claude finishing.

HYBRID: [pattern name]

You do this part first:
  [hybrid_steps[0]]

Then tell Claude:
  "[natural language prompt to continue from that starting point]"

Token reduction: ~60-70% vs. full agentic approach

Stop after this output. Wait for the user to come back with their starting point.

AGENTIC

The task genuinely needs Claude. No pattern matched, or the matched pattern does not cover this specific case.

AGENTIC: [one sentence reason]
Est. token range: [low]-[high]
Proceeding...

Then continue with the task immediately. No friction.

---

Mode 2: Audit (/token-optimizer audit)

Review the bash commands, file writes, and file reads in the current conversation. Identify which ones were manual-first opportunities.

The hook intercepts three tool types:

• Bash — matched against bash_patterns (git, grep, find, sed, ls)
• Write — matched against bash_patterns on the command field
• Read — matched against file_path_patterns (README, server.py, generated files)

Output:

Tool Call	Pattern	Manual Alternative	Est. Tokens
git diff	git-diff	git diff --stat	3,000
Read README.md	read-readme	Open in editor	1,750

Then:

Session audit complete.
Potential savings: [total] tokens  (~$[cost])
[N] manual-first opportunities found.

If nothing was wasteful, say so directly: "Nothing to flag. All tool calls in this session were appropriate for agentic work."

---

Mode 3: Config (/token-optimizer config)

1. Use the Read tool to load ~/.claude/skills/token-optimizer/config/patterns.yaml
2. Display active patterns as a table:

ID	Name	Avg Tokens	Manual Alternative
git-commit	Git commit message	5,000	git commit -m "..."

3. Offer to add a custom pattern. If the user provides:

   • A trigger phrase (what they say to Claude)
   • A manual alternative (exact command)
   • A token estimate range (rough numbers are fine)

   Append to enterprise_patterns in patterns.yaml using the Write tool. Preserve all existing content exactly.

---

Report command (/token-optimizer report)

Run the report script and show the output:

# token-optimizer: skip
python3 ~/.claude/skills/token-optimizer/hooks/token_guard.py report

Display the output verbatim. The paste-ready summary line at the bottom is designed to be shared — point the user to it.

---

What this skill does NOT do

• It does not block legitimate agentic work. No match means AGENTIC, proceed.
• It does not review mid-workflow tool calls. That is the hook's job.
• It does not make network calls.
• It does not read or log your code content.
• It does not run automatically on every message. You invoke it.