Yesterday, v0.6.0 of a Claude Code prompt improver plugin shipped on GitHub. The idea started simple. The twist is how far it got taken.
It started as one hook. Before Claude Code runs your prompt, it checks if the prompt is vague. Clear? Pass through, 189 tokens charged, done. Vague? A skill fires, researches your codebase, and asks 1 to 6 grounded clarifying questions. The whole point: shape context so Claude lands a better first output instead of burning a correction loop. Think about how often you type something like “fix the auth bug” and Claude goes off in the wrong direction for 600 tokens before you course-correct. That is what this hook is designed to kill.
What counts as vague? The check looks at specificity, not length. A short prompt with a clear scope passes. A long prompt with no concrete target fails. The clarifying questions it generates are not generic either. The skill reads your actual codebase first, so the questions it surfaces are grounded in your file structure, your existing patterns, your named components. Not “what do you want to achieve?” but “do you want this to apply to the existing UserAuth class or create a new one?”
That single idea is now a declarative engine running seven nudges across three hook events.
The part worth sitting with: adding a new nudge requires one JSON file and zero Python. Each behavior is a data row in a registry. No scripts to touch. You define what event triggers it, what condition activates it, and what instruction gets injected. That is the whole interface. The engine reads the registry and handles the rest. It means anyone can fork this, add a custom nudge for their own workflow, and never open a Python file.
The Seven Nudges and Where They Fire
🔍 On every UserPromptSubmit:
- improve: the original behavior. Vague prompts get the skill, clear prompts pass through. The clarity check itself costs almost nothing, so you are not paying a tax on prompts that are already good.
- approach-assessment: non-trivial requests get asked to pick an approach before Claude starts (plan, subagent, or just do it). This fires before any tokens get spent on the actual task, which is exactly when the decision is cheapest to make.
- workflow: dynamic workflow requests get routed to plan mode, with implementation pushed to a cheaper model so the session model stays for planning. Keeps your expensive context window doing planning work instead of grinding through boilerplate implementation it could hand off.
- output-readability: substantial deliverables get nudged toward conclusion-first structure with sections instead of walls of text. Particularly useful for research tasks where you want a verdict up top before the reasoning, not buried at the end after three paragraphs of setup.
📋 Before a tool runs (PreToolUse):
- plan: entering plan mode triggers a nudge for a readable plan plus a self-review pass before it’s presented. The self-review step catches gaps before you see the plan, so you are not spending a round-trip pointing out what is missing.
- background-exec: long-running commands (dev servers, file watchers) get nudged to run in background and poll only the output that matters. Without this, Claude will happily sit and stream a dev server log at you indefinitely instead of moving on.
🤖 When an agent spawns (SubagentStart):
- subagent-routing: Explore and Plan agents get steered toward breadth over depth and conclusion-first reporting, so the parent context stays lean. Subagents that write long preambles before their actual findings are a common way parent sessions bloat. This nudge cuts that before it starts.
Every nudge fires only when it applies. Silent otherwise. Clear prompts still only pay for the clarity check. Nothing else loads.
Pro Tip
The approach-assessment nudge is the one worth enabling first. It fires before Claude starts on anything non-trivial and forces one question: plan, subagent, or just do it? That single decision point cuts a lot of expensive mid-task pivots. The reason it works is the forcing function. “Just do it” is a legitimate answer, but choosing it consciously is different from letting Claude assume it. When you pick “plan” you get an artifact you can approve before any code runs. When you pick “subagent” you keep your main session clean. That one structured pause at the start saves more tokens than most optimizations you can make mid-task.
How to Install
claude plugin marketplace add severity1/severity1-marketplace
claude plugin install prompt-improver@severity1-marketplaceAfter install, the registry is editable. If you want to disable a nudge you don’t use, you pull it out of the registry. If you want to add one for your team’s specific patterns, you drop in a JSON file. No rebuild step, no restarting anything.
Repo: github.com/severity1/claude-code-prompt-improver
⭐ Worth a star if you’ve ever had Claude run 800 tokens in the wrong direction before you caught it.
Claude Code Prompt Improver v0.6.0 – declarative nudge engine
by u/crystalpeaks25 in PromptEngineering