prompting-effectively

What this skill does

# Prompt Architecture

Effective prompts have structure. This skill covers the principles that make prompts clear, reliable, and maintainable — whether you're writing commands, agents, modes, skills, or API system prompts.

**MANDATORY:** Before authoring any prompt for internal Claude tools (skills, agents, modes, commands, subagent prompts), read [opus-4-7.md](opus-4-7.md) — the Opus 4.7-specific behavior reference. It covers model-specific tuning (effort, tool triggering, literal instruction following, subagent spawning, thinking, agentic patterns) that this architecture overview does not.

For detailed patterns and examples of the architecture principles below, see [reference.md](reference.md).

## The Two Zones

The most important architectural decision: what goes where.

**Behavior zone** (system prompt, agents, modes):
- Identity, personality, tone
- Constraints and hard rules
- Tool usage policies (→ [tool-design](../tool-design/SKILL.md) covers designing the tools themselves)
- Decision frameworks ("when X, do Y")
- Formatting preferences

**Task zone** (commands, skills, task prompts):
- Temporary role shifts and focus areas
- Step-by-step procedures or constraints for the task
- Context the agent needs to do this specific thing

**Knowledge zone** (skills, documents, user context, CLAUDE.md):
- Reference material and domain knowledge
- User-specific context and preferences
- Project information
- Data that changes between sessions

System prompt content gets treated as foundational identity. Task-zone content layers on top — it *redirects* the agent without replacing who it is. Knowledge gets treated as reference material. Mixing these up creates agents that treat their own rules as optional suggestions, or user-turn prompts that fight the system prompt for control of identity.

→ For the orthogonal API-level question — what goes in the `system` message vs the `user` message of a single API call — see [system-vs-user-prompt](../system-vs-user-prompt/SKILL.md).

## XML for Instruction Domains

Use XML tags to separate concern domains (identity, safety, tools, formatting). Rules:

- Section-level boundaries only — don't wrap every paragraph
- Two levels of nesting maximum for instructions (deeper is fine for examples)
- Over-tagging creates noise that dilutes the structural signal

Over-formatted system prompts bleed into over-formatted responses — use the lightest formatting that makes content clear.

## Tone Registers

The voice you use affects how the model interprets instructions — and the right voice depends on *where the prompt lives*.

**Third person → Identity (system prompts only):**
> "Claude cares about people's wellbeing."
> "The agent avoids over-formatting responses."

Establishes personality traits. The model internalizes these as "who I am." This framing belongs in system prompts, agents, and modes — not in commands or skills.

**"You are X" → Identity declaration (system prompts only):**
> "You are a senior security auditor who reviews code for vulnerabilities."

Defines the agent's core role. In a system prompt, this is foundational. In a user-turn prompt (command, skill, task), it conflicts with the identity already established — use "Act as X for this task" instead.

**"Act as X" → Temporary role (commands, skills, task prompts):**
> "Act as a security auditor for this review. Focus on auth flows and input validation."

Layers a role on top of the existing identity without overriding it. The agent applies this lens for the current task, then returns to its base behavior.

**Second person → Operations:**
> "When you encounter X, stop immediately."
> "You should use the minimum number of tools needed."

Direct instruction for procedures and workflows. Works in both zones.

**Imperative → Hard rules:**
> "NEVER reproduce song lyrics."
> "ALWAYS search before responding about current events."

Absolute rules that should not be overridden by context.

### The Escalation Ladder

1. **Suggestion**: "It's fine to..." / "Claude can..."
2. **Default**: "Claude does..." / "Claude avoids..."
3. **Instruction**: "You should..." / "Always prefer..."
4. **Hard rule**: "NEVER..." / "MUST..." / "CRITICAL:..."
5. **Repeated hard rule**: Same rule in multiple sections with different framing

Most guidance sits at levels 2–3. Reserve 4–5 for genuine non-negotiables. If everything is CRITICAL, nothing is.

## Subtract Before You Add

When the model produces bad output, scan the prompt for the instruction causing it and delete that instruction. The model has strong defaults — out-of-distribution behaviors (wrapping output in unusual tags, inventing structure, weird formatting) almost always trace back to a prompt that pushed the model there. The fix is subtraction, not addition.

**Worked example.** A tool description read:

> "Task instruction wrapped in `<fork-task>` verbatim."

The model wrapped its output in `<fork-task>` tags because the description told it to. The minimal fix is deletion:

> "The task this fork should execute."

What goes wrong if you skip the delete step:

- **Adding a prohibition while leaving the cause:** keep the "wrapped in `<fork-task>`" instruction, then bolt on *"DO NOT wrap in `<fork-task>` tags."* Now the prompt contradicts itself, and the prohibition primes attention toward the very tags you don't want.
- **Replacing with a positive description when none was needed:** "One self-contained instruction, e.g. 'Send a DM to Priya.'" Reads fine, but the field name and schema already convey this. You've spent tokens telling the model to write normally — which is what it would have done anyway.

**Order of preference:**

1. **Delete** the instruction causing the misbehavior. Often nothing needs to take its place — the field name, type, or surrounding context already conveys what's expected.
2. **Rephrase positively** when the field genuinely lacks a description. "DO NOT use ellipses" → "Use periods instead" — describe the target, not its inverse.
3. **Prohibit** only when you have observed the failure *without* any prompt pushing the model there. Rare. The bar is evidence, not preference.

**When negative framing earns its place:** the model has an observed prior toward the wrong behavior with no prompt cause. "Avoid Inter" works because Opus genuinely defaults to Inter. "Be conservative" in a code review actively suppresses findings (see opus-4-7.md). Otherwise: trust the default.

**Heuristic:** before adding *anything* in response to bad output, find the line in the prompt that caused it. If you find one, delete it and stop. Telling the model to "write normally" or "respond naturally" is a token-burning no-op — it would have done that already if you hadn't told it otherwise.

## Positive Framing

For instructions that survive the subtraction check — genuine deviations from default behavior — describe the target, not its inverse.

**Weak:** "Do not use ellipses."
**Strong:** "Use periods or commas to end clauses."

The model produces what you describe. "Don't do X" requires the model to represent X in order to avoid it, which can prime the failure mode rather than suppress it. "Do Y" steers directly. This holds across domains:

- Output style: "don't be verbose" → "keep responses to 2–3 sentences for simple questions"
- Tool use: "don't call this tool unnecessarily" → "call this tool when you see X, Y, or Z"
- Behavioral guidance: "don't be sycophantic" → "open with the answer, not a compliment"

Concrete positive instructions outperform abstract negative ones, especially in long prompts where any single rule's attention weight is diluted by surrounding context. If you find yourself writing a "don't," ask what the corresponding "do" is — that's usually the better instruction.

## Examples

**Rules:**
- Place examples adjacent to the rules they illustrate — never in a separate appendix
- Use good/bad pairs for nuanced behaviors
- Add rationale tags when the reasoning matters for generalization

```xml
<example>