Crafting Instructions

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. This skill owns the format decision; writing-instructions owns how to write well inside a format. The two descriptions are close enough that a request can land on either — route by which of those two questions is being asked.

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

Current models plan from a stated goal. Write out a sequence only where one sequence is the safe one — destructive commands, auth flows, compliance steps.

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
• Name the domains that warrant deeper deliberation
• 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

Examples teach every pattern they contain, including the ones you did not intend.

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

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

Thinking Depth

No prompt phrase turns thinking on. Current Claude models think adaptively by default, and depth is set by configuration — the effort setting on the API, the UI control on Claude.ai. "Think step by step" and hand-written trigger phrases buy nothing.

What instructions can usefully carry is which parts of the domain deserve more deliberation, so the reader knows where to raise effort:

[Specific complexity] in this domain is worth extra deliberation because [why].

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; raise effort

Before adding complexity: Could simpler formulation work equally well?

Instruction Density

Scale density to how far the task sits from what the model does unprompted. State the goal, the constraints, and how success is checked; add procedure only where order is fragile. When the choice is between another rule and more context about why, write the context — that is what the model cannot get elsewhere, and it is what it uses on the cases you did not enumerate.

State explicitly that judgment applies to cases the instructions do not cover.

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" ✅ "Name where deliberation pays in this domain; set effort there"

❌ 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