How to use the Measured Optimization Loop agent skill (ce-optimize)

What the skill makes the agent do

When installed, the agent takes a named system or piece of code with a measurable metric and runs a controlled loop. It sets up a measurement harness, records a baseline, forms hypotheses, tries changes in isolated experiments, and keeps only the changes that score better.

Winning changes are committed to an optimize/<spec-name> git branch with a written log. The run stops at approval gates so you can confirm the plan and spend before experiments run.

• Attributes the cost of a named workload before searching implementations, when that is the cheapest useful first step.
• Scores variants against a benchmark or judge and keeps the winners.
• Writes a disk log of every experiment and its result.

Install the ce-optimize skill

Download the ZIP for this skill from this page. Unzip it into one of two places: ~/.claude/skills/ for your personal use across projects, or .claude/skills/ inside a specific project if only that project should have it.

If you use the Claude apps instead, upload the skill under Settings → Capabilities → Skills.

• Personal install: unzip into ~/.claude/skills/
• Project install: unzip into .claude/skills/ in the project root
• Claude apps: Settings → Capabilities → Skills, then upload

Trigger the skill with a natural request

You do not need a special command. Describe the goal and the metric in plain words. The skill's description says to use it when a working system's metric should move and the winning change is not already known.

You can also pass a path to an optimization spec YAML file, or describe the goal directly. Use a different skill when the job is different: ce-debug for diagnosing a bug or root cause, and ce-work when you already know the change you want.

• Example: "Use ce-optimize to cut the cost of our summarization workload without lowering the judge score."
• Example: "Run the measured optimization loop on the search indexing function and tell me which variants beat the baseline."
• Example with a spec: "Use ce-optimize with optimize-spec.yaml."

Understand the phases and approval gates

The skill runs four phases in order: setup, measurement scaffolding, hypothesis generation, and the optimization loop, followed by wrap-up. Before any experiment runs, the agent must check that files in the mutable and immutable scope have no uncommitted changes, and it must present the plan for your approval.

The run stops automatically on any of eight criteria, including every required target being met, max iterations, max active hours, a spend cap, plateau, a user interrupt, or no runnable hypothesis left.

• Clean-tree gate: no uncommitted changes in scoped files.
• User approval gate: you must explicitly approve before experiments start.
• Dependency pre-approval: new dependencies are listed in one bulk list for your approval.

Know what you need before you start

The repository must be a git checkout, and the files in scope need a clean tree. The host agent must support SKILL.md skills. You also need benchmark or judge scripts defined by your optimization spec.

The example specs use LLM-based judging, which may need model API access and keys. The files do not specify which keys are needed, so check your spec before running.

• git repository with a clean tree for scoped files
• An agent host that supports SKILL.md skills
• Benchmark or judge scripts from your optimization spec
• Model API access and keys if your spec uses LLM judging

Safety notes before you approve a run

This skill runs scripts and uses the network. It creates branches and keep/revert commits on optimize/<spec-name> after you approve. Review the spec, caps, and scope before approving.

Avoid running it with uncapped spend, or on sensitive repositories where automatic commits and experiments are unwanted.

• Set spend caps so the run has limits; the skill states caps are limits, not forecasts.
• Read the spec's mutable and immutable scope before approving.
• Read the Phase 1 gate summary, which discloses capped and uncapped spend.

Tips for better results

Write a clear metric and a benchmark that matches it. The loop can only keep changes that score better on what you measure. Keep the log: it is the record of every experiment, and it is the source of truth for resuming a run.

• Name the metric and how it is measured in your request.
• Keep the working tree clean before starting.
• Use a spec YAML file for repeatable runs.