{"id":32495867,"url":"https://github.com/severity1/claude-code-prompt-improver","last_synced_at":"2026-02-14T05:21:18.727Z","repository":{"id":319401933,"uuid":"1078603411","full_name":"severity1/claude-code-prompt-improver","owner":"severity1","description":"Intelligent prompt improver hook for Claude Code. Type vibes, ship precision.","archived":false,"fork":false,"pushed_at":"2025-12-13T09:08:03.000Z","size":3221,"stargazers_count":974,"open_issues_count":1,"forks_count":91,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-12-14T23:09:01.528Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/severity1.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-18T03:03:21.000Z","updated_at":"2025-12-14T17:57:52.000Z","dependencies_parsed_at":"2025-10-19T02:13:43.567Z","dependency_job_id":"07fb2926-b763-4cc9-b891-ec7ffc5f9088","html_url":"https://github.com/severity1/claude-code-prompt-improver","commit_stats":null,"previous_names":["severity1/claude-prompt-optimizer"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/severity1/claude-code-prompt-improver","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/severity1%2Fclaude-code-prompt-improver","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/severity1%2Fclaude-code-prompt-improver/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/severity1%2Fclaude-code-prompt-improver/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/severity1%2Fclaude-code-prompt-improver/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/severity1","download_url":"https://codeload.github.com/severity1/claude-code-prompt-improver/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/severity1%2Fclaude-code-prompt-improver/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29437538,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-14T03:34:37.767Z","status":"ssl_error","status_checked_at":"2026-02-14T03:34:09.092Z","response_time":53,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-10-27T14:00:52.811Z","updated_at":"2026-02-14T05:21:18.720Z","avatar_url":"https://github.com/severity1.png","language":"Python","readme":"# Claude Code Prompt Improver\n\nA UserPromptSubmit hook that enriches vague prompts before Claude Code executes them. Uses the AskUserQuestion tool (Claude Code 2.0.22+) for targeted clarifying questions.\n\n![Demo](assets/demo.gif)\n\n## What It Does\n\nIntercepts prompts and evaluates clarity. Claude then:\n- Checks if the prompt is clear using conversation history\n- For clear prompts: proceeds immediately (zero overhead)\n- For vague prompts: invokes the `prompt-improver` skill to create research plan, gather context, and ask 1-6 grounded questions\n- Proceeds with original request using the clarification\n\n**Result:** Better outcomes on the first try, without back-and-forth.\n\n**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.\n\n## How It Works\n\n```mermaid\nsequenceDiagram\n    participant User\n    participant Hook\n    participant Claude\n    participant Skill\n    participant Project\n\n    User-\u003e\u003eHook: \"fix the bug\"\n    Hook-\u003e\u003eClaude: Evaluation prompt (~189 tokens)\n    Claude-\u003e\u003eClaude: Evaluate using conversation history\n    alt Vague prompt\n        Claude-\u003e\u003eSkill: Invoke prompt-improver skill\n        Skill--\u003e\u003eClaude: Research and question guidance\n        Claude-\u003e\u003eClaude: Create research plan (TodoWrite)\n        Claude-\u003e\u003eProject: Execute research (codebase, web, docs)\n        Project--\u003e\u003eClaude: Context\n        Claude-\u003e\u003eUser: Ask grounded questions (1-6)\n        User-\u003e\u003eClaude: Answer\n        Claude-\u003e\u003eClaude: Execute original request with answers\n    else Clear prompt\n        Claude-\u003e\u003eClaude: Proceed immediately (no skill load)\n    end\n```\n\n## Installation\n\n**Requirements:** Claude Code 2.0.22+ (uses AskUserQuestion tool for targeted clarifying questions)\n\n### Option 1: Via Marketplace (Recommended)\n\n**1. Add the marketplace:**\n```bash\nclaude plugin marketplace add severity1/severity1-marketplace\n```\n\n**2. Install the plugin:**\n```bash\nclaude plugin install prompt-improver@severity1-marketplace\n```\n\n**3. Restart Claude Code**\n\nVerify installation with `/plugin` command. You should see the prompt-improver plugin listed.\n\n### Option 2: Local Plugin Installation (Recommended for Development)\n\n**1. Clone the repository:**\n```bash\ngit clone https://github.com/severity1/claude-code-prompt-improver.git\ncd claude-code-prompt-improver\n```\n\n**2. Add the local marketplace:**\n```bash\nclaude plugin marketplace add /absolute/path/to/claude-code-prompt-improver/.dev-marketplace/.claude-plugin/marketplace.json\n```\n\nReplace `/absolute/path/to/` with the actual path where you cloned the repository.\n\n**3. Install the plugin:**\n```bash\nclaude plugin install prompt-improver@local-dev\n```\n\n**4. Restart Claude Code**\n\nVerify installation with `/plugin` command. You should see \"1 plugin available, 1 already installed\".\n\n### Option 3: Manual Installation\n\n**1. Copy the hook:**\n```bash\ncp scripts/improve-prompt.py ~/.claude/hooks/\nchmod +x ~/.claude/hooks/improve-prompt.py\n```\n\n**2. Update `~/.claude/settings.json`:**\n```json\n{\n  \"hooks\": {\n    \"UserPromptSubmit\": [\n      {\n        \"hooks\": [\n          {\n            \"type\": \"command\",\n            \"command\": \"python3 ~/.claude/hooks/improve-prompt.py\"\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\n## Usage\n\n**Normal use:**\n```bash\nclaude \"fix the bug\"      # Hook evaluates, may ask questions\nclaude \"add tests\"        # Hook evaluates, may ask questions\n```\n\n**Bypass prefixes:**\n```bash\nclaude \"* add dark mode\"                    # * = skip evaluation\nclaude \"/help\"                              # / = slash commands bypass\nclaude \"# remember to use rg over grep\"     # # = memorize bypass\n```\n\n**Vague prompt:**\n```bash\n$ claude \"fix the error\"\n```\n\nClaude asks:\n```\nWhich error needs fixing?\n  ○ TypeError in src/components/Map.tsx (recent change)\n  ○ API timeout in src/services/osmService.ts\n  ○ Other (paste error message)\n```\n\nYou select an option, Claude proceeds with full context.\n\n**Clear prompt:**\n```bash\n$ claude \"Fix TypeError in src/components/Map.tsx line 127 where mapboxgl.Map constructor is missing container option\"\n```\n\nClaude proceeds immediately without questions.\n\n## Design Philosophy\n\n- **Rarely intervene** - Most prompts pass through unchanged\n- **Trust user intent** - Only ask when genuinely unclear\n- **Use conversation history** - Avoid redundant exploration\n- **Max 1-6 questions** - Enough for complex scenarios, still focused\n- **Transparent** - Evaluation visible in conversation\n\n## Architecture\n\n**v0.4.0:** Skill-based architecture with hook-level evaluation.\n\n**Hook (scripts/improve-prompt.py) - Evaluation Orchestrator:**\n- Intercepts via stdin/stdout JSON (~70 lines)\n- Handles bypass prefixes: `*`, `/`, `#`\n- Wraps prompts with evaluation instructions (~189 tokens)\n- Claude evaluates clarity using conversation history\n- If vague: Instructs Claude to invoke `prompt-improver` skill\n\n**Skill (skills/prompt-improver/) - Research \u0026 Question Logic:**\n- **SKILL.md**: Research and question workflow (~170 lines)\n  - Assumes prompt already determined vague by hook\n  - 4-phase process: Research → Questions → Clarify → Execute\n  - Links to reference files for progressive disclosure\n- **references/**: Detailed guides loaded on-demand\n  - `question-patterns.md`: Question templates (200-300 lines)\n  - `research-strategies.md`: Context gathering (300-400 lines)\n  - `examples.md`: Real transformations (200-300 lines)\n\n**Flow for Clear Prompts:**\n1. Hook wraps with evaluation prompt (~189 tokens)\n2. Claude evaluates: prompt is clear\n3. Claude proceeds immediately (no skill invocation)\n4. **Total overhead: ~189 tokens**\n\n**Flow for Vague Prompts:**\n1. Hook wraps with evaluation prompt (~189 tokens)\n2. Claude evaluates: prompt is vague\n3. Claude invokes `prompt-improver` skill\n4. Skill loads research/question guidance\n5. Claude creates research plan, gathers context, asks questions\n6. **Total overhead: ~189 tokens + skill load**\n\n**Progressive Disclosure Benefits:**\n- Clear prompts: Never load skill (zero skill overhead)\n- Vague prompts: Only load skill and relevant reference files\n- Detailed guidance available without bloating all prompts\n- Zero context penalty for unused reference materials\n\n**Why main session (not subagent)?**\n- Has conversation history\n- No redundant exploration\n- More transparent\n- More efficient overall\n\n**Manual Skill Invocation:**\nYou can also invoke the skill manually without the hook:\n```\nUse the prompt-improver skill to research and clarify: \"add authentication\"\n```\n\n## Token Overhead\n\n**v0.4.0 Update:** 31% reduction through hook-level evaluation\n\n- **Per prompt (v0.4.0):** ~189 tokens (evaluation prompt)\n- **Per prompt (v0.3.x):** ~275 tokens (embedded evaluation logic)\n- **Reduction:** ~86 tokens saved per prompt (31% decrease)\n- **30-message session:** ~5.7k tokens (~2.8% of 200k context, down from 4.1%)\n- **Trade-off:** Minimal overhead for better first-attempt results\n\n**Clear prompts benefit:**\n- Evaluation happens in hook (~189 tokens)\n- Claude proceeds immediately (no skill load)\n- Zero skill overhead for clear prompts\n\n**Vague prompts:**\n- Evaluation in hook (~189 tokens)\n- Skill loads only when needed for research/questions\n- Progressive disclosure: reference files load on-demand\n\n## FAQ\n\n**Does this work on all prompts?**\nYes, unless you use bypass prefixes (`*`, `/`, `#`).\n\n**Will it slow me down?**\nOnly slightly when it asks questions. Faster overall due to better context.\n\n**Will I get bombarded with questions?**\nNo. It rarely intervenes, passes through most prompts, and asks max 1-6 questions.\n\n**Can I customize behavior?**\nIt adapts automatically using conversation history, dynamic research planning, and CLAUDE.md.\n\n**What if I don't want improvement?**\nUse `*` prefix: `claude \"* your prompt here\"`\n\n## License\n\nMIT\n","funding_links":[],"categories":["Tools \u0026 Utilities","Python"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fseverity1%2Fclaude-code-prompt-improver","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fseverity1%2Fclaude-code-prompt-improver","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fseverity1%2Fclaude-code-prompt-improver/lists"}