# Prompt Optimizer > Rigorous mode prompt optimizer — audits a polished prompt, decides output architecture (single-turn vs. chained multi-stage), and rewrites it to elicit state-of-the-art output from Claude. Triages every input into OUT OF PURVIEW / BORDERLINE / IN PURVIEW; rigorous optimization (architecture decision, 9-dim diagnostic, archetype detection, capability activation) applies ONLY to IN PURVIEW. When ch… - **Type:** Skill - **Install:** `agentstack add skill-viktor-milev-claude-skills-prompt-optimizer` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [viktor-milev](https://agentstack.voostack.com/s/viktor-milev) - **Installs:** 0 - **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [viktor-milev](https://github.com/viktor-milev) - **Source:** https://github.com/viktor-milev/claude-skills/tree/main/prompt-optimizer ## Install ```sh agentstack add skill-viktor-milev-claude-skills-prompt-optimizer ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # Prompt Optimizer (State-of-the-Art Edition) ## CHANGELOG **v4.2 — Jun 2026.** Recalibration for Claude Opus 4.8 (released May 28 2026), plus a new RUN SETTINGS recommendation. No structural changes to the workflow; no architecture decision module changes; no lockstep coordination with prompt-architect required. - **Capability-activation note recalibrated for Opus 4.8 (Step 5).** The "4.7 calibration note" is now the "4.7–4.8 calibration note." 4.8's documented behavior changes — more reliable reasoning-effort calibration at each effort level, better tool triggering (fewer skipped tool calls the task required), improved honesty/anti-confabulation, more consistent instruction-following — narrow where three techniques earn their place, with one technique held deliberately steady: - *Reasoning activation* — split "more thinking" (now native via adaptive thinking + the effort dial) from "specific reasoning structure" (forced alternatives, self-critique, chain-of-verification — still the prompt's job). Generic "think step by step" earns its place even more rarely on 4.8. - *Anti-sycophancy* — held steady, NOT softened further. 4.8's honesty gains concern the model's claims about its own work, not its willingness to push back on the user's framing; on the reflexive-validation axis 4.8 did not improve. Value undiminished. - *Research activation* — narrowed: 4.8's better tool triggering means the scaffold earns its place only where phrasing is ambiguous enough that the model might still not search. - *Epistemic calibration* — smaller marginal value (the model flags uncertainty more natively); the v3 source-material precondition for confidence tags stands unchanged. - *Scope literalism* — reinforced on 4.8 (more obedient / more consistent instruction-following); content unchanged. - **RUN SETTINGS recommendation added (new output element; Step 9.5).** The optimizer now returns two operational recommendations alongside the optimized prompt: EFFORT (the 4.8 chat-app dial — low / high / xhigh / max) and RESEARCH (web search / Research mode on or off). Derived from state the workflow already computes (triage band + architecture verdict + reasoning-depth diagnostic) — no new analytical step. Thinking is folded into EFFORT by design: on 4.8, thinking depth *is* the effort dial (adaptive thinking is automatic; manual thinking budgets are unsupported), so a separate "thinking" recommendation would be a category error. RUN SETTINGS is operational metadata only — never inside the optimized prompt code block, present on IN PURVIEW (and a single optional web-search line on BORDERLINE), never on OUT OF PURVIEW. Addresses a real silent-failure mode: an in-prompt "search for X" instruction fails quietly when web search is toggled off. **v4.1 — May 2026.** Three surgical calibration additions grounded in the Anthropic official prompting guide (and, where convergent, Ruben Hassid's chat-app prompt optimizer). No structural changes; no architecture decision changes; no lockstep coordination with prompt-architect required. - **`` elevated to first-class structural tool (Step 6 Branch A).** v4's structural tools list included ``, context-first ordering, ``, motivated constraints, ``, ``, ``, domain-specific tags, and `[bracketed placeholders]` — but omitted `` as a first-class tool, despite Anthropic identifying examples as "one of the most reliable ways to steer Claude's output format, tone, and structure." Calibration guidance specifies when to add (Creative archetype voice anchoring, Iterative refinement consistency, format-preference cases) and when to skip (generic tasks, no signaled format preference). Addresses an underplayed lever surfaced in the v3 A/B test complex_creative loss (Howard Marks voice diluted by structural scaffolding). - **Quote-grounding pattern for long-document tasks (Step 6 Branch A).** Added an explicit structural tool: for prompts loading ≥3K tokens of source material, instruct Claude to extract relevant passages into `` tags before reasoning. Per Anthropic's long-context guidance, materially reduces drift and hallucination on document-grounded analytical tasks. Directly relevant to multi-document research synthesis (annual reports, long transcripts, and dense source material that must be analyzed without drift). - **Scope literalism added to 4.7 calibration note (Step 5).** v4's calibration note covered reasoning, anti-sycophancy, and research activation but omitted 4.7's literal-reading shift. Step 5.5 signal preservation handles most cases operationally; the calibration note now surfaces the principle during capability selection — particularly for keystone prompts where session-wide norms must apply consistently. Item considered and rejected for v4.1: tag-framing preference rule (prefer `` over `` when equally precise). Scored 40% against a ~60% threshold — operates at wrong altitude (tag name vs. content framing), already covered by the "tags earn their place" principle, no evidence basis. Logged for revisit only if a future A/B test surfaces tag-framing as a failure mode. **v4 — May 2026.** Introduces architecture decision as a first-class step. The v3 skill had a structural alignment problem: it optimized a proxy (the quality of a single-turn prompt) rather than the actual target (state-of-the-art Claude output on the user's task). For complex work, those objectives diverge — forcing a single-turn structure compresses output that would have been materially better delivered as a chain. v4 fixes this by promoting the architecture decision from an implicit downstream constraint (the v3 feasibility pass could only flag overflow) to an explicit upstream decision (new Step 3, between Archetype Detection and Diagnostic). The decision drives branched behavior in Steps 4–7 and produces one of two distinct output formats: - **Single-turn template** — the v3 output, refined. Includes a new SINGLE-TURN (CEILING) sub-band that makes the "fits but at the edge" cases visible to the user (previously silent). - **Chain template** (new) — produces a README/setup guide, a Project orchestrator (custom instructions), and per-stage prompts as separate deliverables, mirroring the validated Project-orchestrated workflow pattern. The architecture decision is governed by seven named signals (four primary, three amplifying) with explicit guards against over-recommending chain. The verdict, signals fired, and Project-vs-flat sub-decision are always named — the recommendation is falsifiable, not aesthetic. **v3 — Apr 2026.** Fixes three real bugs surfaced by a 20-prompt A/B test: - **Signal preservation** (new Step 5.5, formerly 4.5). The single largest skill-level failure mode in v2 was *structural overwrite of raw-prompt signals*. The optimizer wrapped unfilled placeholders (`[CV]`, `[JD]`) as if material were present; converted ambiguous hints ("I have a draft to share") into locked workflows; and dropped explicit format directives ("both analyses side by side") during restructuring. Step 5.5 enumerates every signal in the raw prompt before any restructuring and requires each to be preserved or explicitly overridden with rationale. - **Feasibility pass** (revised Step 7, formerly 6). The old step asked only "what could we add?" It never asked "what would crash the turn if we added it?" The revised step runs explicit checks — output budget, context-dependency honesty, user-format preservation, input-presence — and is allowed to *cut* the optimization rather than only extend it. - **Calibrated capability activation** (Section 5, formerly 4). `[Confirmed]/[Inferred]` confidence tags now require explicit source material in the prompt. `` now explicitly degrades to "state what you don't know" when no search tool is present. --- Optimize prompts to reach the ceiling of what Claude can produce on a given task — but ONLY when the task warrants it. Rigorous optimization on a prompt that doesn't need it produces worse output, not better. The skill's first job is to decide whether to optimize at all. ## Core philosophy **Stop optimizing prompts. Start optimizing the Claude session that the prompt initiates.** A prompt is not a request. It is the keystone of an interaction. The job of optimization is not to make the prompt well-formed — it is to make Claude perform at the top of its distribution on the task the prompt describes. But this logic only applies when the task has a ceiling worth reaching. A PTO email does not. Forcing XML scaffolding, capability activation, and 6-section diagnostic outputs onto casual communication tasks makes the downstream output *worse*, not better — it bloats the prompt, buries the actual ask, and ships Claude a bureaucratic commission when the user wanted a 3-sentence note. This is a SEVERE failure mode (see Failure Modes section). The skill therefore operates in three triage bands, classified before any optimization work begins. A second equally important philosophy (v3): **preserve the user's signals; restructure only what the user didn't specify.** The raw prompt is the user's compressed intent. Every format directive, placeholder, ambiguity marker, and workflow hint is a signal. Optimization that overwrites those signals produces a prompt Claude follows perfectly — to the wrong target. A third equally important philosophy (v4): **choose the architecture before choosing the structure.** Single-turn is the default delivery vehicle, but it is not the only one. When the work is genuinely complex — multi-deliverable, sequentially dependent, checkpoint-bearing, or compression-costly — chain architecture produces materially better output than any single-turn prompt could. The skill's job is to make that architecture call explicitly, name the signals that justified it, and produce a chain deliverable when chain is the right answer. Defaulting silently to single-turn on prompts that deserved a chain is an alignment failure between the skill's stated mission (state-of-the-art output) and its mechanical behavior (single-turn polish). --- ## Step 0 — TRIAGE (mandatory; runs before every other step) Classify the input into one of three bands using the four tests below. State the verdict explicitly in one line before proceeding. The user may override (e.g., "treat as IN PURVIEW") if they disagree. ### The four triage tests Run all four. Score each with OUT / BORDERLINE / IN leaning. **Test 1 — Artifact type.** What is the downstream output? - OUT leaning: email, text message, Slack message, tweet/post, caption, subject line, short note, simple list, simple lookup, simple formatting task, casual personal communication - BORDERLINE leaning: article, blog post, cold outreach, summary of provided material, standard business document (meeting agenda, status update), recipe / single-workout plan, single-topic explainer - IN leaning: report, memo, analysis, evaluation, research synthesis, strategic document, session keystone, multi-constraint creative work, agentic task spec, decision framework, published artifact intended for external stakeholders **Test 2 — Raw prompt word count.** - 100 words: IN leaning (content usually dominates, but size correlates) **Test 3 — Analytical load.** Does the task require reasoning, decomposition, research, evaluation, or synthesis? - None (pure generation, formatting, lookup): OUT leaning - Light (single narrow judgment, e.g., "make this tone warmer"): BORDERLINE leaning - Present (multi-step reasoning, tradeoff analysis, research integration, evaluation against criteria): IN leaning **Test 4 — Consequentiality.** What is the downstream cost of a mediocre output? - OUT leaning: Low-consequence communication — casual content, familiar or non-specific audience, and a mediocre version still accomplishes the task (PTO email to known boss, tweet about your day, text to a friend, routine Slack update) - BORDERLINE leaning: Externally-facing or reputationally-significant artifact — first-impression content, cold outreach, professional networking, short business documents where tone and specificity materially affect whether the artifact achieves its purpose. The user sends it once, but getting it wrong has real professional cost. - IN leaning: Session keystone, published document, work product shared with stakeholders, or anything that will be iterated on ### Verdict rules - **3 or 4 OUT leanings → OUT OF PURVIEW.** Short-circuit. Do not run the full workflow. - **3 or 4 IN leanings → IN PURVIEW.** Run the full workflow below. - **Mixed or 3+ BORDERLINE leanings → BORDERLINE.** Run abbreviated workflow. - **Override rule:** if analytical load is PRESENT (a real reasoning task), promote at least one band up regardless of other scores. "Should I take this job?" at 8 words is IN PURVIEW, not OUT. - **Override rule:** if the user explicitly flags the prompt as a keystone or high-stakes ("this kicks off my session", "this goes to my CIO", "this is the prompt for my automated pipeline"), promote to IN PURVIEW. ### Output the verdict in one line Before any further work, state: > **TRIAGE: [OUT OF PURVIEW | BORDERLINE | IN PURVIEW]** — [one-sentence rationale citing the two or three tests that drove the call] If the user disagrees, they can override in their next message. Proceed to the band-appropriate output path below. --- ## Band-specific output paths ### Path A — OUT OF PURVIEW output format Return exactly this, and nothing else: > **TRIAGE: OUT OF PURVIEW** — [rationale] > > **Verdict:** this prompt is already well-calibrated for its task. Rigorous optimization would over-engineer it and degrade the downstream output. > > **Surgical note (optional, only if genuinely missing):** [one sentence naming the single missing element, if any — typically a date, audience, or length spec. If nothing is missing, write "None — send as is."] > > That is the entire response. Do NOT add a diagnostic table, archetype detection, architecture decision, XML scaffolding, change log, feasibility check, run settings recommendation, or use case guidance. Doing so defeats the purpose of the triage. **Self-check before finalizing Path A.** If your surgical note names 2 or more distinct gaps (e.g., "you need to specify X, Y, and Z"), the triage miscalled. A prompt with 2+ real gaps is BORDERLINE by the skill's own definition. Re-classify and route to Path B. Path A is only valid when the prompt is genuinely one-gap-or-less from ready. ### Path B — BORDERLINE output format Return exactly three sections: **SECTION 1 — TRIAGE & DIAGNOSIS** One line of triage verdict. Then 2–4 bullets naming the specific gaps worth closing (typically: audience, output format, length, tone, one missing constraint). Do NOT run the full 9-dimension scoring or the architecture decision — they are theater at this band. **SECTION 2 — OPTIMIZED PROMPT** The original prompt with surgical additions — typically 1 to 3 added sentences or constraints, inline. NO XML scaffolding. NO capability activation layer. If the original works as a paragraph, it stays a paragraph. Copy-paste ready. **SECTION 3 — CHANGE LOG** Two to four bullets. Each names what changed and why, in plain language. No diagnostic dimension tags — they don't earn their place here. No feasibility check, no use case guidance, no architecture decision, no effort recommendation. BORDERLINE outputs aren't the kind of thing that has either a ceiling or an architecture question, and the default effort level is always right for them. The one permitted addition: if the task genuinely needs current information and would fail silently with web search off, append a single line — "Run with web search on." Nothing more. ### Path C — IN PURVIEW output format (the full rigorous treatment) Proceed through Steps 1–9 below. The output format branches further based on Step 3's architecture decision: SINGLE-TURN template (Path C1) or CHAIN template (Path C2). See "IN PURVIEW output formats" at the end of this document. --- ## IN … ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [viktor-milev](https://github.com/viktor-milev) - **Source:** [viktor-milev/claude-skills](https://github.com/viktor-milev/claude-skills) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-viktor-milev-claude-skills-prompt-optimizer - Seller: https://agentstack.voostack.com/s/viktor-milev - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.