⏳ This skill is pending AI review.

Scores will appear once the review pipeline completes.

v3.0.1

simmer

2389-research@2389-research⭐ 16 stars· last commit 13d ago· 1 open issues

>

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.

—/10

// RATINGS

⭐GitHub Stars
⭐⭐ 16 on GitHubGitHub ↗

Growing

🟢ProSkills Score
—
📍

Not yet listed on ClawHub or SkillsMP

// 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

SituationUseWhy
You have an artifact and want it bettersimmerIterative refinement against criteria
You want parallel code implementations competingcookoffParallel generation + fixed criteria + pick winner
You don't know what you want yetomakase-offParallel 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 typeSuggested criteria
Document / specclarity, completeness, actionability
Creative writingnarrative tension, specificity, voice consistency
Email / commsvalue prop clarity, tone match, call to action strength
Prompt / instructionsinstruction precision, output predictability, edge case coverage
API designcontract completeness, developer ergonomics, consistency
Pipeline / workflowcoverage, efficiency, noise
Configuration / infracorrectness, resource efficiency, maintainability

Evaluation Modes

ModeWhen to use
Judge-only (default)Text artifacts — judge scores against criteria
RunnableCode/pipelines — judge interprets script output
HybridBoth — 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

FeatureWhen you need it
Workspace targetsRefining a multi-file directory — iterations tracked as git commits so you can diff any two rounds
Runnable evaluatorsYour artifact has a test script — point simmer at it (python evaluate.py) and the judge interprets output
Background constraintsThe generator needs to know what's available (models, budget, latency targets) to make realistic choices
Output contractsValid output has a defined shape (e.g., JSON schema) — violations score 1/10, forcing format fixes first
Validation commandsA cheap pre-check (./validate.sh) catches broken pipelines in seconds before the full evaluator runs
Search space trackingExplicit 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 to
  • README.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

// REPO STATS

16 stars
1 open issues
Last commit: 13d ago