Improving Prompts
Overview
Apply documented Claude 4.5 best practices to existing prompts. Do not invent "improvements" - use the actual guidance from Anthropic.
When to Use
- Optimizing CLAUDE.md or AGENTS.md files
- Improving custom command prompts
- Refining skill instructions
- Migrating prompts from older Claude models to 4.5
When NOT to Use
- Writing new prompts from scratch (just follow best practices directly)
- The prompt is working well and user hasn't identified issues
The Core Problem
Without this skill, agents:
- Invent "best practices" from general knowledge
- Make structural changes without asking what's broken
- Add complexity assuming more structure = better
- Change things to demonstrate value rather than solve problems
Common Rationalizations (Do Not Fall For These)
| Rationalization | Reality |
|---|---|
| "The user said it's too vague" | "Too vague" isn't actionable. What specific behavior fails? |
| "I'm the expert, trust me" | Authority doesn't bypass the need for concrete issues |
| "Time pressure - demo tomorrow" | Pressure is when agents make the worst decisions |
| "The spirit of the skill is to help" | Violating the letter IS violating the spirit |
| "I have enough context" | If you can't name the specific failure, you don't |
| "Structure is always better" | Structure solves structure problems, not all problems |
| "This is obviously an improvement" | Obvious to you ≠ solving the user's actual problem |
Required Process
Step 1: Understand Before Changing
Before ANY modifications:
- Ask what specific behaviors are underperforming
- Ask what the prompt should achieve that it currently doesn't
- If user says "just improve it generally" - ask for at least one concrete issue
What counts as a "concrete issue":
- "Claude ignores my instruction to be concise" ✓
- "The examples I provide don't match the output format" ✓
- "Claude suggests changes but doesn't implement them" ✓
What does NOT count:
- "It's too vague" ✗ (vague about what?)
- "It doesn't follow best practices" ✗ (which practice? what fails?)
- "It's inconsistent" ✗ (inconsistent how? show examples)
Do NOT proceed with generic "improvements" based on assumptions.
Step 2: Reference Actual Best Practices
See references/claude-4.5-best-practices.md for the complete reference. Key principles:
Be explicit with instructions:
- Claude 4.5 follows instructions precisely - vague requests get literal interpretations
- If you want "above and beyond" behavior, explicitly request it
- Example: "Create a dashboard" → "Create a dashboard. Include relevant features and interactions. Go beyond basics."
Add context/motivation:
- Explain WHY a rule exists, not just WHAT the rule is
- Claude generalizes from explanations
- Example: "NEVER use ellipses" → "Never use ellipses because the text-to-speech engine cannot pronounce them"
Be vigilant with examples:
- Examples are followed precisely - ensure they demonstrate desired behavior
- One excellent example beats many mediocre ones
Avoid "think" without extended thinking:
- When extended thinking is disabled, "think" triggers unwanted behavior
- Use alternatives: "consider," "evaluate," "assess," "determine"
Control verbosity explicitly:
- Claude 4.5 defaults to efficiency/conciseness
- If you want summaries or explanations, request them explicitly
Tool usage patterns:
- "Can you suggest changes" → Claude suggests but doesn't implement
- "Make these changes" → Claude implements
- Be explicit about whether to act or advise
Step 3: Preserve What Works
- Do NOT restructure sections that aren't problematic
- Do NOT add complexity unless solving a stated problem
- Do NOT change tone/voice unless specifically requested
- Keep the user's examples if they demonstrate the right behavior
Step 4: Propose Changes with Rationale
For each change, state:
- What specific best practice it applies
- What problem it solves
- Show before/after
Do NOT make changes without connecting them to documented guidance.
Red Flags - You're About to Fail
- "Based on general best practices..." → STOP. Use documented practices.
- "Structure is always better..." → STOP. Ask if structure is the problem.
- "I'll assume the user wants..." → STOP. Ask.
- Making 10+ changes to a short prompt → STOP. What specific problem are you solving?
- "This is how I would write it..." → STOP. You're not the user.
Quick Reference: Claude 4.5 Improvements
| Issue | Fix |
|---|---|
| Claude takes things too literally | Add "Go beyond basics" or explicit scope |
| Claude doesn't explain reasoning | Add "Explain your reasoning" or "Think through this step by step" |
| Claude is too verbose | Add "Be concise" or "Respond in X sentences" |
| Claude is too terse | Add "Provide detailed explanations" |
| Claude suggests but doesn't act | Change "Can you..." to imperative "Do X" |
| Instruction isn't followed | Add context for WHY the instruction matters |
| Examples not matching output | Ensure examples show exact desired format |
Common Mistakes
Overengineering: Adding categories, numbered lists, XML structure to simple prompts that were working fine.
Changing voice: The user's CLAUDE.md reflects their personality. Don't make it sound like documentation.
Assuming problems: Making changes without knowing what's actually broken.
Inventing practices: Claiming something is a "best practice" without reference to actual guidance.