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)

Required Process

Step 1: Understand Before Changing

Before ANY modifications:

1. Ask what specific behaviors are underperforming
2. Ask what the prompt should achieve that it currently doesn't
3. 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:

1. What specific best practice it applies
2. What problem it solves
3. 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

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.