YahyaLendani/opus-tuner-claude-skill

# claude-skill — portable token discipline

This is the advisory companion to opus-tuner. It needs no hooks, no scripts and no
filesystem: everything here is a habit the model can keep in any Claude client.
Where opus-tuner measures and enforces, this only reminds. Say so if the user
expects the automated version.

## The budget

Track the conversation against two soft ceilings:

| Tier | Ceiling | Meaning |
|---|---|---|
| routine | ~150k tokens | default; most work fits |

This turn runs at **low** effort.

Act directly. No plan, no preamble, no summary of what you are about to do.
Batch independent tool calls into one message.

If the task turns out to need reasoning, say "this needs high" and stop rather than
grinding at low effort — thrashing costs more than the gear saved.

This turn runs at **max** effort.

This gear costs about one extra 150k turn in thinking tokens, so it must buy back at
least one turn of rework. Use it to settle the question in one pass: form the full
hypothesis, verify it, and commit to an answer.

If the answer arrives early, stop thinking and act.

This turn runs at **medium** effort.

Work directly, but check assumptions that touch more than one file. Batch independent
tool calls. Escalate to `/gear-xhigh` only if you hit something genuinely unclear.

This turn runs at **xhigh** effort.

Think before acting: state the hypothesis, then test it with the cheapest possible
tool call. Do not fan out reads until the hypothesis narrows the target.

Reserve `/gear-max` for work where a wrong answer costs more than a full extra turn.

# opus-tuner

Every request re-reads the whole context, so these rules are about how much gets
re-read and how many requests read it.

## The five rules

1. **Batch independent tool calls.** Four greps in one message read the context
   once; four separate messages read it four times.
2. **Grep before read, and bound every read.** `Read` with no `limit`, or above 400
   lines, only when you are certain. Otherwise `offset`/`limit`, or search first.
   Never recursive-scan a repo to find one symbol.
3. **Never trade verification for tokens.** A "saving" that causes rework is a loss.
4. **Delegate breadth, not judgement.** Exploration, mechanical multi-file edits and

# Profile

Run the switcher with the user's argument exactly as given. No argument swaps
dev and creative; `show` changes nothing.

```
# Windows
powershell -NoProfile -ExecutionPolicy Bypass -File "$env:USERPROFILE\.claude\skills\opus-tuner\scripts\profile.ps1" $ARGUMENTS

# macOS / Linux
pwsh -NoProfile -File "$HOME/.claude/skills/opus-tuner/scripts/profile.ps1" $ARGUMENTS
```

If `CLAUDE_CONFIG_DIR` is set, substitute it for `~/.claude` in that path.

# Wrap

Use at a task boundary, or when the user wants to continue in a fresh session.

1. Write the draft. Its facts come from this session's own transcript:

   ```
   # Windows
   powershell -NoProfile -ExecutionPolicy Bypass -File "${CLAUDE_SKILL_DIR}/../opus-tuner/scripts/brief.ps1" -SessionId "${CLAUDE_SESSION_ID}" -Project "<project directory>"

   # macOS / Linux
   pwsh -NoProfile -File "${CLAUDE_SKILL_DIR}/../opus-tuner/scripts/brief.ps1" -SessionId "${CLAUDE_SESSION_ID}" -Project "<project directory>"
   ```