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.