| name | crafting-instructions |
| description | Generate optimized instructions for Claude (Project instructions, Skills, or standalone prompts). Use when users request creating project setups, writing effective prompts, building Skills, or need guidance on instruction types for Claude.ai. |
| metadata | {"version":"0.3.1"} |
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:
Technical:
Execution:
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
