v0.4.0 to v0.5.0

26 added, 51 removed. Audit A to A.

---

name: crafting-instructions

description: Chooses the right FORMAT for instructions on Claude.ai — project instructions, a skill, or a standalone prompt — and gives the format-specific structure once chosen. Use when the question is which container an instruction belongs in ("should this be a skill or project instructions", "where do I put this", "how do I set up this project", "is this worth a skill"), or when someone has instructions and does not know how to package them. For the writing principles that apply inside any of the three formats, use writing-instructions. For building, testing and packaging a complete skill directory, use creating-skill.

metadata:

- version: 0.4.0

+ version: 0.5.0

---

# 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 alongside model-aware

- calibration, complexity scaling and a quality checklist. The two skills 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 the **format

- decision** and `writing-instructions` owns **how to write well inside a

- format**.

+ `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

- **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.

+ 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](references/project-instructions.md)

Key points:

- Additive to system prompt (no duplication)

- Focus on workspace-specific behavior

- - Enable extended thinking suggestions for complex domains

+ - Name the domains that warrant deeper deliberation

- Simple structure (headings/paragraphs) unless complexity demands more

### For Skills

See: [references/creating-skills.md](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](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](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.

+ 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

- **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.

+ ## Thinking Depth

- In instructions, you CAN:

- - Make assistant aware it exists

- - Provide domain-specific indicators for suggesting it

- - ❌ NOT: Include "trigger phrases" (they don't work)

+ 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.

- Pattern:

+ What instructions can usefully carry is which parts of the domain deserve more

+ deliberation, so the reader knows where to raise effort:

```

- For tasks involving [specific complexity], suggest enabling Extended

- thinking, explaining briefly why it would help for THIS task.

+ [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 + suggest extended thinking

+ **Complex task** → Comprehensive instructions; raise effort

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

- **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

+ 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.

- **When uncertain:** Instructions optimized for Opus will still work with Sonnet (just less perfectly). Instructions over-optimized for Sonnet may constrain Opus unnecessarily.

+ 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"

- ✅ "Suggest Extended thinking toggle for [specific complexity]"

+ ✅ "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](references/creating-skills.md) - For building full Skills

- [references/project-instructions.md](references/project-instructions.md) - Detailed guidance for Project instructions

- [references/standalone-prompts.md](references/standalone-prompts.md) - Effective prompt patterns

- [references/skill-vs-project.md](references/skill-vs-project.md) - Detailed comparison and decision guidance