claude-code-prompt-improver
Intelligent prompt improver hook for Claude Code. Type vibes, ship precision.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/severity1-claude-code-prompt-improver)HTML
<a href="/listings/severity1-claude-code-prompt-improver"><img src="/api/listings/severity1-claude-code-prompt-improver/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
**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.
Option 2: Local Plugin Installation (Recommended for Development)
**1. Clone the repository:**
git clone https://github.com/severity1/claude-code-prompt-improver.git cd claude-code-prompt-improver
**2. Add the local marketplace:**
claude plugin marketplace add /absolute/path/to/claude-code-prompt-improver/.dev-marketplace/.claude-plugin/marketplace.json
Replace `/absolute/path/to/` with the actual path where you cloned the repository.
**3. Install the plugin:**
claude plugin install prompt-improver@local-dev
**4. Restart Claude Code**
Verify installation with `/plugin` command. You should see "1 plugin available, 1 already installed".
Option 3: Manual Installation
**1. Copy the engine, rules, builtins, and nudges:**
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 engine resolves `nudges/` relative to its own location and loads it recursively (`nudges/<EventName>/*.json`), so copy the whole `nudges/` tree and keep `scripts/` and `nudges/` siblings under the same parent.
**2. Update `~/.claude/settings.json`:**
{
"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"
}
]
}
],
"SubagentStart": [
{
"hooks": [
{
"type": "command",
"command": "python3 ~/.claude/hooks/prompt-improver/scripts/engine.py SubagentStart"
}
]
}
]
}
}What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 391 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- # 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
- ```mermaid
- 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:**
- ```bash
- claude plugin marketplace add severity1/severity1-marketplace
- ```
- **2. Install the plugin:**
- ```bash
- claude plugin install prompt-improver@severity1-marketplace
- ```
- **3. Restart Claude Code**
- Verify installation with `/plugin` command. You should see the prompt-improver plugin listed.
- ### Option 2: Local Plugin Installation (Recommended for Development)
- **1. Clone the repository:**
- ```bash
- git clone https://github.com/severity1/claude-code-prompt-improver.git
- cd claude-code-prompt-improver
- ```
- **2. Add the local marketplace:**
- ```bash
- claude plugin marketplace add /absolute/path/to/claude-code-prompt-improver/.dev-marketplace/.claude-plugin/marketplace.json
- ```
- Replace `/absolute/path/to/` with the actual path where you cloned the repository.
- **3. Install the plugin:**
- ```bash
- claude plugin install prompt-improver@local-dev
- ```
- **4. Restart Claude Code**
- Verify installation with `/plugin` command. You should see "1 plugin available, 1 already installed".
- ### Option 3: Manual Installation
- **1. Copy the engine, rules, builtins, and nudges:**
- ```bash
- 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 engine resolves `nudges/` relative to its own location and loads it recursively (`nudges/<EventName>/*.json`), so copy the whole `nudges/` tree and keep `scripts/` and `nudges/` siblings under the same parent.
- **2. Update `~/.claude/settings.json`:**
- ```json
- {
- "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"
- }
- ]
- }
- ],
- "SubagentStart": [
- {
- "hooks": [
- {
- "type": "command",
- "command": "python3 ~/.claude/hooks/prompt-improver/scripts/engine.py SubagentStart"
- }
- ]
- }
- ]
- }
- }
- ```
- ## Usage
- **Normal use:**
- ```bash
- claude "fix the bug" # Hook evaluates, may ask questions
- claude "add tests" # Hook evaluates, may ask questions
- ```
- **Bypass prefixes:**
- ```bash
- claude "* add dark mode" # * = skip evaluation
- claude "/help" # / = slash commands bypass
- claude "# remember to use rg over grep" # # = memorize bypass
- ```
- Harness messages that arrive as prompts (for example `<task-notification>` or `<system-reminder>`) also bypass every prompt nudge.
- **Vague prompt:**
- ```bash
- $ claude "fix the error"
- ```
- Claude asks:
- ```
- Which error needs fixing?
- ○ TypeError in src/components/Map.tsx (recent change)
- ○ API timeout in src/services/osmService.ts
- ○ Other (paste error message)
- ```
- You select an option, Claude proceeds with full context.
- **Clear prompt:**
- ```bash
- $ claude "Fix TypeError in src/components/Map.tsx line 127 where mapboxgl.Map constructor is missing container option"
- ```
- Claude proceeds immediately without questions.
- ## Design Philosophy
- - **Improve the prompt-to-output path** - the goal is a right first output. Clarifying a vague prompt is one way; injecting a constraint the user would otherwise add by hand after a bad attempt is another. Both count.
- - **Rarely intervene** - most prompts pass through unchanged; each nudge fires only when it applies.
- - **Fire wide, self-cancel cheap** - a missed nudge costs a full correction loop, a false fire costs a few tokens Claude ignores. That asymmetry justifies high-recall gates, so every nudge leads with a condition ("If this is X... if not, ignore") and dismisses itself when it does not fit.
- - **Trust user intent** - only ask when genuinely unclear; never block.
- - **Max 1-6 questions** - enough for complex scenarios, still focused.
- - **Transparent** - injected context is visible in the conversation.
- ## Architecture
- **Declarative hook engine driven by a JSON nudge registry.** One engine dispatches every hook event; each capability is a data row in `nudges/*.json`, not a separate script. Adding an inject-context nudge is a single JSON file with zero Python changes.
- **Engine (scripts/engine.py) - Event Dispatcher:**
- - Invoked as `engine.py <EventName>` (one entry per event in `hooks.json`)
- - Reads stdin once, runs the event's rules, merges `inject_context` fragments by `priority` with a blank-line join, emits one `hookSpecificOutput` object
- - Exits 0 on every path - a missing/unknown event or an event with no rules is a clean no-op that never reads stdin
- - One bad rule is isolated in a `try/except` so it cannot suppress the others
- **Rules (scripts/rules.py) - Loader + Validation:**
- - Loads and validates `nudges/*.json`; invalid rows are skipped with a stderr note (loading never raises into the engine)
- - `validate_rule` enforces: required `id`/`event`, known event, `action` XOR `handler`, action type legal for the event, compilable regexes, allowlisted `builtin`/`handler` names, unique id
- - Owns the event->capability matrix (v1: `inject_context` on `UserPromptSubmit`, `PreToolUse`, `SubagentStart`)
- - Regexes are compiled once per dispatched event, not at file load
- **Builtins (scripts/nudge_builtins.py) - Escape Hatch:**
- - Two allowlist dicts referenced by string name only: `HANDLERS` (`improve`, `workflow`) and `MATCHERS` (`saved_workflow_exists`)
- - A rule with `"handler": "improve"` runs the named handler, which owns its full fragment including bypass logic; a rule with `"criteria": {"builtin": "saved_workflow_exists"}` runs the named matcher
- - No `eval`/`importlib`/`getattr`-on-path: an unknown name is a load-time skip, never an arbitrary import
- - Named `nudge_builtins` (not `builtins`) because the stdlib `builtins` module is loaded before any user code and would permanently shadow a local `builtins.py`
- **Nudges (nudges/*.json) - The Registry:**
- - `improve` - checks whether a submitted prompt is clear enough to act on, and asks for clarification only when it is genuinely vague.
- - `approach-assessment` - when a request looks non-trivial, raises how to carry it out (a subagent, heavier orchestration, or just doing it) and reminds that a spawned subagent needs its context passed explicitly.
- - `workflow` - when a request looks like a multi-step workflow, suggests planning before running and routing each stage to an appropriately sized model.
- - `ask-user-question` - when a request hides a decision that is genuinely the user's (a fork, a real tradeoff, missing requirements), routes it through the AskUserQuestion tool with concrete options, grounds the questions in research when context is thin, and defaults on minor or reversible choices.
- - `plan-mode` - evaluates every prompt: judges whether the task is complex, multi-step, ambiguous, or architectural enough to warrant a plan reviewed before any code is written, and enters plan mode if so. Self-cancels on trivial work. Owns "whether to plan at all"; `approach-assessment` owns "which approach".
- - `plan` - when entering plan mode, encourages a clean, readable plan: terse steps, file-path anchors, no decision history, and a re-read for flaws before presenting.
- - `subagent-routing` - when a research or planning subagent starts, encourages breadth over depth and lean, conclusion-first reporting.
- - `background-exec` - when a long-running command (dev server, watcher, tail) is about to run, suggests running it in the background and polling only the output that matters.
- - `output-readability` - when the response will be a substantial deliverable (report, review, summary, analysis), encourages a human-readable result: lead with the conclusion, prefer sections and tables, keep it terse.
- **Known limitation (workflow nudge):** the keyword filter biases toward recall, so a non-launch mention of "workflow" (e.g. "fix the CI workflow file") may inject inert guidance. The guidance leads with a conditional guard ("If this prompt will run as a dynamic workflow... if not, ignore") so the model self-cancels false positives. No hook can see the post-prompt workflow decision.
- **Skill (skills/prompt-improver/) - Research & Question Logic:**
- - **SKILL.md**: Research and question workflow (~170 lines)
- - Assumes prompt already determined vague by the engine's improve nudge
- - 4-phase process: Research → Questions → Clarify → Execute
- - Links to reference files for progressive disclosure
- - **references/**: Detailed guides loaded on-demand
- - `question-patterns.md`: Question templates (200-300 lines)
- - `research-strategies.md`: Context gathering (300-400 lines)
- - `examples.md`: Real transformations (200-300 lines)
- ## How to Add a Nudge
- A new inject-context nudge is a single JSON file under `nudges/` - no Python changes.
- **1. Drop a file in the event's subdirectory.** Nudges live in `nudges/<EventName>/`, one folder per hook event, and files are named `<priority>-<id>.json` so each folder sorts in merge order:
- ```
- nudges/
- UserPromptSubmit/
- 00-improve.json
- 10-approach-assessment.json
- 20-workflow.json
- 30-output-readability.json
- 40-ask-user-question.json
- 50-plan-mode.json
- PreToolUse/
- 00-plan.json
- 10-background-exec.json
- SubagentStart/
- 00-subagent-routing.json
- ```
- For example, `nudges/UserPromptSubmit/20-kubernetes.json`:
- ```json
- {
- "id": "kubernetes",
- "event": "UserPromptSubmit",
- "description": "What this nudge does and why (never emitted - JSON has no comments).",
- "criteria": {
- "match": ["\\bkubernetes\\b"],
- "flags": ["ignorecase"],
- "non_slash": true
- },
- "action": {
- "type": "inject_context",
- "text": [
- "If this task touches Kubernetes manifests: validate with kubeconform before applying.",
- "If not, ignore this guidance."
- ]
- },
- "priority": 20
- }
- ```
- The parent directory is authoritative: a rule whose `event` field does not match its folder is skipped with a stderr note (so a file in `PreToolUse/` cannot claim `"event": "UserPromptSubmit"`). The filename's priority prefix is cosmetic - the engine sorts fragments by the JSON `priority` field, not the filename, so keep the two in sync. Priority is event-scoped: it only orders rules that share an event (e.g. `improve` at 0 and `workflow` at 20 both merge on `UserPromptSubmit`; `plan` at 0 never competes with them). Pad the prefix to match your widest priority (2 digits is safe for the gap convention 0/10/20/.../50; a priority >= 100 sorts wrong against 2-digit names).
- **2. That's it.** The engine recursively auto-loads every `nudges/**/*.json` on the next prompt. No `hooks.json` edit is needed unless the nudge targets a new event (each event needs one dispatch entry in `hooks.json` and one new `nudges/<EventName>/` folder).
- **Schema reference:**
- | Field | Required | Meaning |
- |-------|----------|---------|
- | `id` | yes | Unique rule id |
- | `event` | yes | `UserPromptSubmit`, `PreToolUse`, or `SubagentStart` |
- | `description` | no | Intent note, never emitted |
- | `action` | one of | `{ "type": "inject_context", "text": [lines], "append_when": [{ "match": [regex], "text": [lines] }] }` |
- | `handler` | one of | String naming a callable in `nudge_builtins.HANDLERS` (escape hatch) |
- | `criteria` | no | `match`/`exclude` (regex arrays), `match_target` (`prompt`\|`tool_name`\|`agent_type`\|`command`; `command` reads nested `tool_input.command`), `non_slash`, `flags`, `builtin` |
- | `bypass` | no | `default` (suppress on `*`/`#`/empty/harness machine events for prompt targets) or `none` |
- | `priority` | no | Merge order (lower first); default 100 |
- Provide exactly one of `action` or `handler`. `text` is an array of lines joined with newlines at load (clean multiline diffs). `append_when` models a conditional clause declaratively (used by the ultracode clause). Invalid rows are skipped with a stderr note; the engine still exits 0.
- **Flow for Clear Prompts:**
- 1. Hook wraps with evaluation prompt (~189 tokens)
- 2. Claude evaluates: prompt is clear
- 3. Claude proceeds immediately (no skill invocation)
- 4. **Total overhead: ~189 tokens**
- **Flow for Vague Prompts:**
- 1. Hook wraps with evaluation prompt (~189 tokens)
- 2. Claude evaluates: prompt is vague
- 3. Claude invokes `prompt-improver` skill
- 4. Skill loads research/question guidance
- 5. Claude creates research plan, gathers context, asks questions
- 6. **Total overhead: ~189 tokens + skill load**
- **Progressive Disclosure Benefits:**
- - Clear prompts: Never load skill (zero skill overhead)
- - Vague prompts: Only load skill and relevant reference files
- - Detailed guidance available without bloating all prompts
- - Zero context penalty for unused reference materials
- **Research dispatch model:**
- - Glob, Grep, WebSearch, WebFetch, and multi-file Read route through `Task/Explore` (Haiku-based, separate context window)
- - Main context handles history mining, single-file Reads of user-named files, Bash/git commands, synthesis, and questions
- - Bash stays in main context because Explore agents cannot run shell commands
- - Every Explore dispatch carries explicit conversation context (file paths, errors, prior decisions) since Explore has no access to prior turns
- - Net effect: search noise lives in cheap subagent tokens, decisions live in main-context tokens
- **Manual Skill Invocation:**
- You can also invoke the skill manually without the hook:
- ```
- Use the prompt-improver skill to research and clarify: "add authentication"
- ```
- ## Token Overhead
- **v0.4.0 Update:** 31% reduction through hook-level evaluation
- - **Per prompt (v0.4.0):** ~189 tokens (evaluation prompt)
- - **Per prompt (v0.3.x):** ~275 tokens (embedded evaluation logic)
- - **Reduction:** ~86 tokens saved per prompt (31% decrease)
- - **30-message session:** ~5.7k tokens (~2.8% of 200k context, down from 4.1%)
- - **Trade-off:** Minimal overhead for better first-attempt results
- **Clear prompts benefit:**
- - Evaluation happens in hook (~189 tokens)
- - Claude proceeds immediately (no skill load)
- - Zero skill overhead for clear prompts
- **Vague prompts:**
- - Evaluation in hook (~189 tokens)
- - Skill loads only when needed for research/questions
- - Progressive disclosure: reference files load on-demand
- ## FAQ
- **Does this work on all prompts?**
- Yes, unless you use bypass prefixes (`*`, `/`, `#`).
- **Will it slow me down?**
- Only slightly when it asks questions. Faster overall due to better context.
- **Will I get bombarded with questions?**
- No. It rarely intervenes, passes through most prompts, and asks max 1-6 questions.
- **Can I customize behavior?**
- It adapts automatically using conversation history, dynamic research planning, and CLAUDE.md.
- **What if I don't want improvement?**
- Use `*` prefix: `claude "* your prompt here"`
- ## License
- MIT
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.