Claude Code Prompt Improver
Intelligent prompt optimization for Claude Code. It injects the right context at the right moment - at prompt submit, tool use, and subagent start - so Claude has what it needs before it acts. The goal is a better first output, so you spend fewer turns correcting it.
Prompt improvement here means improving the whole path from your prompt to Claude's output, not just rewriting the words you typed. Clarifying a vague prompt is one way to do that. Supplying a constraint you would otherwise have had to add by hand after a bad first attempt is another. Both land the output sooner.
What It Does
A small set of targeted nudges fire only when they apply, each one supplying context that would otherwise cost a correction round-trip:
| Nudge | Fires when | Supplies |
|---|
improve | every prompt (flagship) | clarity check; asks 1-6 grounded questions only when the prompt is genuinely vague |
approach-assessment | a request looks non-trivial (implement, refactor, migrate, multi-file) | choose how to carry it out - subagent, heavier orchestration, or just do it - and pass a spawned subagent the context it needs |
workflow | a request looks like a multi-step workflow | plan-first and per-stage model-routing guidance |
output-readability | the response will be a substantial deliverable | lead with the conclusion, prefer sections and tables, keep it terse |
ask-user-question | a request hides a decision that is genuinely yours (a fork, a real tradeoff, missing requirements) | ask via the AskUserQuestion tool with concrete options so you can think critically; research first when context is thin; default on minor or reversible choices |
plan-mode | every prompt (alongside improve) | assess whether the task is complex enough to warrant a plan reviewed before any code; enter plan mode if so, otherwise proceed |
plan | entering plan mode | terse, readable plan: file-path anchors, no decision history; re-read for flaws before presenting |
background-exec | a long-running command (dev server, watcher, tail) is about to run | run it in the background, poll only the output that matters |
subagent-routing | a research or planning subagent starts | favor breadth over depth, return conclusions not raw dumps |
Two nudges evaluate every prompt. improve checks clarity:
- For clear prompts: proceeds immediately (zero skill overhead)
- For vague prompts: invokes the
prompt-improver skill to create a research plan, gather context, and ask 1-6 grounded questions, then proceeds with the clarification
plan-mode runs alongside it, judging whether the task is complex enough to plan before acting - it self-cancels on anything trivial.
The other seven fire only when they apply. The keyword-gated ones (workflow, approach-assessment, output-readability, ask-user-question, background-exec) lead with a condition ("If this is X... if not, ignore"), so a false fire is dismissed cheaply; the exact-gated ones (plan on plan-mode entry, subagent-routing on a research agent) only fire when the condition is already certain.
Result: Better outcomes on the first try, without back-and-forth.
v0.4.0 Update: Skill-based architecture with hook-level evaluation achieves 31% token reduction. Clear prompts have zero skill overhead, vague prompts get comprehensive research and questioning via the skill.
How It Works
sequenceDiagram
participant User
participant Hook
participant Claude
participant Skill
participant Explore
participant Project
User->>Hook: "fix the bug"
Hook->>Claude: Evaluation prompt (~189 tokens)
Claude->>Claude: Evaluate using conversation history
alt Vague prompt
Claude->>Skill: Invoke prompt-improver skill
Skill-->>Claude: Research and question guidance
Claude->>Claude: Create research plan (TodoWrite)
Claude->>Explore: Dispatch research (Glob, Grep, Web, multi-file Read)
Explore->>Project: Execute search and reads
Project-->>Explore: Raw results
Explore-->>Claude: Synthesized findings
Claude->>Claude: Synthesize, mine history, run git/Bash if needed
Claude->>User: Ask grounded questions (1-6)
User->>Claude: Answer
Claude->>Claude: Execute original request with answers
else Clear prompt
Claude->>Claude: Proceed immediately (no skill load)
end
Installation
Requirements: Claude Code 2.0.22+ (uses AskUserQuestion tool for targeted clarifying questions)
Option 1: Via Marketplace (Recommended)
1. Add the marketplace:
claude plugin marketplace add severity1/severity1-marketplace
2. Install the plugin:
claude plugin install prompt-improver@severity1-marketplace
3. Restart Claude Code
Verify installation with /plugin command. You should see the prompt-improver plugin listed.
