--- name: prompt-improver description: > Transform vague prompts into precise, verifiable structured XML prompts that coding agents execute reliably. Modes: execute (default — generate then run) and plan (generate XML for review first). Use when the user says improve prompt, make this work better, prompt engineer, structure a request, plan a complex change before coding, or when a rough request needs verification criteria before execution. Do not use when the input is already a well-structured XML prompt or detailed implementation spec — skip generation and execute directly. license: MIT metadata: author: owenob1 version: 1.1.0 category: prompt-engineering --- # 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:` or `model=` | Override generator model **for this run only** | Examples: ```text /prompt-improver "Fix the flaky auth tests" /prompt-improver plan "Fix the flaky auth tests" /prompt-improver model:fable "Fix the flaky auth tests" /prompt-improver plan model:gpt-6-sol "Refactor payments" ``` `model:` accepts aliases and full IDs (`fable`, `opus`, `sonnet`, `opus-5.5`, `gpt-6-sol`, `grok-4.7`, `gemini-3.8-flash`, …). Unknown future IDs pass through; only letters, digits and `. _ - : / @ + [ ]` are accepted. Generator CLI is chosen from the model family when installed (Claude host + `model:gpt-6-sol` → codex; Grok host + `model:sonnet` → claude). **Rate-limit / access handling** (automatic): 1. Model cascade on the same CLI, always starting with the requested model (e.g. fable → opus → sonnet; gpt-6-astra → gpt-6-sol → gpt-6-luna → gpt-5.6-terra; grok-4.3 → grok-4.7 → grok-4.6 → grok-4.5) 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 `` blocks are produced when the request needs decomposition. ## Architecture (read this) ```text Host agent (e.g. Fable / Claude / Grok session) │ │ 1. triage + context summary ▼ Headless generator CLI ←── generator model (configured; default per CLI) │ improvement-only, tools disabled/read-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). **Model rule:** headless uses the configured **generator model** (`default_models`: `opus` on claude, `gpt-6-sol` on codex, `grok-4.7` on grok, `gemini-3.8-flash` on gemini). The shipped Claude default is `opus` because spec quality drives execution quality; for cheaper runs set `model:sonnet` per prompt or `default_models.claude` in settings. ## 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 Pass the request through a **quoted heredoc** (`<<'REQ'`) so `$`, backticks and quotes in the user's text are never expanded by the shell, and long requests never hit argv limits: ```bash bash /scripts/generate-prompt.sh \ --mode "execute|plan" \ --conversation-summary "" \ --cwd "$(pwd)" \ ${MODEL_OVERRIDE:+--model "$MODEL_OVERRIDE"} \ --raw-input-file - <<'REQ' REQ ``` `--raw-input ""` still works for short, plain requests. 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, Codex → codex, Grok → grok, …) → that CLI + its default model (`opus`, `gpt-6-sol`, `grok-4.7`, …) 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. Exit codes: `0` improved XML on stdout · `1` bad usage · `2` hard failure (only with `fallback_strategy=error`) · `3` host bounce · `4` generated but failed validation (body still on stdout). On exit 4 or weak 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 + `opus`; Codex host → Codex + `gpt-6-sol`; Grok host → Grok + `grok-4.7`; 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) ```bash printf '%s\n' "$IMPROVED" | bash /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. `<--cwd>/.prompt-improver/settings.json` (project) 3. `~/.config/prompt-improver/settings.json` (user) 4. `config/settings.default.json` (shipped) 5. `config/runtime-defaults.json` (shipped tables) A malformed settings file is skipped with a warning. | Setting / env | Purpose | |---------------|---------| | `backend` / `PROMPT_IMPROVER_BACKEND` | Which CLI runs headless generation (`auto`, `claude`, `codex`, `copilot`, …) | | `model` / `PROMPT_IMPROVER_MODEL` | Force one generator model for all backends (optional) | | `default_models` | Per-backend generator defaults (shipped: claude `opus`, codex `gpt-6-sol`, grok `grok-4.7`, gemini `gemini-3.8-flash`; others use the CLI's own default) | | `generation.backend_timeout_secs` / `PROMPT_IMPROVER_BACKEND_TIMEOUT` | Per-attempt timeout for a generator CLI (default 300; grok uses `grok_timeout_secs`, default 180) | | `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, codex, grok, gemini, agy (Antigravity), copilot, cursor, opencode, cline, qwen, droid, amp, kimi, kiro. Anything else → `custom_command` (repo: `docs/CUSTOM-BACKENDS.md`). ## Safety ```text ALWAYS use headless generation for Phase 1 (generate-prompt.sh) unless input is already execution-ready. Pass user text via --raw-input-file with a quoted heredoc, never interpolated into a shell string. 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. ```