version: "1.0.0" name: improving-prompts description: Use when optimizing CLAUDE.md, AGENTS.md, custom commands, or skill files — diagnose the concrete failure first, then apply current documented Anthropic best practices (explicit instructions, context/motivation, examples, output and verbosity control, thinking/effort, CLAUDE.md size and skill-description rules) instead of inventing improvements. Triggers when a prompt isn't followed, a skill won't activate, CLAUDE.md is too long or ignored, or migrating prompts to current Claude models.

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