severity1/claude-code-prompt-improver

What it solves

Claude Code Prompt Improver reduces the number of correction cycles between a user and an AI agent by ensuring the agent has the right context before it acts. It prevents the "bad first attempt" by identifying vague prompts and injecting necessary constraints or clarifications before the model executes a task.

How it works

The project uses a declarative hook engine that monitors three specific events: prompt submission, tool use, and subagent starts. When an event triggers, the engine evaluates the prompt against a registry of "nudges" (JSON-defined rules).

• For clear prompts: The system adds a small evaluation overhead and proceeds immediately.
• For vague prompts: It invokes a specialized prompt-improver skill that performs research (using tools like Glob and Grep), gathers context, and asks the user 1-6 grounded questions to clarify intent.
• Targeted Nudges: Specific rules fire based on keywords or conditions (e.g., suggesting a plan for complex tasks or recommending background execution for long-running commands).

Who it’s for

Developers using Claude Code who want to increase the accuracy of first-time outputs and reduce the time spent manually correcting AI-generated code or architectural decisions.

Highlights

• Skill-based Architecture: Uses progressive disclosure to load research and question logic only when a prompt is deemed vague, reducing token overhead.
• Curation of Nudges: Includes built-in nudges for approach assessment, workflow planning, output readability, and subagent routing.
• Low Friction: Most prompts pass through unchanged; users can bypass evaluation entirely using prefixes like *.
• Declarative Configuration: New context-injection rules can be added via simple JSON files without modifying Python code.