Claude Code Prompt Improver: targeted prompts for fewer correction turns

Why Prompt Improver targets Claude Code correction cycles

Claude Code Prompt Improver addresses a specific workflow problem: a prompt may be understandable to the developer but under-specified for the agent. The README describes the result as spending fewer turns correcting the first output, and it treats prompt improvement as more than paraphrasing. The plugin can add missing context, identify decisions that belong to the user, and recommend a different execution approach before Claude starts editing files.

The intended users are people using Claude Code for implementation, refactoring, migration, research, and multi-file work. It is not a general-purpose text-generation package. Its behavior is tied to Claude Code events such as UserPromptSubmit, PreToolUse, and SubagentStart. The README also states that Claude Code 2.0.22 or newer is required because targeted clarification uses the AskUserQuestion tool.

The project makes a deliberate distinction between clear and vague prompts. Clear prompts proceed immediately without loading the prompt-improver skill. Vague prompts can trigger research and grounded questions. This design is more conservative than automatically rewriting every request, but it also means that detection quality depends on Claude's interpretation of whether a prompt is genuinely vague.

How Prompt Improver evaluates events and injects nudges

The architecture is a command-based Claude Code hook backed by Python scripts, JSON nudge files, and a prompt-improver skill. The README describes the engine as loading nudges recursively from paths such as nudges/<EventName>/*.json. The engine therefore resolves the nudge directory relative to its own location. That layout matters for manual installation because the scripts and nudges directories must remain siblings under the same parent.

At prompt submission, the flagship improve nudge evaluates clarity. For a vague request, it invokes the skill, creates a research plan, dispatches exploration, synthesizes the findings, and asks between one and six grounded questions. For a clear request, it skips the skill and proceeds without adding a research step. A separate plan-mode nudge runs alongside improve. It decides whether the task needs a plan reviewed before code changes and self-cancels for trivial work.

The other nudges are conditional. approach-assessment can suggest a subagent, heavier orchestration, or direct execution for non-trivial work. workflow can encourage planning and per-stage model routing. output-readability asks for conclusions, sections, and tables when the response is a substantial deliverable. ask-user-question surfaces hidden forks or tradeoffs, while background-exec changes long-running commands such as development servers and watchers into background work. subagent-routing shapes research or planning agents toward conclusions rather than raw result dumps. This is a rules-based prompting layer, not a separate task runner.

Installing the plugin and checking the first prompt

The README gives marketplace installation as the recommended path. The first command adds severity1's marketplace, and the second installs the prompt-improver plugin from it:

claude plugin marketplace add severity1/severity1-marketplace

After the marketplace is available, install the plugin with the exact package name shown in the README:

claude plugin install prompt-improver@severity1-marketplace

Restart Claude Code, then run the `/plugin` command. The README says the prompt-improver plugin should appear in the plugin list. That check confirms registration, but the README does not claim that the command verifies every hook file or rule.

For local development, the repository can be cloned and its development marketplace can be added by absolute path:

git clone https://github.com/severity1/claude-code-prompt-improver.git
cd claude-code-prompt-improver

Replace `/absolute/path/to/` with the actual checkout location when running the documented marketplace command:

claude plugin marketplace add /absolute/path/to/claude-code-prompt-improver/.dev-marketplace/.claude-plugin/marketplace.json

Then install the local package:

claude plugin install prompt-improver@local-dev

Restart Claude Code again. The README says `/plugin` should show "1 plugin available, 1 already installed".

Manual installation exposes the hook layout

Manual installation copies the Python engine, rules, builtins, and nudge directory into Claude Code's user hook location. The documented commands are:

mkdir -p ~/.claude/hooks/prompt-improver/scripts
cp scripts/engine.py scripts/rules.py scripts/nudge_builtins.py ~/.claude/hooks/prompt-improver/scripts/
cp -r nudges ~/.claude/hooks/prompt-improver/nudges
chmod +x ~/.claude/hooks/prompt-improver/scripts/engine.py

The README then instructs users to update ~/.claude/settings.json. The excerpt shows hook entries for UserPromptSubmit and PreToolUse, including a PreToolUse matcher for EnterPlanMode and Bash. The visible configuration invokes engine.py with the corresponding event name, for example:

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.claude/hooks/prompt-improver/scripts/engine.py UserPromptSubmit"
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "EnterPlanMode|Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.claude/hooks/prompt-improver/scripts/engine.py PreToolUse"
          }
        ]
      }
    ]
  }
}

The excerpt cuts off while showing SubagentStart, so it should not be treated as a complete settings file. The README does not document a separate dependency installation command or a Python package requirement beyond the Claude Code version requirement.

Benefits, maintenance, and license considerations

The most concrete benefit is reduced manual steering. Instead of asking Claude to plan before every substantial edit, the plan-mode nudge can make that decision. Instead of waiting for a vague request to produce a weak first attempt, improve can research context and ask focused questions. The hook-level structure also lets conditional guidance appear at the point where it is useful, such as immediately before a long-running Bash command or when a research subagent starts.

The README reports a v0.4.0 skill-based architecture with hook-level evaluation and claims a 31% token reduction. That is a project claim, not an independently measured result available from the repository description. Clear prompts are documented as having zero skill overhead, while vague prompts use the skill and can incur additional evaluation work. The practical trade-off is therefore prompt quality versus extra interaction for requests that the evaluator classifies as vague.

The repository is not archived, and its last push was on 2026-10-01. Releases v0.6.1, v0.6.2, and v0.6.3 are listed, including changes for plan-mode nudges, hooks.json schema handling, machine-event bypass, and UTF-8 decoding on all platforms. Those release notes indicate recent maintenance, but they do not establish compatibility with every Claude Code release. The repository is licensed under MIT. The license permits use and modification subject to its terms, but this review does not provide legal advice. Review LICENSE before redistribution or commercial integration.

Limits and a different approach to prompt quality

This plugin is not a deterministic prompt formatter. The README does not show a supported API for rewriting a prompt into a fixed format, and the decision to clarify, plan, or proceed is made through Claude's interpretation of the conversation. A false trigger can add unnecessary questions or planning language, although the README says keyword-gated nudges begin with a condition so they can be dismissed cheaply.

It is also the wrong tool when the user needs a strict programmatic transformation, such as converting a known template into another template with no model judgment. For that use case, a small Python script that applies explicit transformations would be more predictable. The actual difference is that claude-code-prompt-improver adds event-aware context and may research, question, plan, or route work, while a conventional script follows fixed rules and returns a fixed result.

The project also depends on Claude Code features and event names. AskUserQuestion support is required for its clarification path, and the documented hooks are tied to Claude Code configuration. The README does not document offline operation, rollback behavior, or a compatibility policy across future Claude Code versions.

Editorial conclusion

Adopt this plugin when you repeatedly rely on Claude Code for vague, multi-step, or tool-heavy requests, but do not adopt it if you need deterministic transformations or a fully silent workflow. Check Claude Code 2.0.22 compatibility, the installed hook configuration, and the behavior of your first real prompt before committing to it.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. severity1/claude-code-prompt-improver on GitHub