Writing Instructions

Writing Instructions for Claude

Principles and patterns for writing instructions that Claude follows reliably — whether as project instructions, standalone prompts, or skill content.

Overlap notice. crafting-instructions carries the same five core principles and a fuller format-decision framework. The two were written independently and never reconciled; a 2026-08-24 retrieval measurement put their descriptions at 0.843 cosine, the most confusable pair in the 92-skill catalogue. Until they are merged, this skill owns writing quality and crafting-instructions owns the format decision.

Choosing the Right Format

Determine format before writing. The wrong container undermines good instructions.

Project instructions — persistent context for a workspace. Use when all conversations in a project need shared knowledge, team collaboration context, or initiative-specific behavior. Signals: "for this project," "all conversations about X," "team workspace." Read references/project-instructions.md for detailed guidance.

Standalone prompts — ephemeral, conversational, immediate. Use for one-off requests, ad-hoc direction, or conversational refinement. Signals: "for this task," "right now," "just this once." Read references/standalone-prompts.md for techniques.

Skill content — portable expertise that loads on-demand across contexts. Use when capability is needed across multiple projects, procedural knowledge applies broadly, and instructions should activate automatically on relevant triggers. Signals: "every time I," "whenever," "reusable," "teach Claude how to." For building full skills (structure, testing, iteration, packaging), use the skill-creator skill.

Combined approaches work well: project instructions provide "what you need to know" (reference material, context) while skills provide "how to do things" (methods, procedures). Read references/choosing-formats.md for detailed comparison and migration patterns.

Core Writing Principles

These apply to ALL instruction formats. They are ordered by impact.

1. Imperative Construction

Frame as direct commands. Imperative language reduces ambiguity and signals that the instruction is not optional.

• ❌ "Consider creating X" → ✅ "Create X when conditions Y"
• ❌ "You might want to search" → ✅ "Search for"
• ❌ "Try to optimize" → ✅ "Optimize by"

2. Context and Motivation

Explain WHY requirements exist. Claude uses reasoning about purpose to make better decisions in unstated edge cases, and WHY context is particularly valuable for Opus's autonomous judgment.

• ❌ "Use formal tone"
• ✅ "Use formal tone because documentation targets enterprise clients expecting authoritative voice"

A requirement without context is a rule Claude follows mechanically. A requirement with context is a principle Claude can extend intelligently.

3. Positive Directive Framing

State WHAT to do, not what NOT to do. Negative instructions force Claude to infer the desired alternative — positive instructions state it directly.

• ❌ "Don't use bullet points" → ✅ "Write in flowing paragraph form"
• ❌ "Avoid technical jargon" → ✅ "Use accessible language for beginners"
• ❌ "Never output raw data" → ✅ "Present data with interpretation and context"

When a negative constraint is truly necessary, pair it with the positive alternative: "Present in prose paragraphs, not bullet lists, because flowing text is more conversational for learning contexts."

4. Strategic Over Procedural

Provide goals and decision frameworks rather than step-by-step procedures. If Claude can infer the procedure from the goal, specify only the goal.

• Specify: success criteria, boundaries, decision frameworks, quality standards
• Minimize: sequential steps, detailed execution, operations Claude can determine from goals

This principle scales with model capability — Opus needs less procedural detail than Haiku (see Model-Aware Calibration below).

5. Trust Base Behavior

Claude's system prompt already handles citation protocols, copyright, safety, general tool usage, artifact creation, conversational tone, and accuracy standards. Only specify project- or domain-specific deviations from these defaults.

Duplicating system prompt behavior wastes tokens and can create conflicting signals. Test whether Claude already does what you want before adding instructions for it.

Model-Aware Calibration

Instructions may execute across Haiku, Sonnet, and Opus. The tiers still differ in how much procedural detail they need — treat that as a direction to lean, not a ratio to compute; current models across all three tiers follow instructions more literally than the generation this calibration was first written against, so over-specifying for any of them now costs more than it buys.

Haiku: Lead with explicit imperative commands and concrete decision trees. Provide exact conditions, specific fallbacks, and examples for the scenarios that matter. Structure as: "When X, do Y. When Z, do W."

Sonnet: Provide decision frameworks with explicit conditions alongside a couple of concrete examples demonstrating desired patterns. Balance procedural clarity with strategic context.

Opus: Emphasize strategic goals, reasoning context, and principles over procedures. Opus uses rich WHY context for autonomous judgment in edge cases; one clear example often suffices, and overly procedural instructions constrain it unnecessarily. Frame as: "Goal is X because Y. Apply judgment for unstated cases."

Practical layering pattern: Structure instructions so imperative commands come first, followed by decision frameworks and examples, with strategic reasoning and WHY context woven throughout. A single instruction set serves all three models when layered well.

When uncertain about target model: Optimize for Sonnet — it degrades gracefully on both neighbors.