claude-opus-prompting

Claude Opus Prompting

Use this skill when a main Claude Code agent is about to spawn a Claude Opus subagent (such as sam-skills:claude-code-review) and needs to compose the prompt it hands off. The goal is to produce a one-shot hand-off prompt that is clear, grounded, and yields reliable structured output.

Based on Anthropic's official Claude 4.6 prompting best practices. Scope: composing forwarded prompts for Opus subagents, not general prompt engineering tutorials.

Core philosophy

Treat Claude Opus like a brilliant but new employee who lacks context on your norms. Be explicit. Golden rule: if a colleague with no context would be confused reading the prompt, Claude will be too.

Three things Opus 4.6 rewards:

1. Structured XML blocks over free-form prose. Claude is trained to parse XML tags reliably. Wrapping each part of the prompt in a dedicated tag reduces misinterpretation versus running prose.
2. Long context at the top, query at the bottom. Place large documents first; put the actual ask last. Anthropic's internal tests show up to 30% quality improvement versus the reverse order.
3. Evidence-grounded responses. For review / research / diagnosis tasks, explicitly require Opus to quote source material before drawing conclusions.

Three things Opus 4.6 is prone to if you don't push back:

1. Over-engineering and scope creep. Documented tendency to add abstractions, extra files, defensive coding, "improvements" beyond what was asked. Add <do_not_over_engineer> when the task touches code or design.
2. Over-thinking and revisiting decisions. At higher effort Opus keeps rethinking approaches. Add <commit_to_approach> when you want it to commit.
3. Over-triggering on aggressive language. "CRITICAL: YOU MUST" causes over-triggering. Use normal phrasing; rely on structured blocks for emphasis.

Default block structure

Every hand-off prompt is built from a selection of XML blocks. Include only what the task needs; don't pad with empty sections.

Canonical placement order (important — long context at top, hard rules and output contract at bottom gives Opus the freshest instructions when it starts generating):

1. <role>                      — one sentence, at top
2. <context> / <documents>     — long-form reference material
3. <input> / <target>          — the specific thing to operate on
4. <task>                      — one sentence restating the concrete job
5. <instructions>              — ordered steps, if the workflow matters
6. <grounding_rules>           — evidence requirements, if relevant
7. <constraints>               — hard rules
8. <output_contract>           — exact output shape, at the very bottom

See references/prompt-blocks.md for the full block catalog, including:

• Core blocks: <role>, <task>, <context>, <documents>, <input>, <instructions>, <output_contract>, <constraints>, <examples>, <completion_signal>
• Opus gotcha blocks (paste verbatim when relevant):
  • <do_not_over_engineer> — for any task touching code or design
  • <investigate_before_answering> — anti-hallucination for codebase tasks
  • <commit_to_approach> — reduces over-thinking
  • <grounding_rules> — forces quote-before-conclude for review/research
  • <use_parallel_tool_calls> — for read-heavy subagents
  • <subagent_usage> — when the target agent has Agent/Task tool and you want it to work directly instead of delegating further
  • <do_not_act_before_instructions> — for read-only agents

Scenario templates

End-to-end fill-in-the-blank templates for common hand-off patterns live in references/prompt-recipes.md:

• Code review hand-off — canonical template for spawning sam-skills:claude-code-review with a real Obsidian task-id and plan docs (Recipe 1)
• Research / analysis hand-off — generic template for diagnosis, investigation, or structured analysis tasks (Recipe 2)
• Code review hand-off (no task-id / no plan docs) — variant for direct coding instructions where there is no Obsidian plan to compare against (Recipe 3)

When composing a new prompt, start from the closest template in that file and delete blocks the task doesn't need.

Assembly rules

• One job per subagent run. Don't bundle unrelated tasks. Split or trim.
• Tell Opus what to do, not what not to do — except inside <constraints>, where negative rules are expected.
• Match prompt style to desired output style. Structured markdown prompt → structured markdown output. Flowing prose prompt → flowing prose output.
• Use consistent tag names. If you open with <design_doc>, refer back to it as "the design_doc" throughout.
• Nest when there's hierarchy. Multiple docs go inside <documents> with <document index="n"> + <source> + <document_content> sub-tags.
• Don't prefill assistant messages. Deprecated in Claude 4.6. Use <output_contract> instead.

Assembly checklist

Before sending the prompt:

1. Is there exactly one concrete task in <task>?
2. Is long-form reference material at the top and <output_contract> at the bottom?
3. Do tag names match what <instructions> and <output_contract> reference?
4. Is the output contract specific enough that you (the caller) can parse the response reliably?
5. Is there any "CRITICAL" / "YOU MUST ALWAYS" aggressive language? Dial back.
6. Does the prompt include anti-over-engineering if the task touches code?
7. Does it include grounding rules if the task involves review, research, or diagnosis?
8. Are there redundant instructions across blocks? Remove duplicates.
9. Did you substitute or remove all {{placeholder}} markers from templates?

Anti-patterns

Common failure modes and how to avoid them live in references/prompt-antipatterns.md. Highlights:

• Running prose instructions with no XML structure
• Stuffing the output contract at the top
• Over-prescribing reasoning steps
• Aggressive urgency language
• Mixing review and implementation in one run
• Passing file contents inline when the subagent can read them itself
• Leaving {{placeholder}} markers in the final prompt

When not to use this skill

• Main agent is handing a task to a non-Opus subagent (Haiku tool runners, codex:rescue). Those have their own prompting conventions — see codex:gpt-5-4-prompting for the codex equivalent.
• Task is trivial enough that a one-sentence user prompt would work fine.
• You're not spawning a subagent at all — this skill is specifically about composing forwarded prompts for Opus subagents, not about the main agent's own turn.

References

• references/prompt-blocks.md — full XML block catalog with paste-ready code
• references/prompt-recipes.md — end-to-end scenario templates
• references/prompt-antipatterns.md — failure modes to avoid
• Claude 4.6 prompting best practices — Anthropic official guide
• Use XML tags to structure your prompts — XML tag reference