Immutable. This exact content is served forever at /api/v1/blob/dbfa64530927bdd3.
---
name: crafting-instructions
description: Chooses the right FORMAT for instructions on Claude.ai — project instructions, a skill, or a standalone prompt — and gives the format-specific structure once chosen. Use when the question is which container an instruction belongs in ("should this be a skill or project instructions", "where do I put this", "how do I set up this project", "is this worth a skill"), or when someone has instructions and does not know how to package them. For the writing principles that apply inside any of the three formats, use writing-instructions. For building, testing and packaging a complete skill directory, use creating-skill.
metadata:
version: 0.4.0
---
# Crafting Instructions for Claude
Choose the format for instructions on Claude.ai — Project instructions, Skills,
or standalone prompts — and structure them for the format chosen.
**Overlap notice.** The Core Optimization Principles below also appear in
`writing-instructions`, which carries them in more depth alongside model-aware
calibration, complexity scaling and a quality checklist. The two skills were
written independently and never reconciled; a 2026-08-24 retrieval measurement
put their descriptions at 0.843 cosine, the most confusable pair in the
92-skill catalogue. Until they are merged, this skill owns the **format
decision** and `writing-instructions` owns **how to write well inside a
format**.
## Decision Framework: Which Format to Use?
Ask these questions to determine the right format:
### Use PROJECT INSTRUCTIONS when:
- Context needs to persist for ALL conversations in a workspace
- Multiple team members collaborate with shared knowledge
- Background knowledge required for specific initiative
- Custom behavior scoped to one project only
**Signals:** "for this project", "all conversations about X", "team workspace", "project-specific"
### Use SKILL when:
- Capability needed across MULTIPLE contexts/projects
- Procedural knowledge that applies broadly
- Instructions should activate automatically when relevant
- Want portable expertise that loads on-demand
**Signals:** "every time I", "whenever", "reusable", "across projects", "teach Claude how to"
### Use STANDALONE PROMPT when:
- One-off request with immediate context
- Ad-hoc instructions for single use
- Conversational refinement
- No need for persistence
**Signals:** "for this task", "right now", "just this once", "can you"
### Combined Approaches:
**Project + Skill:**
- Project: Persistent context (market data, product specs)
- Skill: Reusable methods (analysis framework, report templates)
- Use when: Need both workspace context AND portable capabilities
**Skill + Prompt:**
- Skill: General expertise (code review standards)
- Prompt: Specific context ("review this PR for security")
- Use when: Foundational capability + immediate direction
## Core Optimization Principles
These apply to ALL instruction formats:
### 1. Imperative Construction
Frame as direct action commands, not suggestions:
- ❌ "Consider creating X" → ✅ "Create X when conditions Y"
- ❌ "You might want to" → ✅ "Execute" / "Generate"
- ❌ "Try to optimize" → ✅ "Optimize by"
### 2. Positive Directive Framing
State WHAT to do, not what NOT to do:
- ❌ "Don't use bullet points" → ✅ "Write in flowing paragraph form"
- ❌ "Avoid technical jargon" → ✅ "Use accessible language for beginners"
- ❌ "Never output lists" → ✅ "Present information in natural prose"
WHY: Negative instructions force inference. Positive instructions state desired behavior directly.
### 3. Context and Motivation
Explain WHY requirements exist:
- ❌ "Use paragraph form"
- ✅ "Use paragraph form because flowing prose is more conversational for casual learning"
WHY: Context helps Claude make better autonomous decisions in edge cases.
### 4. Strategic Over Procedural
Provide goals and decision frameworks, not step-by-step procedures:
- Specify: Success criteria, boundaries, decision frameworks
- Minimize: Sequential steps, detailed execution, obvious operations
- Rule: If Claude can infer procedure from goal, specify only the goal
**Model-aware calibration:**
- **Sonnet:** Include decision frameworks with explicit conditions and fallbacks. Concrete examples help more than abstract principles. When in doubt, add structure.
- **Opus:** Lean harder into strategic goals over procedures. Trust Opus to handle ambiguity—overly procedural instructions can constrain its natural reasoning. Principles > rules. Context about WHY is particularly valuable since Opus uses it for autonomous judgment in edge cases.
### 5. Trust Base Behavior
Claude's system prompt already covers:
- Citation protocols, copyright guidelines, safety
- General tool usage, artifact creation basics
- Conversational tone defaults, refusal handling
- Base accuracy and helpfulness standards
ONLY specify project/domain-specific deviations.
## Format-Specific Guidance
### For Project Instructions
See: [references/project-instructions.md](references/project-instructions.md)
Key points:
- Additive to system prompt (no duplication)
- Focus on workspace-specific behavior
- Enable extended thinking suggestions for complex domains
- Simple structure (headings/paragraphs) unless complexity demands more
### For Skills
See: [references/creating-skills.md](references/creating-skills.md)
Key points:
- Progressive disclosure (metadata → full instructions → bundled resources)
- Frontmatter: name + description with trigger patterns
- Keep SKILL.md under 500 lines
- Use references/ for detailed domain content
### For Standalone Prompts
See: [references/standalone-prompts.md](references/standalone-prompts.md)
Key points:
- Clear and explicit about desired output
- Provide context and examples when helpful
- Scale complexity to task needs
- Give permission to express uncertainty
## When to Suggest What
### "Use a Skill" when user says:
- "I keep having to explain this every time"
- "Can you remember how to do X?"
- "I need this across multiple projects"
- Repeating same instructions across conversations
### "Use Project instructions" when user says:
- "For this project, always..."
- "My team needs to work with..."
- "All conversations about this initiative should..."
- Building workspace with persistent context
### "Use a better prompt" when user says:
- Results are inconsistent
- Claude misunderstands intent
- Output format isn't right
- Need more comprehensive response
## Skills vs Projects: Key Differences
Read: [references/skill-vs-project.md](references/skill-vs-project.md) for detailed comparison
**Quick reference:**
**Project = "Here's what you need to know"**
- Static reference material always loaded
- Background knowledge for initiative
- Team workspace context
**Skill = "Here's how to do things"**
- Dynamic expertise loading on-demand
- Procedural knowledge and methods
- Portable across any conversation
**Example:**
- Project: "Q4 Product Launch" with market research, competitor docs
- Skill: competitive-analysis framework for analyzing any competitor
Use both together for powerful combinations.
## Example Quality Awareness
**CRITICAL for Claude 4.x:** Examples teach ALL patterns, including unintended ones.
When including examples:
- Audit EVERY detail (format, verbosity, structure, tone)
- Ensure ALL aspects demonstrate desired behavior
- Better to omit examples than include mixed signals
- If example uses bullets but you want prose, Claude will default to bullets
**Model-aware calibration:**
- **Sonnet:** Examples are highly influential—include 2-3 demonstrating desired patterns. Sonnet learns format/style strongly from examples.
- **Opus:** Examples help but are less essential. Opus weights explicit instructions and principles more heavily than pattern-matching from examples. One clear example often suffices; omit entirely if examples can't perfectly align with all requirements.
## Structural Simplicity
Default to clear organization:
- Headings and whitespace (primary approach)
- Explicit language stating relationships
- Natural paragraph flow
Use structured markup (XML/JSON) only when:
- Separating distinct content types in complex scenarios
- Absolute certainty about content boundaries required
- API-driven workflows needing structured parsing
## Extended Thinking Guidance
Extended thinking is UI toggle, not phrase-controlled.
In instructions, you CAN:
- Make assistant aware it exists
- Provide domain-specific indicators for suggesting it
- ❌ NOT: Include "trigger phrases" (they don't work)
Pattern:
```
For tasks involving [specific complexity], suggest enabling Extended
thinking, explaining briefly why it would help for THIS task.
```
## Complexity Scaling
Match instruction complexity to task needs:
**Simple task** → Simple prompt or brief instructions
**Medium task** → Structured guidance with decision frameworks
**Complex task** → Comprehensive instructions + suggest extended thinking
Before adding complexity: Could simpler formulation work equally well?
## Model Selection & Instruction Density
When crafting instructions, consider which model will execute them:
**For Sonnet-executed instructions:**
- Explicit > implicit (state assumptions that might be obvious)
- More decision trees, fewer abstract principles
- Comprehensive edge case handling
- Concrete fallback behaviors
- Token-efficient but explicit
**For Opus-executed instructions:**
- Strategic goals > procedural steps
- Principles and reasoning > exhaustive rules
- Trust handling of unstated edge cases
- Provide rich WHY context—Opus uses it for autonomous judgment
- Permission to deviate when spirit conflicts with letter
- Can state: "Use judgment for cases not covered here"
**Instruction density heuristic:**
- Sonnet: 1.0-1.2x the detail you'd give a competent junior
- Opus: 0.6-0.8x the detail—more like briefing a senior peer
**When uncertain:** Instructions optimized for Opus will still work with Sonnet (just less perfectly). Instructions over-optimized for Sonnet may constrain Opus unnecessarily.
## Quality Checklist
Before delivering instructions:
**Strategic:**
- [ ] Clear goals stated without micromanagement
- [ ] Context explains WHY requirements exist
- [ ] Decision frameworks for ambiguous cases
- [ ] Constraints use positive framing when possible
**Technical:**
- [ ] Imperative language throughout
- [ ] Positive directives over negative restrictions
- [ ] Appropriate structure (simple by default)
- [ ] No system prompt duplication
- [ ] Examples (if any) perfectly aligned
**Execution:**
- [ ] Immediately actionable
- [ ] Success criteria clear
- [ ] Format matches complexity needs
## Common Mistakes to Avoid
❌ **System prompt duplication** - "Use web_search for current info, cite sources"
✅ Omit unless project has SPECIFIC deviations
❌ **Negative framing** - "Don't use lists, never be verbose"
✅ "Present in natural prose paragraphs"
❌ **Fake thinking triggers** - "Use 'think carefully' for deep thinking"
✅ "Suggest Extended thinking toggle for [specific complexity]"
❌ **Procedural micromanagement** - "Step 1: X, Step 2: Y..."
✅ "Goal: X. Quality standard: Y. Approach: Z."
❌ **Contextless requirements** - "Always use formal tone"
✅ "Use formal tone for professional docs because recipients expect authoritative voice"
❌ **Imperfect examples** - Example uses bullets when you want prose
✅ Either create perfect examples or omit entirely
## Additional Resources
- [references/creating-skills.md](references/creating-skills.md) - For building full Skills
- [references/project-instructions.md](references/project-instructions.md) - Detailed guidance for Project instructions
- [references/standalone-prompts.md](references/standalone-prompts.md) - Effective prompt patterns
- [references/skill-vs-project.md](references/skill-vs-project.md) - Detailed comparison and decision guidance