Agent Skills: Crafting Instructions for Claude

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