| 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.
| Thought | Reality |
|---|
| "It's too vague / not best-practice / inconsistent" | Not actionable. Which specific behavior fails? |
| "I have enough context" / "I'll assume the user wants…" | If you can't name the specific failure, you don't. Ask. |
| "I'm the expert" / "This is how I'd write it" | Authority doesn't bypass a concrete issue. You're not the user. |
| "Based on general best practices…" | Use documented practices. Cite the guidance. |
| "Structure is always better" | Structure solves structure problems, not all problems. |
| "Time pressure — demo tomorrow" | Pressure is when the worst changes get made. |
| "This is obviously an improvement" | Obvious to you ≠ solving the user's actual problem. |
| Making 10+ changes to a short prompt | Stop. What specific problem are you solving? |
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 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:
- What specific best practice it applies
- What problem it solves
- Before/after
Do NOT make changes without connecting them to documented guidance.
Quick Reference: Issue → Fix
| Issue | Fix |
|---|
| Output too narrow / not generalized | State scope explicitly ("every section", "all cases") |
| Claude doesn't explain reasoning | Ask it to explain its reasoning, or raise effort |
| Claude is too verbose | "Be concise" or "Respond in X sentences" |
| Claude is too terse | "Provide detailed explanations" |
| Claude suggests but doesn't act | Change "Can you…" to imperative "Do X" |
| Instruction isn't followed | Add context for WHY it matters |
| Examples not matching output | Ensure examples show the exact desired format |
| CLAUDE.md too long / ignored | Cut lines that wouldn't cause a mistake if removed (target <200) |
