Prompt Improver

Overview

A skill that analyzes and improves prompts based on general LLM/agent best practices. It focuses on verifiability, clear scope, explicit constraints, and context economy so the agent can execute with minimal back-and-forth.

If you are running in Claude Code, also read references/claude.md and apply the additional Claude-specific techniques. If you are running in Codex CLI, also read references/codex.md and apply the additional Codex-specific techniques.

When the input is a document that instructs an agent (e.g., plan files, AGENTS.md, system instruction docs), treat the document as the improvement target; identify issues and propose concrete improvements, and include a revised draft when helpful.

Workflow

Step 0: Classify Task and Complexity

Classify the task and decide whether an explicit exploration/planning phase should be recommended:

• Task type: bugfix, feature, refactor, research, UI/visual, docs, ops
• Complexity: single-file/small change vs multi-file/uncertain impact
• Risk: data safety, security, compatibility, performance
• Input type: prompt vs agent-instruction document (plan files, AGENTS.md, system instruction docs)

If the task is complex or ambiguous, the improved prompt should explicitly request an exploration/planning phase before implementation.

Step 1: Analyze the Prompt

Analyze the user-provided prompt from the following perspectives:

1. Verifiability: Does it include means for Claude to verify its own work?
2. Specificity: Are files, scenarios, and constraints clearly specified?
3. Context: Is necessary background information provided?
4. Scope: Is the task scope appropriately defined?
5. Expected Outcome: Are success criteria clear?
6. Constraints: Are language/runtime versions, dependencies, security, or compatibility requirements specified?
7. Context Economy: Is the prompt concise and focused, without unnecessary information?
8. Execution Preference: Is it clear whether the model should implement, propose, or just analyze?

Step 2: Identify Issues

Check for the following anti-patterns:

Step 3: Create Improved Prompt

Apply best practices to create an improved version:

Add Verifiability

Before: "implement a function that validates email addresses"
After: "write a validateEmail function. test cases: user@example.com is true, invalid is false, user@.com is false. run the tests after implementing"

Add Specific Context

Before: "fix the login bug"
After: "users report that login fails after session timeout. check the auth flow in src/auth/, especially token refresh. write a failing test that reproduces the issue, then fix it"

Add Reference to Existing Patterns

Before: "add a calendar widget"
After: "look at how existing widgets are implemented on the home page to understand the patterns. HotDogWidget.php is a good example. follow the pattern to implement a new calendar widget with month selection and pagination"

Add Context Economy

Before: "here is a long unrelated history ... fix the dropdown"
After: "fix the dropdown in src/ui/Dropdown.tsx. issue: keyboard navigation skips items. keep the prompt focused; omit unrelated history"

Add Rich Context Inputs

Before: "build fails"
After: "build fails with this error: [paste error]. run the smallest relevant test command. if needed, read the build script and package config"

Add Explicit Exploration/Planning When Needed

Before: "refactor auth to support OAuth"
After: "first explore src/auth and summarize current flow, then propose a plan. after approval, implement with tests"

When information is missing, include explicit questions inside the improved prompt and do not assume defaults.

Example: Bugfix

Before: "search is broken"
After: "users report search returns empty results for queries with hyphens. reproduce in src/search/. paste the error log if any. write a failing test for 'foo-bar' returning results, fix the root cause, run: pnpm test --filter search"

Example: UI/Visual

Before: "make the dashboard look better"
After: "implement the attached screenshot for the dashboard header in src/ui/DashboardHeader.tsx. match spacing and typography. take a new screenshot and list any differences. run: pnpm lint"

Example: Refactor

Before: "clean up the auth code"
After: "inspect src/auth and list duplication hotspots. propose a refactor plan scoped to one module. after approval, remove duplication without changing behavior. add a targeted test if coverage is missing. run the smallest relevant test command"

Example: Research

