# Prompt Optimize

> Present the efficiency-versus-effectiveness frontier as labelled variants and let the user pick. TRIGGER WHEN: the user wants to review or optimize a prompt, system message, or agent instructions for clarity/tokens/reliability.

- Skill: `acaprino/prompt-optimize` (Agent Skill)
- Install (CLI): `npx skillmds@latest add acaprino/prompt-optimize`
- Raw SKILL.md: https://api.skillmd.com/api/skills/acaprino/prompt-optimize/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: acaprino (https://skillmd.com/u/acaprino)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/acaprino/prompt-optimize

---


> `<plugin-root>` names the directory that holds this plugin's `.codex-plugin/plugin.json`. Resolve it once from where this file was loaded, then substitute it into every path below that starts with it.
> Arguments: `<prompt text or file path> [--model claude|gpt|gemini|<open-weight model, e.g. gemma-3-12b>] [--optimize-for clarity|tokens|reliability] [--compare]`. Wherever `<arguments>` appears below, substitute the text the user typed after the skill name.

<!-- Generated by the Daodan compiler for codex. Edit the kernel, never this file. -->

# Prompt Optimization

## CRITICAL RULES

1. **Read the prompt first.** If `<arguments>` is a file path, read the file. If inline text, use it directly.
2. **Never modify the user's original prompt** until they approve a variant.
3. **Show the frontier.** Efficiency vs effectiveness is the user's call, not the optimizer's: present variants along that axis with honest cost labels, and let the user pick. `--optimize-for` is the shortcut for users who already know their pole.
4. **Name the model class.** `--model` accepts a vendor name or an open-weight model name; the analysis turns it into a class (frontier reasoning model, hybrid open reasoner, small open-weight instruct model, older non-reasoning model), and every recommendation is made for that class. What enforces an output shape, and whether a reasoning scaffold helps, differ by class more than by vendor.
5. **Never enter plan mode.** Execute immediately.

## Step 1: Analysis and variant frontier (single agent pass)

Spawn the `prompt-engineer` agent via the `Agent` tool, description "Analyze the prompt and generate the variant frontier", with the brief below as its prompt. One agent, one pass: it analyzes first, natively, and returns only the observable artifacts defined in Phase 2. No explicit reasoning scaffold is imposed on it, per its own anti-pattern rules for reasoning models.

