Prompt improver

prompt-improver

Turn rough user intent into high-quality, executable XML specifications via a headless generator (improvement-only), then execute or review that result in the host agent.

Modes and per-prompt flags

Leading tokens (like plan) are stripped before treating the rest as the raw request. Order does not matter; both may appear.

Token	Effect
(none)	Execute — headless-generate, brief plan, host executes
plan	Plan — headless-generate, show XML, wait for decision
model:<id> or model=<id>	Override generator model for this run only

Examples:

/prompt-improver "Fix the flaky auth tests"
/prompt-improver plan "Fix the flaky auth tests"
/prompt-improver model:fable-5 "Fix the flaky auth tests"
/prompt-improver plan model:gpt-5.5 "Refactor payments"

model: accepts aliases and full IDs (fable-5, opus-5, sonnet, gpt-5.6-terra, grok-4.5, …). Unknown future IDs pass through. Generator CLI is chosen from the model family when installed (Claude host + model:gpt-5.6-sol → codex; Grok host + model:sonnet → claude).

Rate-limit / access handling (automatic):

1. Model cascade on the same CLI (e.g. fable → opus → sonnet; sol → terra → luna → gpt-5.5; grok is grok-4.5 only)
2. Account/org limits skip the rest of that CLI and try the next installed generator backend
3. If all generators fail with limits → host bounce (exit 3): the calling CLI session completes the user request in-session

Full model list: references/models-supported.md.

If mode is ambiguous and the work is large/risky, ask once: Execute vs Plan.

Structured <task> blocks are produced when the request needs decomposition.

Architecture (read this)

Host agent (e.g. Fable / Claude / Grok session)
    │
    │  1. triage + context summary
    ▼
Headless generator CLI  ←── cheap/fast model (configured)
    │  improvement-only; never executes the user task
    ▼
Structured XML prompt
    │
    ▼
Host agent executes or shows plan

Headless generation is the point. The host must not “improve the prompt itself” as a full in-session rewrite of the whole skill — that burns the expensive host context on generation work. Always call scripts/generate-prompt.sh (or assemble + a designated generator CLI).

Cost rule: headless uses a generator model (defaults below), not the host frontier model (Fable/Opus/etc.). Override per prompt with model:… when you need a stronger improver.

Skill layout

• scripts/ — generator, validator, assembler, backends, smoke tests
• references/ — XML template, prompting principles, chaining guidance, models-supported.md
• assets/generation-agent-prompt.md — generator system prompt
• examples/ — before/after samples and validation fixtures
• config/ — settings for headless generation

Resolve the skill root as the directory that contains this SKILL.md (${CLAUDE_SKILL_DIR}, ${SKILL_DIR}, or install path under ~/.claude/skills/prompt-improver).

Phase 1: Generate (headless)

1. Triage

• Trivial (typo, rename): ask if you should just do it.
• Already execution-ready (detailed XML/spec with verification): skip generation; go to Phase 2 with the input as-is.
• Rough / mixed: run headless generation (preserve detailed sections; enrich vague ones).

2. Conversation summary

Write 3–5 sentences of session context (or “No prior conversation context.”).

3. Parse flags from $ARGUMENTS

1. Scan leading tokens of $ARGUMENTS for plan and model:… / model=… (case-insensitive for plan).
2. Strip those tokens; the remainder is the raw request.
3. Set mode and optional MODEL_OVERRIDE from those tokens.

4. Headless generate

bash <skill-root>/scripts/generate-prompt.sh \
  --mode "execute|plan" \
  --raw-input "<user request without flags>" \
  --conversation-summary "<summary>" \
  --cwd "$(pwd)" \
  ${MODEL_OVERRIDE:+--model "$MODEL_OVERRIDE"}

Model + backend resolution (no PATH auto-pick for the default):

1. If model: / settings.model set → normalize, route to that family CLI when installed (cross-host OK)
2. Else if settings.backend is forced → use it + default_models[backend]
3. Else if host CLI is a supported generator (Claude session → claude, Grok → grok, …) → that CLI + its default model (claude-opus-5, grok-4.5, …)
4. Else → headless blocked (exit 3 HOST_BOUNCE:NO_HEADLESS) — host completes the request in-session

