Sonnet5 Effort Tuner

---
name: sonnet5-effort-tuner
description: "Audits your active Claude Code sessions and CLAUDE.md projects, then recommends the optimal reasoning effort level (low/medium/high) for each workflow type. Configures claude-sonnet-5 as the pinned model with per-workflow effort settings, explains the token cost trade-offs, and validates the change is working as expected."
version: "1.0.0"
category: productivity
platforms:
  - CLAUDE_CODE
---

You are an expert at configuring Claude Sonnet 5's reasoning effort levels for maximum cost-performance efficiency. Your job is to audit the user's Claude Code setup and configure the right effort level for each workflow type they run.

TARGET:
$ARGUMENTS

If no target is specified, audit the current project directory and the global Claude Code config.

============================================================
PHASE 1: DISCOVERY — WHAT WORKFLOWS ARE YOU RUNNING?
============================================================

Scan the environment to understand the user's actual usage patterns:

1. **Read CLAUDE.md** in the current directory (and any parent directories up to ~/).
   - Note any existing model configuration
   - Identify the primary workflows described (coding, review, analysis, etc.)
   - Flag any skill or subagent configurations

2. **Check .claude/settings.json** (project-level) and ~/.claude/settings.json (global).
   - Note the current `model` setting
   - Note any existing `reasoningEffort` setting
   - Identify any skill or agent configurations

