| name | opus-prompting |
| description | Use this skill when the user is writing, reviewing, debugging, or rewriting any
instructions that Claude itself will read — including CLAUDE.md files, skill files
(SKILL.md, frontmatter descriptions), slash command templates (.claude/commands/*.md),
and agent definitions (.claude/agents/*.md). Trigger on symptoms like: an agent firing
too often or on the wrong things, a prompt that's too long or full of MUST/NEVER/ALWAYS,
Claude ignoring sections of a command, agents looping on tools instead of stopping,
skills not activating when they should, descriptions that don't trigger correctly, or
asking how to structure a system prompt so Claude behaves a certain way. Also trigger
when converting docs/runbooks into skills, drafting agent frontmatter from scratch, or
asking what's "pulling weight" in a prompt. Do not trigger for general code review, MCP
server design, hook scripts, or API/SDK questions unless the artifact under discussion
is a prompt Claude reads.
|
Prompt Writing Assistant
Claude follows natural language more literally than most models expect. The primary failure mode is overtriggering and over-specification — not under-compliance. Write less, trust more.
If unsure whether these behavioral properties are current, check the system date and search for the latest Claude model documentation.
Claude Behavioral Properties
| Property | Implication |
|---|
| Adaptive thinking with tunable effort levels | Let Claude calibrate reasoning depth; manual thinking budgets are unsupported — set effort at the API level when needed |
| Literal instruction following | Every instruction compounds — write guidelines, not rules |
| High system prompt responsiveness | Natural language over directives; aggressive language causes overtriggering |
| Overtriggering as primary failure mode | MUST use [tool] → tools fired when not needed; soften to Use [tool] when... |
| Overeagerness / overengineering | Claude adds features, docs, error handling beyond what's asked; scope constraints help |
| Response length calibrates to task complexity | Let the task set length — prompts that prescribe target lengths fight built-in calibration |
| Reduced autonomous tool calls and subagent spawning | Scaffolding that forces tool loops or multiple subagents may be counterproductive — describe intent, let Claude choose |
| Sampling parameters unsupported | Temperature, top-p, and top-k are not configurable — steer behavior through instruction, not sampling |
| Prefilling deprecated | Assistant message prefilling is unsupported; use system prompt instructions or structured output |
Applying These Patterns
Read these artifact-type blocks to identify which patterns matter most for your current task. Pattern numbers reference references/patterns.md.
CLAUDE.md Instructions
Key concern: Over-specification compounds across every session. Each unnecessary rule burns token budget and can trigger the behaviors it's trying to prevent.
- Pattern 1 (Aggressive language) — soften or remove
MUST/NEVER/CRITICAL; they cause overtriggering in instructions that persist across sessions
- Pattern 5 (Context/motivation) — one
because... per constraint lets Claude generalize rather than memorize
- Pattern 6 (Over-specification) — describe intent, not exhaustive rules; three similar lines beat a premature abstraction
Guidance: Write guidelines a colleague would follow without needing to memorize them. If a rule triggers the behavior it's preventing (e.g., NEVER be verbose makes the prompt verbose), cut it.
Skill Body (SKILL.md)
Key concern: The description field in frontmatter is a token-budget signal — it controls when the skill loads into context. Lead with what the skill does when invoked, not what subject it covers.
- Pattern 7 (Verbosity) — skill descriptions are ranking signals; every word must earn its place
- Pattern 6 (Over-specification) — progressive disclosure: frontmatter triggers loading, body provides depth
- Pattern 4 (Formatting) — match the skill's prose style to the output you want from the model
Guidance: First sentence of description should be a verb phrase naming the activation behavior (e.g., "identifies X and surfaces Y" not "covers X, Y, and Z"). See also: aeo-skill-creator skill.
Slash Command Template
Key concern: Command templates are read once per invocation. The model parses them linearly — structure (especially XML) matters more than in persistent context.
- Pattern 8 (XML structure) — use semantic tags (
<workflow>, <reference>, <current-state>) to separate mutable from immutable sections
- Pattern 4 (Formatting) — prompt format influences output format; structure the template like you want the output
- Pattern 3 (Tool invocation) — conditional tool use (
Use [tool] when...) prevents overtriggering in command workflows
Guidance: Front-load the command's purpose and exit criteria. $ARGUMENTS substitution is a command-only feature — if this content is in a skill, arguments won't route. See also: slash-command-creator skill.
Agent System Prompt
Key concern: Agents are more literal than interactive sessions. Overtriggering is amplified because agents act autonomously on every instruction.
- Pattern 1 (Aggressive language) —
MUST/ALWAYS in agent prompts cause pathological tool loops
- Pattern 3 (Tool invocation) — describe tools conditionally; agents will invoke every tool that sounds relevant
- Pattern 6 (Over-specification) — agents handle novel situations better with principles than with exhaustive rules
Guidance: Describe tool use conditionally (Use X when Y) not imperatively (Always use X). Test by asking: if this instruction fires incorrectly, what's the blast radius?
Self-Check
Before outputting, run these three tests:
- Golden rule: Would a colleague with minimal context understand this without asking clarifying questions?
- Self-defeating instructions: Does any instruction trigger the behavior it's preventing? (
MUST NOT be verbose is itself verbose; NEVER overthink invites overthinking)
- How vs what: Am I specifying how when the reader only needs what? (If yes, cut the how — Claude will find an appropriate implementation)
References
| File | Content |
|---|
references/patterns.md | 8 pattern categories with before/after examples and transformation rules |
references/agentic-patterns.md | Agent teams, delegation, tool design, state tracking, error handling |
scripts/analyze-prompt.py | CLI analyzer for deprecated patterns (configure via scripts/config.json) |
