crafting-instructions

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](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 tre