zirkel-optimize-instruction
Optimizes the exact wording of an instruction/prompt for a recurring task using APE — generates one candidate per framing, scores them against real test cases, and critiques the winner. Use when a prompt will be reused and its wording matters: "tune this prompt", "find the best wording for this instruction", "optimize this system prompt", "which phrasing works best", with representative test cases available. Not for one-off prompts with no test cases.
- License 许可
- MIT
- 最近更新
- 2026-11-02
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- zirkel-optimize-instruction
- description
- Optimizes the exact wording of an instruction/prompt for a recurring task using APE — generates one candidate per framing, scores them against real test cases, and critiques the winner. Use when a prompt will be reused and its wording matters: "tune this prompt", "find the best wording for this instruction", "optimize this system prompt", "which phrasing works best", with representative test cases available. Not for one-off prompts with no test cases.
03 SKILL.md 正文
zirkel-optimize-instruction
Generate 5 framings, score on fixed test cases, select, critique the winner. The guard enforces the candidate count, the framing set, the tie-break, and the checklist size in code.
The guard is python3 -B "${CLAUDE_PLUGIN_ROOT}/scripts/zirkel.py", typed in full in each command below.
Preferred path: the workflow
When the Workflow tool is available, run
${CLAUDE_PLUGIN_ROOT}/workflows/optimize-instruction.js
(args { taskDescription, testCases:[{input, expectedOutcome}] }). It dispatches
one instruction-candidate agent per framing in parallel, scores each against the
exact test cases, selects with the framing tie-break, and critiques the winner.
Inputs
- a recurring task description
- 3-5 representative real test cases
{input, expectedOutcome}. Source them from real prior inputs first; only construct if none exist. MUST NOT fabricate test cases or adjust expected outcomes.
Process
- Generate exactly 5 candidates — one per APE framing: rule-based, example-based, definition-based, question-based, chain-of-thought-based. Each commits fully to its framing (no blending).
- Score each candidate against the exact provided test cases (pass count).
- Select the highest score. Validate the count, framings, and tie-break:
echo '{"candidates":[
{"framing":"rule-based","score":4},
{"framing":"example-based","score":4},
{"framing":"definition-based","score":3},
{"framing":"question-based","score":2},
{"framing":"chain-of-thought-based","score":4}
]}' | python3 -B "${CLAUDE_PLUGIN_ROOT}/scripts/zirkel.py" candidates -
The guard requires exactly 5 candidates covering all 5 framings and breaks ties
by framing precedence: rule → example → definition → question → CoT. Use its
winner. If the guard rejects the set (wrong count, missing/duplicate framing,
or malformed JSON), regenerate only the missing/duplicate framing(s) and
re-validate. If the guard still rejects after 2 attempts, stop and report which
framing(s) could not be produced rather than looping indefinitely.
- Critique the winner only with meta-prompting's 4-item checklist, revising only failing items:
echo '{"checklist":[
{"criterion":"rules unambiguous","pass":true},
{"criterion":"handles out-of-scope","pass":false},
{"criterion":"format rules compatible","pass":true},
{"criterion":"no two-way readings","pass":true}
]}' | python3 -B "${CLAUDE_PLUGIN_ROOT}/scripts/zirkel.py" critique -
Output
- candidates table: framing, score (n/total)
- winner + why
- critique checklist: pass/fail per criterion
- the final prompt, ready to use
Example (task: "triage inbound support tickets by urgency"):
| framing | score |
|----------------------|-------|
| rule-based | 4/5 |
| example-based | 4/5 |
| definition-based | 3/5 |
| question-based | 2/5 |
| chain-of-thought-based | 4/5 |
Winner: rule-based (tie with example-based and chain-of-thought-based at 4/5;
framing precedence picks rule-based)
Critique:
- [x] rules unambiguous
- [ ] handles out-of-scope -> revised: added an explicit "no urgency signal
found" fallback clause
- [x] format rules compatible
- [x] no two-way readings
Final prompt:
"""
Classify this support ticket's urgency as high, medium, or low.
- high: mentions data loss, outage, or a billing failure blocking checkout
- medium: a broken feature with a workaround, or a repeat complaint
- low: a question, a feature request, or cosmetic issue
- if no urgency signal is present, classify as low and note "no signal found"
Ticket: {ticket_text}
"""
04 同仓库更多 Skills
toy-check
A skill that checks things in the repository and reports what it finds.
demo-check
Reports which generated files changed since the last generation run. Use when the user asks what drifted. Read-only; never edits a file.
demo-check
Reports which generated files changed since the last generation run. Use when the user asks what drifted. Read-only; never edits a file.
demo-check
Reports which generated files changed since the last generation run. Use when the user asks what drifted. Read-only; never edits a file.
demo-check
Reports which generated files changed since the last generation run. Use when the user asks what drifted. Read-only; never edits a file.
zirkel-verify-assumptions
Checks exactly ONE named assumption against real evidence in at most 3 steps and reports one outcome: confidence raised (>=90), reading changed, or still unresolved. Use to resolve a single load-bearing uncertainty — typically a blocking entry surfaced by zirkel-clarify-scope: "verify this one assumption", "is it actually true that X", "check this before we rely on it". For multiple uncertainties, invoke once per uncertainty — the step budget is never shared.