/writing-instructions

name: writing-instructions
description: "Sentence-level and section-level craft for instructions Claude will actually follow, in any container — project instructions, a standalone prompt, or skill body text. Use when the text exists or is being drafted and the question is quality: \"why is Claude ignoring this instruction\", \"rewrite this prompt so it works\", \"improve my project instructions\", \"make this instruction stick\", \"is this too prescriptive\", \"how much structure does Sonnet need versus Opus\". Covers imperative construction, positive framing, strategic-versus-procedural calibration per model, extended thinking, complexity scaling, and a quality checklist. For deciding WHICH container the instruction belongs in, use crafting-instructions. For building, testing and packaging a whole skill directory, use creating-skill."
metadata:
  version: 0.3.0

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