⏳ This skill is pending AI review.
Scores will appear once the review pipeline completes.
simmer
>
Choose how to use this skill
You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.
1. Native installer
This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.
Do not guess an installer command or replace an existing version without reviewing the diff.
2. Complete package recommended
Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.
No complete ProSkills package is published for this listing yet.3. Prompt-only
Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.
Need only the instruction file?
Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.
No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.
// RATINGS
// README
Simmer
You wrote a prompt. It works. But is it good? Simmer runs your artifact through multiple rounds of criteria-driven refinement — each round, a panel of judges reads your code, understands the problem, and proposes specific improvements.
Read the story behind Simmer →
Iterative artifact refinement — take any artifact or workspace and hone it over multiple rounds using criteria-driven feedback.
Installation
/plugin marketplace add 2389-research/claude-plugins
/plugin install simmer@2389-research
What This Plugin Provides
One skill (simmer) with five subskills that run the refinement loop:
- Setup — identify the artifact (file or workspace), elicit 2-3 quality criteria, determine evaluation method
- Generator — produce an improved version based on the judge's ASI (Actionable Side Information — the single highest-leverage fix)
- Judge — score the candidate 1-10 per criterion, produce the ASI
- Judge Board — panel of perspective-diverse judges; drop-in replacement for Judge when JUDGE_MODE is board
- Reflect — record the trajectory, track the best candidate across iterations
Trigger Phrases
Say any of these to start a simmer loop:
"simmer this", "refine this", "hone this", "iterate on this", "make this better", "improve this over a few rounds", "polish this", "tighten this up", "optimize this pipeline", "find the best model for this task", "tune this configuration"
Any request to iteratively improve an artifact triggers simmer.
When to Use Simmer vs. Cookoff vs. Omakase-Off
| Situation | Use | Why |
|---|---|---|
| You have an artifact and want it better | simmer | Iterative refinement against criteria |
| You want parallel code implementations competing | cookoff | Parallel generation + fixed criteria + pick winner |
| You don't know what you want yet | omakase-off | Parallel designs + react + discover preference |
Rule of thumb: Simmer = serial iteration. Cookoff/omakase-off = parallel exploration.
Quick Example: Single File
User: "Simmer this" [pastes a pitch email]
Claude: I'm using the simmer skill to set up iterative refinement.
What does "better" mean for this? I'd suggest:
1. Value prop clarity
2. Tone match
3. Call to action strength
User: "Those work"
[Iteration 0: Judge scores seed — 4.0/10]
[Iteration 1: Generator fixes value prop → 5.3/10]
[Iteration 2: Generator fixes CTA → 6.3/10]
[Iteration 3: Generator fixes tone → 7.3/10]
Trajectory:
| Iter | Value Prop | Tone | CTA | Composite | Key Change |
|------|-----------|------|-----|-----------|------------|
| 0 | 4 | 5 | 3 | 4.0 | seed |
| 1 | 7 | 5 | 4 | 5.3 | specific problem statement |
| 2 | 7 | 6 | 6 | 6.3 | low-friction CTA |
| 3 | 7 | 7 | 8 | 7.3 | peer-sharing tone |
Best candidate: iteration 3 (7.3/10)
3 iterations complete. Run 3 more?
Quick Example: Workspace with Evaluator
User: "Simmer this pipeline — find the best setup for this task"
Claude inspects the workspace, finds evaluate.sh and config.json,
and proposes criteria + evaluation method:
Evaluator: ./evaluate.sh
Criteria: accuracy, cost efficiency, latency
Search space: models, prompt text, pipeline topology
User: "Looks good, coverage is the priority. 5 iterations."
[Iteration 0: Run evaluator on seed, judge scores — 3.7/10]
[Iteration 1: Generator swaps to cheaper model → 5.3/10]
[Iteration 2: Generator splits into 2-step chain → 7.0/10]
[Iteration 3: Generator adds few-shot examples → 7.7/10]
...
Best candidate: iteration 4 (8.1/10)
Works On Anything
| Artifact type | Suggested criteria |
|---|---|
| Document / spec | clarity, completeness, actionability |
| Creative writing | narrative tension, specificity, voice consistency |
| Email / comms | value prop clarity, tone match, call to action strength |
| Prompt / instructions | instruction precision, output predictability, edge case coverage |
| API design | contract completeness, developer ergonomics, consistency |
| Pipeline / workflow | coverage, efficiency, noise |
| Configuration / infra | correctness, resource efficiency, maintainability |
Evaluation Modes
| Mode | When to use |
|---|---|
| Judge-only (default) | Text artifacts — judge scores against criteria |
| Runnable | Code/pipelines — judge interprets script output |
| Hybrid | Both — run script AND judge results against criteria |
No format contract on evaluator output. The judge reads whatever your script produces — test results, metrics, error logs, anything.
Judge Board
Simmer auto-selects between a single judge and a multi-judge board based on complexity:
- Simple (short email, tweet, ≤2 criteria) → single judge, fast
- Complex (3 criteria, long artifact, code, pipelines) → judge board with deliberation
The board constructs three judges tailored to your specific problem — not from a fixed menu, but by reading your artifact, criteria, and constraints and designing judges with diverse perspectives. An extraction prompt gets different judges than a DND adventure hook.
Judges investigate before scoring — they read the evaluator script, ground truth, prior candidates, and config files to understand the problem deeply. A judge who reads the evaluator discovers scoring mechanics on iteration 0 instead of learning them through 3 iterations of trial and error.
If a single-judge run hits a plateau (3 iterations without improvement), simmer offers to upgrade to the board mid-run with 2 extra iterations.
Defaults and Safety
Default iteration count: 3 rounds per batch. After each batch, simmer asks whether to continue. You can request a specific count ("simmer this for 10 rounds") or stop early at any prompt.
Regression safety: The reflect subskill tracks the best candidate seen so far. If a new iteration scores lower than the current best, the best-so-far is preserved — the loop never loses progress. At the end, result.md always contains the highest-scoring candidate, not just the latest one.
Advanced Features
| Feature | When you need it |
|---|---|
| Workspace targets | Refining a multi-file directory — iterations tracked as git commits so you can diff any two rounds |
| Runnable evaluators | Your artifact has a test script — point simmer at it (python evaluate.py) and the judge interprets output |
| Background constraints | The generator needs to know what's available (models, budget, latency targets) to make realistic choices |
| Output contracts | Valid output has a defined shape (e.g., JSON schema) — violations score 1/10, forcing format fixes first |
| Validation commands | A cheap pre-check (./validate.sh) catches broken pipelines in seconds before the full evaluator runs |
| Search space tracking | Explicit bounds on what to explore — reflect tracks tried vs. untried regions so the judge steers toward gaps |
See the v2 design spec for full details on each feature.
Output Directory Structure
Single-file mode (default output dir: docs/simmer):
docs/simmer/
iteration-0-candidate.md # Seed (original artifact)
iteration-1-candidate.md # Each improved candidate
iteration-2-candidate.md
iteration-3-candidate.md
trajectory.md # Running score table
result.md # Final best candidate (highest score, not necessarily latest)
Workspace mode:
./pipeline/ # Target directory (modified in place)
[project files] # Tracked via git commits per iteration
docs/simmer/ # Tracking files (separate from workspace)
trajectory.md # Running score table
Workspace iterations are tracked as git commits rather than separate files.
How It Work
// HOW IT'S BUILT
// FILES
2 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.
skills/simmer/SKILL.md8.4 KBupstream ↗
--- name: simmer description: > Use when user says "simmer this", "refine this", "hone this", "iterate on this", or asks to improve a specific artifact over multiple rounds. Runs an iterative refinement loop with investigation-first judges that read the code, understand the problem, and propose evidence-based improvements. Auto-selects single judge or multi-judge board based on complexity. Works on any artifact type: documents, prompts, specs, emails, creative writing, API designs, pipelines, codebases. Supports multi-file workspace targets, runnable evaluators, and open-ended optimization (model selection, pipeline topology, prompt tuning). --- # Simmer Iterative refinement loop — take an artifact (single file or workspace) and hone it repeatedly against user-defined criteria until it's as good as it can get. **Related skills (test-kitchen family):** - `test-kitchen:omakase-off` — don't know what you want → parallel designs → react → pick - `test-kitchen:cookoff` — know what you want, it's code → parallel implementations → fixed criteria → steal the best - `simmer` — know what you want, it's anything → user-defined criteria → iterate until good ## Flow ``` "Simmer this" / "Refine this" / "Optimize this pipeline" ↓ ┌─────────────────────────────────────┐ │ SETUP (identify + criteria) │ │ Load simmer-setup subskill │ │ │ │ Output: artifact, rubric, N iters, │ │ evaluator (optional), │ │ background (optional) │ └─────────────────────────────────────┘ ↓ ┌─────────────────────────────────────┐ │ LOOP (default 3 iterations) │ │ │ │ Each iteration: │ │ 1. Dispatch generator subagent │ │ 2. Run evaluator (if present) │ │ 3. Dispatch judge subagent │ │ 4. Load reflect subskill │ │ │ │ Generator gets: candidate + ASI │ │ + background │ │ Judge gets: candidate + rubric │ │ + evaluator output (if any) │ │ Reflect gets: full score history │ └─────────────────────────────────────┘ ↓ ┌─────────────────────────────────────┐ │ OUTPUT │ │ Best candidate → result file │ │ Score trajectory displayed │ └─────────────────────────────────────┘ ``` ## When to Use Trigger when user wants iterative refinement of any kind: - "Simmer this", "refine this", "hone this", "iterate on this" - "Make this better", "improve this over a few rounds" - "Polish this", "tighten this up" - "Optimize this pipeline", "find the best model for this task" - "Tune this configuration", "improve these prompts against this test suite" - Any request to iteratively improve an artifact or workspace **Judge mode is auto-selected by setup** based on problem complexity: | Condition | JUDGE_MODE | |-----------|-----------| | text/creative, ≤2 criteria, short artifact (email, tweet, tagline) | `single` | | text/creative, 3 criteria or long/complex artifact | `board` | | code/testable (any) | `board` | | pipeline/engineering (any) | `board` | | User says "with a single judge" | `single` (override) | | User says "with a judge board" or "with a panel" | `board` (override) | **Plateau upgrade:** If the loop started with a single judge and detects a plateau (3 iterations without improvement), offer: "Scores have plateaued. Switch to judge board for deeper diagnosis?" If the user accepts, switch to `JUDGE_MODE: board` for remaining iterations. **Not simmer:** If the artifact is code and the user wants parallel implementations, use cookoff instead. ## Orchestration **Announce:** "I'm using the simmer skill to set up iterative refinement." **Track progress** (TodoWrite if available, otherwise inline): 1. Setup — identify artifact, elicit criteria, determine evaluation method 2. Refinement loop (N iterations) 3. Output best version with score trajectory ### Phase 1: Setup **Invoke `simmer:simmer-setup`.** Do not attempt to identify the artifact or ask about criteria yourself — that is the setup subskill's job. **Shortcut:** If the user (or calling system) has already provided artifact, criteria (each with at least one sentence describing what a high score looks like), iteration count, mode, and optionally evaluator/background, skip the setup subskill entirely. Construct the setup brief directly and proceed to Phase 2. Setup returns a brief: ``` ARTIFACT: [content, file path, or directory path] ARTIFACT_TYPE: [single-file | workspace] CRITERIA: - [criterion 1]: [what better looks like] - [criterion 2]: [what better looks like] - [criterion 3]: [what better looks like] PRIMARY: [criterion name — omit if equally weighted] EVALUATOR: [command to run — omit for judge-only mode] BACKGROUND: [constraints, available resources, domain knowledge — omit if not needed] OUTPUT_CONTRACT: [valid output format description — omit for text/creative] VALIDATION_COMMAND: [quick check command — omit if no cheap validation exists] SEARCH_SPACE: [what's in scope to explore — omit if unconstrained] JUDGE_MODE: [single | board — auto-selected by setup based on complexity. User can override] JUDGE_PANEL: [optional custom judge definitions — omit to use defaults for problem class] ITERATIONS: [N] MODE: [seedless | from-file | from-paste | from-workspace] OUTPUT_DIR: [path, default: docs/simmer] ``` ### Phase 2: Refinement Loop **For single-file mode:** ```bash mkdir -p {OUTPUT_DIR} ``` **For workspace mode:** ```bash # Create initial commit to snapshot the seed state cd {ARTIFACT} git add -A && git commit -m "simmer: iteration 0 — seed state" ``` **Iteration counting:** "N iterations" means N generate-judge-reflect cycles AFTER the initial seed judgment. The seed judgment is iteration 0 (not counted toward N). So `ITERATIONS: 3` means: - Iteration 0: Judge the seed (no generator) - Iteration 1: Generate → Judge → Reflect - Iteration 2: Generate → Judge → Reflect - Iteration 3: Generate → Judge → Reflect - Total: 3 generation passes + 1 seed judgment = 4 judge rounds For seedless mode: iteration 1 generates the initial candidate AND judges it. `ITERATIONS: 3` means 3 generation passes total. **Iteration 0 (seed):** *Single-file mode:* - Write the seed artifact to `{OUTPUT_DIR}/iteration-0-candidate.md` - If seedless: dispatch generator subagent to produce initial candidate from description + criteria, then judge it - If from-file or from-paste: the seed IS the starting artifact — judge it directly (no generator) *Workspace mode:* - The seed is the current state of the workspace directory - If from-workspace: judge the current state directly (no generator) - If seedless: dispatch generator to scaffold the initial workspace, then judge it **Each iteration:** **Step 1: Generator (subagent)** Invoke `simmer:simmer-generator` as a subagent. *Single-file subagent prompt:* ``` You are the generator in a simmer refinement loop. Invoke the skill: simmer:simmer-generator ITERATION: [N] ARTIFACT_TYPE: single-file CRITERIA: [rubric from setup] CURRENT CANDIDATE: [full text of current best candidate] JUDGE FEEDBACK (ASI from previous round): [ASI text, or "First iteration — generate initial candidate" if seedless iteration 1] Write your improved candidate to: {OUTPUT_DIR}/iteration-[N]-candidate.md (or appropriate extension matching artifact type) Report: what specifically changed and why (2-3 sentences). ``` *Workspace subagent prompt:* ``` You are the generator in a simmer refinement loop. Invoke the skill: simmer:simmer-generator ITERATION: [N] ARTIFACT_TYPE: workspace WORKSPACE: [directory path] CRITERIA: [rubric from setup] BACKGROUND: [constraints, available resources, domain knowledge from setup] OUTPUT_CONTRACT: [valid output format — omit if not specified in setup] VALIDATION_COMMAND: [quick check command — omit if not specified in setup] SEARCH_SPACE: [what's in scope toREADME.mdupstream ↗
Contents are not inlined in the catalog. Open the upstream file.
Plain-text copy, no login: /skill-bundles/2389-research-simmer-skills-simmer.md