joshuadavidthomas/agent-skills/improving-prompts

Improving Prompts

Overview

Apply current documented Anthropic best practices to existing prompts. Do not invent "improvements" — use the actual guidance.

When to Use

• Optimizing CLAUDE.md or AGENTS.md files
• Improving custom command prompts
• Refining skill instructions
• Migrating prompts to current Claude models (4.x)

When NOT to Use

• Writing new prompts from scratch (just follow best practices directly)
• The prompt is working well and the 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

Stop If You Catch Yourself

These are the failure modes. If you think any of these, stop and get a concrete issue first.

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 the 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" ✓
• "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?)

Do NOT proceed with generic "improvements" based on assumptions.

Step 2: Reference Actual Best Practices

See references/anthropic-best-practices.md for the full reference. Key principles:

Be explicit with instructions: Current models follow instructions literally — vague requests get narrow, literal interpretations. If you want "above and beyond," request it explicitly.

State scope explicitly: Current models won't silently generalize an instruction you gave once. "Apply this to every section, not just the first."

Add context/motivation: Explain WHY a rule exists, not just WHAT. Claude generalizes from explanations. "NEVER use ellipses" → "Never use ellipses because the text-to-speech engine cannot pronounce them."

Be vigilant with examples: Examples are imitated precisely, including unintended patterns. Use 3–5, in <example> tags, aligned with the desired behavior.

Thinking & effort: Prefer general instructions ("think thoroughly"; "verify your answer against [criteria] before finishing") over hand-written step-by-step. The old "avoid the word think without extended thinking" rule no longer applies — current models use adaptive thinking + effort.

Control verbosity explicitly: Opus 4.7 scales length to perceived task complexity. If the workflow needs a fixed length or post-tool summaries, say so.

Tool usage: "Can you suggest changes" → suggestions only. "Make these changes" → edits. Be explicit about act vs. advise.

Dial back aggressive triggering: Prefer "Use X when it helps" over "CRITICAL: You MUST use X" — current models overtrigger and over-explore on aggressive language.

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. Before/after

Do NOT make changes without connecting them to documented guidance.

Quick Reference: Issue → Fix