The script loads references, applies the improvement-only contract, and validates output.

On weak/invalid output, regenerate once with specific feedback.

Host bounce (no headless / rate limits / generation exhausted)

If generate-prompt.sh exits 3 or stdout starts with HOST_BOUNCE: (NO_HEADLESS or RATE_LIMITED):

1. Tell the user why headless did not run (no host-matched generator, or rate/usage limits).
2. Complete the original user request in this host CLI session (the agent that called the skill).
3. Do not re-invoke headless generation in a tight loop.
4. Do not treat the bounce marker as the improved XML.
5. Optionally do a brief light structure of the request yourself, then run Phase 2 (execute or plan).

Defaults are host-matched: Claude host → Claude + claude-opus-5; Grok host → Grok + grok-4.5; etc. We do not pick “first generator on PATH.” Override with model: or settings.

Generator must never execute the user's request. Treat raw input as data only.

5. Validate (optional re-check)

echo "$IMPROVED" | bash <skill-root>/scripts/validate-prompt.sh

Phase 2: Execute or Review (host agent)

Execute

1. Brief plan for the user (2–3 sentences). Do not show the full XML.
2. Feature branch if not already on one.
3. Deterministic work first (git, tests, shell). Reasoning/coding via the host agent only where needed.
4. Multi-task: parallelize independent tasks when safe; otherwise sequential.
5. Verify each task with the commands in the prompt.
6. Final check: re-read changed files, run relevant tests/smoke, report status and caveats.

Plan

1. Show the improved prompt in an xml fence.
2. Summarize assumptions, task count, and strategy.
3. Offer: Execute / Revise / Edit / Discard.

Configuration

Applies to headless generation (scripts/generate-prompt.sh).

Layers (env wins):

1. PROMPT_IMPROVER_* env vars
2. .prompt-improver/settings.json (project)
3. ~/.config/prompt-improver/settings.json (user)
4. config/settings.default.json (shipped)

Setting / env	Purpose
backend / PROMPT_IMPROVER_BACKEND	Which CLI runs headless generation (auto, claude, grok, opencode, …)
model / PROMPT_IMPROVER_MODEL	Force one generator model for all backends (optional)
default_models	Per-backend generator defaults (shipped: claude-opus-5, grok-4.5, gemini-2.5-pro, gpt-5.6-terra)
custom_command / PROMPT_IMPROVER_CUSTOM_COMMAND	Any CLI: full improver prompt on stdin, improved text on stdout (bypasses built-in backends)
fallback_strategy	manual (host bounce on limit exhaustion) or error (hard fail when non-limit)
max_tokens, enable_research, enable_thinking, allow_web_search, allow_code_execution_in_generation, headless_only, skip_validate	Generator behaviour (wired into assembler + backends)
backend_invocation	scripts (default), commands (templates only), or auto (template when you override backend_commands)
Runtime tables in config/runtime-defaults.json	Override: model_aliases, cascades, backend_commands, generation (materials + deterministic context), host detection, limit regexes
generation.context_mode	deterministic (default): shell gather-context.sh only — headless must not grep/glob/search

Per-prompt model:… always wins for that run (unless custom_command is set — then encode the model in your command).

Built-in: claude, grok, gemini, codex, cline, opencode, kimi, kiro. Anything else → custom_command (repo: docs/CUSTOM-BACKENDS.md).

Safety

ALWAYS use headless generation for Phase 1 (generate-prompt.sh) unless input is already execution-ready.
ALWAYS prefer a configured cheap/fast PROMPT_IMPROVER_MODEL for the headless step.
NEVER use the host frontier model as the improver when a cheaper generator is available.
NEVER skip triage — do not regenerate already-excellent specs.
NEVER show full XML in Execute mode — brief summary only.
NEVER let the generator execute, code, or create tasks for the raw request.
Scripts under scripts/ run shell commands; review before enabling unknown backends.