/prompt-improver

Turn vague agent prompts into precise, verifiable specs — then run them.

Features · Install · Usage · Models · How it works · Advanced · Contributing · Full model list · Custom backends

---

✨ Features

Headless generation	Improves prompts in a separate model call — not by grinding the host agent session
Improvement-only	Generator never implements your feature; it only rewrites the request
Execute or plan	Run immediately, or review the XML first
Any model override	model:fable-5, model:sonnet, model:gpt-5.5, … — routes to the right CLI when installed
Cross-host / cross-CLI	Claude host + GPT generator, Grok host + Claude generator — OK if that CLI is on PATH
Portable skill	Agent Skills format · skills.sh · Claude marketplace

---

📦 Install

Recommended

npx skills add -g owenob1/prompt-improver

Other install options

Project only

npx skills add owenob1/prompt-improver

Claude Code — add marketplace

/plugin marketplace add owenob1/prompt-improver

Claude Code — install plugin

/plugin install prompt-improver@prompt-improver

Manual (clone + copy)

git clone https://github.com/owenob1/prompt-improver.git && cp -R prompt-improver/skills/prompt-improver ~/.claude/skills/prompt-improver

---

🚀 Usage

# Improve + execute (default)
/prompt-improver "Fix the flaky auth tests"

# Improve only — review the XML before running
/prompt-improver plan "Fix the flaky auth tests"

# Use a specific generator model for this run
/prompt-improver model:fable-5 "Fix the flaky auth tests"

Flag	Effect
(none)	Improve headlessly, then execute
plan	Improve headlessly, show XML, wait
model:<id>	Override generator model for this run (any family / future ID)

---

🧠 Default generator models

Backend CLI	Default model	Notes
claude	sonnet → Sonnet 5	Daily-driver structured rewrite
grok	grok-composer-2.5-fast	Fast high-quality improver
gemini	gemini-2.5-pro	Pro reasoning for specs
codex	gpt-5.5	GPT-5 family Codex default

Default pick: host CLI + that CLI’s default (Claude→sonnet, Grok→composer, …) — not first-on-PATH.
Override: model: → env/settings.model → routes by model family when that CLI is installed.

Recognized models & aliases

Pass full IDs or short aliases. Unknown future IDs pass through (e.g. gpt-5.6-sol-ultra, grok-4.6) and still route by family prefix.

Family	Examples (model:…)	Generator CLI
Claude	fable-5, fable, opus, sonnet, haiku, claude-*	claude
Grok	grok-4.5, grok-4.3, grok-composer-2.5-fast, grok-build, composer-*	grok
Gemini	gemini-2.5-pro, gemini-2.5-flash, gemini-3.1-pro, gemini-*	gemini
OpenAI / Codex	codex, openai, gpt-5.5, gpt-5, gpt-5.6-sol, sol, terra, luna, gpt-5.3-codex, o4-mini, gpt-*	codex

Cross-host is fine: Claude Code + model:gpt-5.6-sol uses codex if installed; Grok + model:sonnet / model:fable-5 uses claude if installed.

Access / rate-limit fallbacks

If a model is unavailable, restricted, or out of usage, headless generation:

1. Walks the model cascade on the current CLI (first success wins)
2. On account/org limits, skips the rest of that CLI and tries the next installed generator
3. If every generator is limited → host bounce: the calling agent CLI finishes the user request in-session

CLI	Fallback
Claude	fable → opus → sonnet
Codex	sol → terra → luna → gpt-5.5
Grok	grok-4.5 → composer-2.5-fast → grok-build
Gemini	gemini-2.5-pro → gemini-2.5-flash

Full alias + cascade reference: models-supported.md (also under docs/MODELS.md).

---

⚙️ How it works

1. Triage — skip generation if the input is already a solid spec
2. Generate — headless rewrite via scripts/generate-prompt.sh (model/backend resolved as above)
3. Validate — structural checks
4. Execute or review — host runs the plan (or shows it with plan)

---

🔧 Advanced

Standalone CLI (no agent skill)

# Standalone: improve only (plan mode), default generator model
bash skills/prompt-improver/scripts/standalone-improve.sh "Fix the flaky auth tests" plan

# Same, but force Fable as the generator
bash skills/prompt-improver/scripts/standalone-improve.sh "Fix the flaky auth tests" plan fable-5

# Lower-level generate script (same flags the skill uses headlessly)
bash skills/prompt-improver/scripts/generate-prompt.sh \
  --mode plan \
  --raw-input "Fix the flaky auth tests" \
  --model fable-5

Settings

mkdir -p ~/.config/prompt-improver
cp skills/prompt-improver/config/settings.example.json \
  ~/.config/prompt-improver/settings.json
# Keys starting with // are comments (safe to leave or delete)

Key / env	Purpose
model / PROMPT_IMPROVER_MODEL	Force one generator model
default_models	Per-backend defaults
backend / PROMPT_IMPROVER_BACKEND	auto (host-matched), claude, grok, opencode, …
custom_command / PROMPT_IMPROVER_CUSTOM_COMMAND	Any CLI: prompt on stdin → improved text on stdout
model_aliases	Extend/override short names → model IDs
model_fallback_chains	Custom rate-limit cascades
backend_commands	Custom CLI invoke templates
generation	Materials paths, output contract, deterministic context (no AI grep/glob)

Runtime tables (aliases, cascades, host detection, generation materials, …) ship in config/runtime-defaults.json and are fully overridable. Full guide: docs/CUSTOM-BACKENDS.md.

Repository layout

skills/prompt-improver/   # installable skill
plugins/prompt-improver/  # Claude Code plugin
.claude-plugin/           # marketplace catalog
tests/                    # smoke tests

Security

Scripts under skills/prompt-improver/scripts/ run shell and may invoke coding CLIs. Review before install.

---

🤝 Contributing

bash tests/smoke-test.sh

CONTRIBUTING.md · Roadmap

---

📄 License

MIT © owenob1