```
You are evaluating and optimizing a prompt.

## Input
- Original Prompt: [Insert the prompt from <arguments>]
- Optimization Target: [--optimize-for flag value, or "frontier" when absent]
- Target Model: [--model flag value, default "claude"]

## Phase 1: Analysis (private)
Analyze the prompt thoroughly before writing any output. Extract its behavioral contract
first, then classify the archetype and score on a 1-5 scale only the rubric dimensions that
archetype wants, marking the rest N/A. Identify ambiguities, missing edge cases, structural
weaknesses, and injection vulnerabilities.
Do not include this working in the response: Phase 2 defines the only output you produce.

Model-class check: turn the target model into a class before anything else. Frontier
reasoning model (Claude 4.6 and later, GPT-5.x and GPT-6, Gemini 3, o-series, R1 class):
thinking is native and controlled by an effort setting. Hybrid open reasoner (Qwen3, Gemma 4,
DeepSeek V3.x, gpt-oss): thinking is switched by mode tokens. Small open-weight instruct model
(Gemma 3, Llama 3.x 8B, Phi-4-mini, Mistral Small and anything under roughly 30B served
through Ollama, llama.cpp, vLLM or similar): no native thinking control, weak format
compliance, and a serving stack that may offer constrained decoding. Older non-reasoning
model: the classic patterns apply. Read the model-fit rows of
`<plugin-root>/skills/prompt-engineering/SKILL.md` for the class before scoring model
fit, and `<plugin-root>/skills/prompt-engineering/references/model-guidance.md` when
the target is a named vendor model whose current guidance matters to the rewrite.

Usage-profile check: determine how the prompt is used (one-off, repeated system prompt,
agent loop) and whether prompt caching applies. Which tokens matter follows from this:
output tokens bill at full price and dominate latency; a cached prefix bills 0.1x on reads
(0.025x on Claude Fable 5.1 and Mythos 5.1), so shortening it saves a tenth of what it
appears to, and a cache-breaking edit re-bills it at the write multiplier (1.25x for the
5-minute TTL, 2x for the 1-hour TTL).

Reasoning-pattern check: for a frontier reasoning model, default to NO explicit scaffold:
direct instructions plus precise success criteria, with the effort setting as the lever;
consult the "Reasoning models change the defaults" section of
`<plugin-root>/skills/prompt-engineering/references/reasoning-patterns.md` before
adding any pattern, and never add worked reasoning traces as few-shot exemplars. For a
hybrid open reasoner or a small open reasoner, the same section says what the lever is
(mode tokens, depth self-selection, zero-shot first). Otherwise, decide whether the task
would benefit from a structured reasoning scaffold beyond plain instructions (CoT,
Step-Back, ReAct, Tree-of-Thought, Self-Consistency, Reflexion, Plan-and-Solve,
Least-to-Most, Self-Ask, Skeleton-of-Thought). If yes, read that reference, pick the pattern
that matches the task shape using the selection cheat sheet, and apply it in Phase 2.
For the efficiency variant, always consult that file's token-efficient patterns
(Chain of Draft, Concise CoT, token-budget prompting, Sketch-of-Thought) and its
"Cost-aware selection" section: the efficiency pole is built from those techniques,
not from bare word-deletion.
If the existing prompt already scores 4+ on every dimension, do not add a pattern just
for completeness: record the decision in the analysis instead.

Output-shape check: if anything parses the output (JSON, a schema, an enum, a fixed
template), read `<plugin-root>/skills/prompt-engineering/references/structured-output.md`
and decide the enforcement rung for this model class: format instruction only,
instruction plus validate-and-repair, API structured outputs, or constrained decoding in
the serving stack. On a small open-weight model the instruction alone is never the
enforcement; say which rung the variant assumes and what it costs. Domain validation runs after
schema validation and the system fails closed on either, so the rung a variant names covers the
shape and not the correctness of what the shape holds: the variant says which obligations the
rung covers and which need a domain validator beside it. When the task needs
reasoning as well as a shape, order the prompt to reason first and format last, or split
it into two calls; never ask for reasoning inside the JSON. Where the target is a Claude
4.6 or later model, assistant prefill on the last turn is not available; on an open-weight
model served locally, prefilling the opening brace still is.

Task-family check: if the archetype is extraction or classification (NER, relations,
events, fields from documents, labels from a fixed set), read
`<plugin-root>/skills/prompt-engineering/references/extraction-prompting.md` and
apply the per-task shape it names; extraction is not a reasoning task, so a scaffold added
to it is a defect, and for a fixed schema at volume say plainly that a fine-tuned small
model is the ceiling the prompt cannot reach.

Judge and agent checks: if the archetype is judge / evaluator, read
`<plugin-root>/skills/prompt-engineering/references/judge-prompting.md` and build the
variants on its default shape (one criterion per judge, binary with evidence, a reference when
one exists, a checklist step for open-ended criteria, 0-5 where a scalar is needed); a judge
persona, a judge debate or a 1-10 scale in the original is a defect to report, not a style. If
the archetype is agentic / tool-use, or the text is a tool description, an instruction file, a
skill description or an orchestrator brief, read
`<plugin-root>/skills/prompt-engineering/references/agent-instructions.md` and apply
its anatomy: no few-shot demonstrations in a tool agent's system prompt by default, and long-job
persistence written as verified state rather than a reminder.

Constraint-count check: count the constraints the output must satisfy at once (format, length,
lexical, structural, content). Joint compliance saturates early on every class measured, so
escalate by count: zero to three constraints normal, four to five, add a verifier, and
above five simultaneously verifiable constraints propose a split into stages or a
verify-and-retry step as its own variant and say what it costs; the numbers are in the role's
over-constraining anti-pattern. The band decides only when the optimizer volunteers a split or
a verifier variant as its own option. It is not a reliability criterion and it does not answer
a caller's error budget: when the caller names a joint-success target, or when any counted
constraint is machine-checkable, decide on the four numbers of the output-shape eval
(schema validity, answer accuracy, executable accuracy, the wrong-but-valid rate) rather than
on the count. In a persistent agent rule file the guardrail rules are exempt: fifty guardrails
did not collapse a coding agent's task pass rate, and there the defect to hunt is a conflicting
or unverifiable rule. Output obligations the same file carries, a release-note or
commit-message format for example, count like any other simultaneous constraint.

Language check: the variants stay in the language the original is written in unless a
measurement on the target model and task says otherwise, in which case a translated variant may
enter the frontier, labelled, with the language change reported in the Behavioral changes
section and the measurement named. Absent that measurement, translating an Italian or other
non-English prompt to English is not an optimization, because the effect changes sign by task
and model; a language change the caller asks for is a behavioral change to report.

## Phase 2: Output
Based on your analysis, respond strictly in this format:

### Diagnostic Scorecard (original, predicted)
State the archetype and the model class in one line each, then one row per applicable
dimension. Include the conditional dimensions (output determinism, tool-use correctness,
trust boundaries, evalability, creative latitude) only when this archetype wants them, and
list the ones you marked N/A with a short reason underneath.

| Dimension | Score (1-5) | Key issue |
|-----------|:---:|-------|
| Intent alignment | X | ... |
| Instruction clarity | X | ... |
| Constraint correctness | X | ... |
| Model fit | X | ... |
| Context efficiency | X | ... |
| Robustness | X | ... |

### Variant Frontier
Produce 3 variants by default:
- **A. Max effectiveness**: prioritize quality, robustness, and output control; token cost is secondary.
- **B. Balanced**: resolve the analysis issues at neutral or lower token cost.
- **C. Max efficiency**: minimum tokens at estimated parity, built with a token-efficient
  technique where reasoning is involved.

Collapse to fewer variants only when they would genuinely converge (trivial or already
near-optimal prompts); say that you did and why. Each variant is a fully rewritten,
ready-to-use prompt in its own fenced block. Use XML tags if the target model is Claude
and the prompt mixes instructions, context, or examples; headings suffice for simple prompts.
When the output is parsed, every variant states the enforcement rung it assumes, and the
serving-stack setting or validator that rung needs sits next to the prompt, not inside it.

### Comparison
| Variant | Tokens (est.) | Delta vs original | Technique applied | Enforcement (if parsed) | Predicted effect (unmeasured) | What you give up |

Token estimates: characters/4 on the prompt text, labeled "est.". If a variant also
constrains reasoning or output length, state the expected output-token effect
separately: that is where most of the real savings live.

### Behavioral changes
For each variant, report what changed in behavior rather than in wording: constraints
strengthened or relaxed, behaviors removed or added, interface changes, tool-policy or
reasoning-strategy changes, output-enforcement changes, trust boundaries hardened or
weakened. Print only the lines that are true. If a variant changes nothing behavioral, say
so in one line. Lead with any relaxation or removal instead of burying it under the token
saving.

### Honesty note
Close with these caveats, adapted to the case:
- Label every quality claim predicted, measured, or verified. A score this pass assigned is
  predicted by definition, including the scorecard above.
- Predicted scores and parity are single-pass estimates by the same model that wrote
  the variants, not measurements; small formatting changes alone are known to swing
  task accuracy, so treat the deltas as hypotheses.
- To actually verify "fewer tokens, same results": run a paired eval (identical inputs
  per variant, pre-declared non-inferiority margin). The prompt-engineer prompt-evals
  guidance covers the method; promptfoo fits in CI.
- If the output is parsed, say that schema compliance on this model class is predicted
  until measured on a hundred real inputs, and name the parse-failure rate as the first
  number to collect, with the wrong-but-valid rate collected beside it: an obligation the
  schema cannot express is caught by a domain validator, not by the schema.
- If the prompt is a cached system prompt, repeat the cache-economics warning from
  the analysis.
- If the prompt is a judge, say that agreement with humans is predicted until Cohen's kappa
  is measured on the caller's own labels, one kappa per criterion.
```

