/optimize-skills to survive token price volatility

optimization-pattern.md

Offloading AI Agent Work to Scripts + Cheap Models

A repeatable pattern for reducing the cost of Claude Code skills by 90-95%. Works for any agentic workflow where the frontier model is doing mechanical work that doesn't require frontier-level reasoning.

---

The Problem

When you build a skill (slash command) for Claude Code, the frontier model handles everything: parsing files, constructing shell commands, making API calls, formatting output. Most of this is deterministic work that doesn't need intelligence — you're paying $0.50-1.00 per run for what a Python script could do for free.

Step Classification

Mechanical (script it — free)	Needs some intelligence (Haiku — cheap)	Needs frontier reasoning (keep Opus)
Parsing structured files	Web research / data extraction	Writing personalized content
String formatting / templating	Classification / filtering with judgment	Complex multi-step planning
File I/O, status updates	CRUD operations with conditional logic	Novel problem-solving
URL construction, API calls with known params	Summarization	Ambiguous user intent
Regex extraction

Script Design Checklist

• No external dependencies if possible (stdlib only)
• CLI arguments with argparse — batch number, count, flags
• --dry-run flag — parse and preview without side effects
• JSON output file (/tmp/<skill>-pending.json) for downstream AI steps
• Human-readable stdout — summary tables, skip warnings, confirmation prompts
• Edge case handling — missing fields, already-processed entries, malformed input
• Idempotent updates — safe to re-run if interrupted

Haiku Agent Delegation Principles

• Give complete context — the agent can't ask clarifying questions
• One clear task — search, create, log (not "figure out what to do")
• Structured input/output — JSON in, one-line status reports out
• Parallel, not sequential — launch all agents in one message
• Batch size — 5-7 items per agent

Optimized Skill Structure

Step 1  Run script          (Python — parse, transform, act)        FREE
Step 2  AI follow-up        (Haiku agents in parallel — API work)   ~$0.02
Step 3  Clean up            (delete temp files)                     FREE

Before/After Example: send-outreach

Before (~$0.50-1.00/run)

Opus reads batch markdown file          → parses with regex knowledge
Opus constructs AppleScript per email   → string templating
Opus shows email to user                → formatting
Opus waits for "sent"                   → flow control
Opus uses Edit tool 7 times             → find-and-replace
Opus calls CRM search 7 times          → API calls
Opus calls CRM create 7 times          → API calls
Opus calls CRM log 7 times             → API calls

21 tool calls, all Opus. ~$0.50-1.00.

After (~$0.02-0.05/run)

Opus runs: python3 scripts/send-outreach.py --batch 9 --next 10
  └─ Script parses, opens Mail, confirms, updates statuses    (free)
  └─ Script writes /tmp/outreach-crm-pending.json             (free)

Opus reads JSON, spawns 2 Haiku agents for CRM logging        (~$0.02)
Opus cleans up temp file                                       (free)

3 Opus tool calls + 2 Haiku agents. ~$0.02-0.05.

When NOT to Optimize

• One-off tasks — if you run it once a month, the cost doesn't matter
• Tasks that are mostly creative — writing, strategy, novel debugging
• Tasks where the AI's judgment IS the value — code review, content evaluation
• Prototype phase — get it working first, optimize after the workflow stabilizes

SKILL.md

name	optimize-skills
description	Audit a Claude Code skill for cost optimization. Classifies each step as mechanical/cheap-AI/frontier, proposes script offloading and Haiku delegation. Use when reviewing skill costs, "optimize this skill", "make this cheaper", or "audit skill cost".
argument-hint	skill-name-or-path
allowed-tools	Read, Grep, Glob, Bash(python3 *), Agent

Optimize Skills

Analyze an existing Claude Code skill and produce a concrete plan to reduce its per-run cost by offloading mechanical work to scripts and cheap models.

Reference: references/optimization-pattern.md — full pattern, classification table, script checklist, before/after examples.

---

Step 1 — Identify the target skill

If $ARGUMENTS is provided, locate the skill:

