Improve Prompt

Overview

Turn a vague or under-specified prompt into one that reliably produces the output the user actually wants — for any target model, not just Claude. The skill is model-agnostic: it uses techniques that hold across vendors (OpenAI, Google, Meta, Mistral, Midjourney, Stable Diffusion, Sora, Veo, ElevenLabs, etc.) and only mentions a vendor when a technique is genuinely vendor-specific, flagged as optional.

Core principle: A good prompt removes the model's need to guess. Most weak prompts fail because they leave the task, the context, the output shape, or the success criteria implicit. The job is to make those explicit without bloating the prompt.

This is a collaborator, not an auto-rewriter. Never auto-fire. Never silently rewrite. When the prompt is underspecified, ask before guessing — see The Iron Rule.

When to Use

• User types /improve-prompt.
• User pastes a prompt (or describes one) and asks to improve / sharpen / fix / "make it better" / "why isn't this working".
• User wants help phrasing a request to any AI model — text, image, video, or audio.

Don't use for: writing a prompt from a blank slate where the user hasn't said what they want at all (interview them first about the goal), or for non-prompt copy-editing.

The Iron Rule

DO NOT GUESS AT MISSING INTENT. ASK, THEN REWRITE.

If the prompt is missing something that materially changes the output — the audience, the format, the constraints, the target model's medium — you ask before rewriting. Inventing those details produces a confident rewrite that solves the wrong problem. The exception: if the gap has an obvious, low-risk default, fill it and state the assumption in the rationale so the user can correct it.

Workflow

1. Classify  → text/LLM prompt or generative (image/video/audio)?
2. Diagnose  → score against the relevant dimensions; list what's missing
3. Decide    → gaps that change the output → interview; trivial gaps → assume + flag
4. Rewrite   → produce the improved prompt
5. Explain   → short rationale: what changed, why, and any assumptions made

1. Classify

The two families have different best practices. Detect which one applies (ask if ambiguous):

• Text / LLM / agent — chat, instructions, system prompts, coding, extraction, reasoning, roleplay.
• Generative media — image, video, audio/music/voice. These are descriptive, not instructional: you describe the artifact you want, not commands to follow.

2. Diagnose

Score the prompt against the dimensions for its family (Dimensions below). Identify concretely what is missing or weak — cite the phrase, don't hand-wave.

3. Decide: interview vs. assume

For each gap, ask: does filling this differently produce a materially different output?

• Yes → ask the user. Use AskUserQuestion for 1–3 crisp choices (audience, format, length, tone, target model/medium, must-include / must-avoid). Don't interrogate — ask only what changes the answer.
• No / obvious default → fill it and note the assumption in the rationale.

Skip the interview entirely when the prompt is already well-specified and only needs tightening.

4. Rewrite

Apply the techniques. Keep it model-agnostic. Preserve the user's voice and intent — improve clarity and completeness, don't impose a different goal. Size the rewrite to the gaps found in step 2: every added line closes a named gap, and when the gaps are closed, stop — length is set by the gaps, not by thoroughness.

5. Explain

Always close with a brief rationale:

• What changed — the 3–6 substantive edits, each tied to a dimension ("added an explicit output format because the original left it implicit").
• Assumptions made — anything filled by default, so the user can correct it.
• Optional per-model notes — only if a vendor-specific tweak would help (e.g. "if you're sending this to Claude, wrapping the reference text in <doc> tags improves grounding"; "for Midjourney, append --ar 16:9 --style raw"). Mark these as optional.

Dimensions (Text / LLM)

A strong text prompt usually nails these. Use as the diagnostic checklist:

Dimensions (Generative media)

Image/video/audio prompts are descriptive and order-sensitive. Diagnostic checklist:

Front-load the most important terms — most media models weight earlier tokens more heavily.

Techniques That Generalize

These hold across vendors and both families:

1. Be specific and concrete. Replace abstractions with the exact thing. "Summarize in 3 bullets for a non-technical exec" beats "summarize nicely."
2. State the output contract. Format, length, structure, and what not to include. For LLMs, ask for the exact schema. For media, state aspect ratio / duration / resolution.
3. Show, don't just tell. One or two examples (few-shot) anchor the model far more reliably than adjectives. For media, reference styles/artists/film stocks concretely.
4. Give the model room to reason (text). For anything analytical, allow step-by-step or a scratchpad before the final answer; ask for the answer last — a model forced to commit to an answer before reasoning tends to defend the first thing it said rather than work the problem.
5. Set boundaries. Explicit must-include / must-avoid lists prevent drift more reliably than hoping.
6. Provide context the model can't infer. Paste the data, the prior decision, the audience — don't make it guess.
7. One prompt, one job. Split multi-goal prompts; chained simple prompts beat one tangled mega-prompt.
8. Front-load importance (media especially). Lead with subject and the non-negotiable attributes.
9. Prefer positive instruction. "Write in plain active voice" works better than "don't be verbose" on most models; use negatives only for true exclusions.
10. Keep it as short as it can be while staying complete. Every clause should earn its place; padding dilutes the signal.

Output Template

## Improved prompt

<the rewritten prompt, in a fenced block so it's copy-paste ready>

## What changed
- <edit> — <which dimension / why>
- ...

## Assumptions
- <anything filled by default; omit section if none>

## Optional per-model notes
- <vendor-specific tweak, marked optional; omit section if none>

When the change is small, collapse to the improved prompt + a one-line rationale. When you interviewed first, the rationale can reference the answers ("set the format to a comparison table per your choice").

Examples

Text — before/after

Before: write about our new feature

After interview (audience: existing customers; channel: changelog; tone: concise):

Write a changelog entry announcing <FEATURE> to existing customers.

Audience: current users, moderately technical.
Length: 80–120 words.
Structure: one-sentence what-it-is, then 2–3 bullets of concrete benefits, then a one-line how-to-enable.
Tone: direct, no marketing superlatives.
Do not invent capabilities — only describe: <paste the feature's actual behavior here>.

Image — before/after

Before: a nice picture of a city

After:

A rain-soaked Tokyo side street at night, neon signage reflecting in puddles,
a lone figure under a translucent umbrella, shallow depth of field, 35mm,
cinematic teal-and-magenta palette, wet asphalt detail, volumetric haze,
photoreal. --ar 16:9

Rationale: led with subject + setting, added composition (35mm, shallow DoF), lighting/mood, concrete detail density, and an aspect ratio; --ar is Midjourney-specific (optional — drop it for other models).

Red Flags — STOP

• About to rewrite a prompt whose goal you're guessing at → ask first (Iron Rule).
• About to pad a prompt with boilerplate that doesn't change the output → cut it.
• Adding vendor-specific syntax to the main rewrite instead of the optional notes → keep the core agnostic.
• Skipping the rationale → the user can't learn or correct without it.