## Step 2: The user picks the pole

After the agent returns, present its output and ask the user which variant to adopt, via AskUserQuestion: one option per variant, each label naming the pole and each description carrying the token estimate and the main trade-off; put your recommended variant first with "(Recommended)". Skip the question and deliver the matching pole directly when:

- `--optimize-for` was passed (clarity -> A, reliability -> A with constraints and examples emphasized, tokens -> C), or
- the user already stated their target in the request.

`--compare` forces the full frontier presentation even when a shortcut applies.

## Step 3: Deliver

Deliver the chosen variant ready to copy, with its token estimate, the enforcement rung and its setting when the output is parsed, and 1-2 test inputs the user can validate it with. Apply it to the source file only if the user asks; the original is never modified without approval.

## Quick Examples

- `/prompt-optimize "Summarize this document"`: full frontier, user picks the pole
- `/prompt-optimize prompts/system.md --optimize-for tokens`: straight to the efficiency pole
- `/prompt-optimize prompts/agent.md --model gpt --compare`: optimize for GPT, always show the full frontier
- `/prompt-optimize prompts/extract.md --model gemma-3-12b`: small open-weight target: the variants name their enforcement rung and the extraction shape they use
- `/prompt-optimize prompts/judge.md --model gpt`: judge archetype: the variants decompose the rubric, drop the persona, and name the agreement check