• Check clauffice/dot-claude/skills/$ARGUMENTS/SKILL.md
• Fall back to .claude/skills/$ARGUMENTS/SKILL.md
• If a path is given directly, use it

Read the skill's SKILL.md and any scripts it references. Also read references/optimization-pattern.md.

If no argument is provided, ask:

"Which skill do you want to optimize? Give me the skill name or path."

---

Step 2 — Audit each step (present to user)

For every step in the target skill, classify it using the table from references/optimization-pattern.md:

Present a cost audit table like this:

| Step | What it does | Classification | Current cost | Optimized cost |
|------|-------------|----------------|-------------|----------------|
| 1    | Parse batch file | Mechanical | Opus ($$$) | Python script (free) |
| 2    | Open Mail app | Mechanical | Opus ($$$) | Python script (free) |
| 3    | Log to CRM | Cheap AI | Opus ($$$) | Haiku agents ($0.02) |
| 4    | Write personalized note | Frontier | Opus ($$$) | Opus (keep) |

Include estimated before/after cost per run.

HitL checkpoint: Ask the user:

"Here's my audit. Do you agree with the classifications? Anything I'm mis-categorizing?"

Wait for confirmation before proceeding.

---

Step 3 — Propose optimization plan (3 options)

Based on the confirmed audit, propose 3 optimization strategies with different trade-offs:

Option A: Full optimization — Script everything mechanical, Haiku for cheap-AI steps. Maximum savings, requires writing a Python script.

Option B: Quick wins only — Consolidate the most expensive mechanical steps into a script. Moderate savings, less code to maintain.

Option C: Haiku delegation only — No new scripts; just move non-frontier AI work to Haiku agents. Minimal effort, moderate savings.

For each option, show:

• Estimated cost reduction (percentage and $/run)
• What needs to be built (script, agent instructions, SKILL.md changes)
• Trade-offs (maintenance burden, complexity, flexibility)

HitL checkpoint: Ask the user to pick an option or combine elements.

---

Step 4 — Build the optimization

Based on the chosen option, implement the changes:

If scripting (Options A or B):

1. Write the Python script in the target skill's scripts/ directory
2. Follow the script design checklist from references/optimization-pattern.md
3. Test with --dry-run flag
4. Update SKILL.md to call the script instead of manual steps

If Haiku delegation (all options):

1. Write complete, self-contained agent instructions
2. Specify model: "haiku" and batch size (5-7 items per agent)
3. Update SKILL.md with the delegation pattern

Always:

1. Restructure SKILL.md into the thin-orchestrator pattern:

   Step 1  Run script        (Bash — all mechanical work)
   Step 2  AI follow-up      (Haiku agents in parallel)
   Step 3  Clean up          (delete temp files, report)
   

2. Preserve all existing Rules and HitL moments
3. Add any new rules needed for the script

---

Step 5 — Verify and sync

1. If the script exists, run it with --dry-run to verify it works
2. Run ./clauffice/install.sh to sync changes to .claude/
3. Show a final before/after summary:

BEFORE: [X] Opus tool calls, ~$Y.YY/run
AFTER:  [X] Opus calls + [X] Haiku agents, ~$Y.YY/run
SAVINGS: ~XX%

---

Rules

• Always read the reference first: Load references/optimization-pattern.md before classifying any steps.
• Never skip the audit table: Step 2 must produce a visible classification of every step — don't jump straight to building.
• Always present 3 options: Users need trade-off context to make a good choice. Never propose only one path.
• Don't over-optimize creative work: If a step requires frontier reasoning (writing, planning, novel problem-solving), leave it on Opus. Refer to the "When NOT to Optimize" section.
• Scripts must have --dry-run: Every Python script produced must support --dry-run for safe testing.
• Preserve existing skill behavior: The optimized skill must produce identical outputs to the original. Cost optimization is about efficiency, not changing functionality.
• Always sync after changes: Run ./clauffice/install.sh after modifying any skill files.
• Self-improvement: If the user says "never do X again," update this Rules section immediately. If the user approves the final optimization, save the before/after diff as an example in examples/optimization-[skill-name].md so this skill learns what good looks like.