Crafting Instructions for Claude
Generate technically optimized instructions for Claude.ai across three formats: Project instructions, Skills, and standalone prompts.
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
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
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
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 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 - For building full Skills
- references/project-instructions.md - Detailed guidance for Project instructions
- references/standalone-prompts.md - Effective prompt patterns
- references/skill-vs-project.md - Detailed comparison and decision guidance