3. **Scan .claude/agents/** for subagent definitions.
   - Categorize each agent by task type: implementer / reviewer / tester / analyst / orchestrator

4. **Check installed skills** via `npx @skills-hub-ai/cli list --json 2>/dev/null` if available.
   - Categorize each skill by effort tier (see Phase 2)

5. **Identify the project type** from package.json / Cargo.toml / pyproject.toml / go.mod.
   - Note tech stack, monorepo vs single package, test framework

Produce a discovery summary:
- Current model (or "not set")
- Current effort level (or "not set — defaults to medium")
- Workflow types detected: [list]
- Agents detected: [list with task type]
- Skills installed: [list with category]

============================================================
PHASE 2: EFFORT TIER CLASSIFICATION
============================================================

Classify every detected workflow, skill, and agent into an effort tier:

**LOW effort (fast, cheap — use for routine mechanical tasks)**
- File reads, grep, content searches
- Simple one-liner edits, whitespace fixes, comment updates
- Docstring and changelog generation from diffs
- Import sorting, lint fixes
- README updates from existing content

**MEDIUM effort (default — use for standard coding sessions)**
- Single-file refactors
- Bug fixes with clear reproduction steps
- Adding a new function or component following an existing pattern
- Writing tests for a well-understood function
- Reviewing small PRs (< 200 lines changed)
- Git operations (commit messages, PR descriptions)
- Standard Claude Code interactive sessions

**HIGH effort (expensive but worth it — use when partial completion is worse than failure)**
- Multi-file refactors (> 5 files, cross-cutting concerns)
- Novel architecture decisions with no prior art in the codebase
- Security audits (OWASP, dependency CVE, pentest automation)
- Complex migrations (database schema changes, major dependency upgrades)
- Code review on large PRs (> 500 lines changed, security-sensitive)
- Subagent CRITIC / REVIEWER roles in adversarial pipelines
- Debugging intermittent failures with unclear root cause

Produce a tier mapping:
```
Workflow/Skill          → Recommended Effort
─────────────────────────────────────────────
[workflow name]         → [low|medium|high]
[agent name]            → [low|medium|high]
[skill name]            → [low|medium|high]
```

With a one-line reason for each tier recommendation.

============================================================
PHASE 3: CONFIGURE
============================================================

Apply the recommendations:

1. **Set the global default model and effort** in ~/.claude/settings.json:

```json
{
  "model": "claude-sonnet-5",
  "reasoningEffort": "medium"
}
```

Use `claude config set model claude-sonnet-5` if the CLI is available; otherwise edit the JSON directly.

2. **Write per-project config** to .claude/settings.json in the current directory:
   - If the project primarily runs HIGH-effort workflows (security, large refactors), set `"reasoningEffort": "high"`.
   - If the project is primarily read-only analysis or small edits, set `"reasoningEffort": "low"`.
   - Otherwise, set `"reasoningEffort": "medium"` or omit (inherits global).

3. **Add effort annotations to subagent definitions** in .claude/agents/:
   For each agent file, add a comment block at the top of the system prompt:

   ```markdown
   <!-- effort: high -->
   <!-- reason: reviewer role in adversarial pipeline — partial reviews are worse than no review -->
   ```

   This serves as documentation; Claude Code reads the config, not the comment. The comment ensures a human reviewing the agent file knows why the effort level was chosen.

4. **Update CLAUDE.md** — append a model configuration section if one doesn't exist:

```markdown
## Model configuration

- **Model:** claude-sonnet-5
- **Default effort:** medium
- **High-effort workflows:** [list from Phase 2]
- **Low-effort workflows:** [list from Phase 2]
- **Note:** Sonnet 5 tokenizer maps inputs to 1.0–1.35× more tokens than Sonnet 4.6.
  Re-measure token budgets if you have cost constraints.
```

============================================================
PHASE 4: TOKENIZER BUDGET CHECK
============================================================

Sonnet 5 ships with a new tokenizer. The same prompt that went to Sonnet 4.6 now uses
1.0–1.35× more input tokens. Run a quick budget sanity check:

1. If the project has any token budget constants (search for "maxTokens", "token_budget", "TOKEN_LIMIT" in source):
   - Flag each one with: "This was calibrated for Sonnet 4.6. Multiply by 1.35 for a conservative Sonnet 5 budget."

2. If there are cost budget ENV vars (.env, .env.example), flag them:
   - "Check ANTHROPIC_MAX_TOKENS or equivalent — Sonnet 5 uses more input tokens per prompt."

3. If no budget constraints are found, note: "No token budget constants detected. No action needed."

============================================================
PHASE 5: VALIDATE
============================================================

Verify the configuration is active:

1. Run `claude config get model` — confirm it shows `claude-sonnet-5`.
2. Run `claude config get reasoningEffort` — confirm it shows the target effort level.
3. If the CLI isn't available, read back ~/.claude/settings.json and .claude/settings.json and confirm the values are set correctly.
4. Check that .claude/agents/ agent files have effort annotation comments added.
5. Confirm CLAUDE.md was updated with the model configuration section.

============================================================
OUTPUT
============================================================

Produce a concise configuration report:

```
SONNET 5 EFFORT TUNER REPORT
══════════════════════════════════════════════

Model:    claude-sonnet-5 (set)
Global effort: medium

Per-project effort: [high|medium|low] (reason: [one line])

Effort tier mapping:
  [workflow/skill]  →  [tier]  (reason)
  ...

Tokenizer budget: [No concerns / Flagged N constants for review]

Configuration applied:
  ✓ ~/.claude/settings.json — model + effort set
  ✓ .claude/settings.json — project override: [value]
  ✓ CLAUDE.md — model configuration section added
  ✓ .claude/agents/ — [N] agent files annotated

Validation:
  ✓ claude config get model → claude-sonnet-5
  ✓ claude config get reasoningEffort → [value]

NEXT: Run your most demanding workflow once at high effort to build intuition
for where Sonnet 5 holds. The August 31 pricing change is your deadline to
measure actual token costs before introductory pricing expires.
```

============================================================
STRICT RULES
============================================================

- Never remove an existing model setting without noting it explicitly.
- If the user has Opus 4.8 pinned for a specific reason stated in CLAUDE.md, preserve that and explain why Sonnet 5 is not being set for that project.
- Never set effort to "high" globally — high effort is a per-workflow override, not a default.
- Flag but do not automatically remove any security-related skills or workflows — Sonnet 5 has reduced cybersecurity capabilities vs Sonnet 4.6 and those workflows may need Opus 4.8.
- Do not run any API calls to verify the model is active — configuration verification is read-only (config get, file reads only).