Before: "why is this API slow?"
After: "explore request flow around src/api/. summarize likely bottlenecks with evidence (logs, timings). propose 2-3 hypotheses and what data is needed to confirm. do not implement yet. if needed, ask for access to profiling output"

Example: Ops

Before: "deployment failed"
After: "deploy fails with error: [paste log]. identify the failing step in scripts/deploy.sh and related CI config. suggest a fix and a rollback plan. run: ./scripts/deploy.sh --dry-run (if available)"

Example: Docs

Before: "update the README"
After: "update README.md to include install + dev steps based on existing scripts. keep it concise. confirm commands exist and match actual scripts"

Step 4: Output Format

Output in the following format:

## Prompt Analysis

### Original Prompt
[User-provided prompt]

### Issues
- [Issue 1 and its impact]
- [Issue 2 and its impact]
...

### Missing Information (Questions to Ask)
The following questions should be answered to make the prompt more effective:
- [Question 1] (Why it is needed)
- [Question 2] (Why it is needed)
...

### Verification Plan
- Commands to run (tests, build, lint, screenshots)
- Expected results or acceptance criteria

### Exploration/Planning Recommendation
- Recommend exploration/planning first? [Yes/No] and why

### Execution Preference
- Implement now / propose plan only / analyze only
- Any constraints on response length or format

### Improved Prompt
[The improved prompt]

### Document Improvement Suggestions (if applicable)
- [Issue and concrete improvement for the instruction document]
- [Issue and concrete improvement for the instruction document]

### Revised Document (optional)
[A revised draft of the instruction document when helpful]

### Improved Prompt Template (optional)
Use this as a fill-in template if the user wants a reusable prompt format:

[Task]

• Goal:
• Target files/paths (@...):
• Constraints (runtime/version/deps/security/compat):
• Context (symptom, logs, repro, links):

[Verification]

• Commands:
• Expected results:
• UI checks (screenshots/visual diffs):

[Exploration/Planning]

• Do exploration/planning first? (Yes/No) + reason:

[Execution Preference]

• Implement now / plan only / analyze only
• Output format (concise report, patch summary, checklist, etc.)

### Short Prompt Template (optional)
Use this when the user wants the shortest effective prompt:

Goal: ... Targets: path1/path2 Context: symptom + repro + logs Constraints: runtime/deps/compat Verify: command + expected result Explore/Plan: yes/no (why) Execute: implement / plan only / analyze only Output: concise format

### Improvement Points
1. [Explanation of improvement 1]
2. [Explanation of improvement 2]
...

### Additional Recommendations (optional)
- [Whether to do exploration/planning first]
- [Whether to parallelize or delegate investigation]
- [Whether preliminary research is needed]
- [Ways to reduce context usage]

Reference: Best Practices Checklist

Best practices to reference when improving prompts:

Provide Verification Methods

• Include test cases
• Specify expected output
• For UI changes, request screenshot comparison
• Add "run the tests" or "verify the build succeeds"
• Include explicit commands to run

Explore → Plan → Implement Order

• Use an exploration/planning phase first for complex tasks
• Create a plan before implementation
• Small fixes don't need a formal plan
• When uncertain, ask clarifying questions before coding

Include Specific Context

• Paste error messages
• Specify existing patterns
• Clarify edge cases
• State environment constraints (runtime, language versions, dependencies)

Use Rich Inputs

• Paste logs and stack traces
• Provide URLs for docs or API references
• Attach or paste large text outputs when needed

Manage Context Window

• Keep prompts concise and focused
• Remove unrelated history or speculation
• Ask for missing info instead of guessing

Leverage Parallelism/Delegation

• For research tasks: request parallel investigation or summaries
• For code review: request an independent review pass
• Keeps the main task focused

Patterns to Avoid

• Vague instructions like "make it better" or "improve it"
• Implementation requests without verification methods
• Multiple unrelated tasks at once
• Requesting changes to files not yet read
• Large context dumps with no clear signal