Skip to content

CLAUDE.md

Latest commit

 

History

History
152 lines (124 loc) · 6.3 KB

CLAUDE.md

File metadata and controls

152 lines (124 loc) · 6.3 KB

Claude Code Prompt Improver

This file provides guidance to Claude Code when working with code in this repository.

Overview

A UserPromptSubmit hook plugin that enriches vague prompts before Claude Code executes them. Uses skill-based architecture with hook-level evaluation for efficient prompt clarity assessment.

Core functionality:

  • Intercepts prompts via UserPromptSubmit hook
  • Evaluates clarity using conversation history
  • Clear prompts: proceeds immediately with minimal overhead
  • Vague prompts: invokes prompt-improver skill for research and clarification
  • Uses AskUserQuestion tool for targeted clarifying questions (1-6 questions)

Build & Development Commands

Testing:

  • Run all tests: pytest tests/ or python -m pytest
  • Run specific test suite:
    • Hook tests: pytest tests/test_hook.py
    • Skill tests: pytest tests/test_skill.py
    • Integration tests: pytest tests/test_integration.py

Installation:

  • Add marketplace: claude plugin marketplace add severity1/severity1-marketplace
  • Via marketplace: claude plugin install prompt-improver@severity1-marketplace
  • Local dev: claude plugin marketplace add /path/to/claude-code-prompt-improver/.dev-marketplace/.claude-plugin/marketplace.json then claude plugin install prompt-improver@local-dev
  • Manual hook: cp scripts/improve-prompt.py ~/.claude/hooks/ && chmod +x ~/.claude/hooks/improve-prompt.py

Architecture

Hook Layer (scripts/improve-prompt.py):

  • Evaluation orchestrator - reads stdin JSON, writes stdout JSON
  • Handles bypass prefixes: * (skip), / (slash commands), # (memorize)
  • Wraps prompts with evaluation instructions for clarity assessment
  • Claude evaluates clarity using conversation history
  • If vague: instructs Claude to invoke prompt-improver skill

Skill Layer (skills/prompt-improver/):

  • SKILL.md: Research and question workflow
    • 4-phase process: Research, Questions, Clarify, Execute
    • Assumes prompt already determined vague by hook
    • Links to reference files for progressive disclosure
  • references/: Detailed guides loaded on-demand
    • question-patterns.md: Question templates and effective patterns
    • research-strategies.md: Context gathering strategies
    • examples.md: Real prompt transformations

Directory structure:

  • scripts/ - Hook implementation
  • skills/prompt-improver/ - Skill and reference files
  • tests/ - Test suite (hook, skill, integration)
  • hooks/ - Hook configuration (hooks.json, auto-discovered)
  • .claude-plugin/ - Plugin metadata

Code Conventions

Hook output format:

  • JSON structure following Claude Code specification
  • Format: {"hookSpecificOutput": {"hookEventName": "UserPromptSubmit", "additionalContext": "..."}}
  • Exit code 0 for all success paths
  • Hook commands use python3 || python fallback for Windows compatibility

Bypass prefixes:

  • * prefix: Skip evaluation entirely, strip prefix from prompt
  • / prefix: Slash commands bypass automatically
  • # prefix: Memorize commands bypass automatically

File paths:

  • Use forward slashes (Unix-style) per Claude Code standards
  • All paths in plugin configuration use forward slashes

Skill structure:

  • YAML frontmatter with name and description
  • Skill name: lowercase, hyphens, max 64 chars
  • Description: under 1024 chars, includes activation triggers
  • Reference files: self-contained, one-level deep
  • Writing style: imperative/infinitive form (avoid "you/your")

Testing:

  • Tests use pytest-compatible functions (no test classes)
  • Hook tests run the script via subprocess and validate JSON output
  • Skill tests validate file structure, frontmatter, and references
  • Integration tests verify end-to-end flow and architecture separation
  • Python standard library only (json, sys, subprocess, pathlib, re)

Detected Patterns

Progressive disclosure:

  • Clear prompts: evaluation only, no skill load
  • Vague prompts: evaluation + skill load + references
  • Reference materials load only when needed
  • Zero context penalty for unused reference materials

Evaluation flow:

  1. Hook wraps prompt with evaluation instructions
  2. Claude evaluates using conversation history
  3. If clear: proceed immediately
  4. If vague: invoke prompt-improver skill, then research, questions, execute

Research and questioning:

  • Create dynamic research plan via TodoWrite
  • Research what needs clarification (not just the project)
  • Ground questions in research findings (not generic assumptions)
  • Support 1-6 questions for complex scenarios
  • Use conversation history to avoid redundant exploration

Git Insights

Key architectural decisions:

  • Migrated from hook-only to skill-based architecture for significant token reduction on clear prompts
  • Hook auto-discovery: hooks/hooks.json at standard location removes need for hooks field in plugin.json
  • Plugin distributed via severity1-marketplace for easy installation
  • Progressive disclosure pattern chosen to minimize context overhead for the common case (clear prompts)

Evolution:

  • Started as embedded evaluation logic in hook script
  • Extracted skill layer to separate evaluation (hook) from enrichment (skill)
  • Added marketplace support for distribution

Best Practices

  • Keep hook script minimal - it runs on every prompt submission
  • Never add heavy imports or network calls to the hook script
  • Reference files should be self-contained so they work when loaded independently
  • Test bypass prefixes whenever modifying hook logic to prevent breaking slash commands
  • When adding new bypass prefixes, update both the hook script and the conventions section

Design Philosophy

  • Rarely intervene - Most prompts pass through unchanged
  • Trust user intent - Only ask when genuinely unclear
  • Use conversation history - Avoid redundant exploration
  • Max 1-6 questions - Enough for complex scenarios, still focused
  • Transparent - Evaluation visible in conversation