prompt-engineering

What this skill does

# Prompt Engineering

**Every prompt is an interface contract — clarity of intent determines quality of output.** Apply when crafting skills,
agents, output styles, system prompts, or any AI instructions.

## Read first when

- **You are writing a prompt for another model** (skill, subagent, system prompt, agent instruction, output style) →
  load [`${CLAUDE_SKILL_DIR}/references/agent-authored-prompts.md`] **BEFORE drafting**. Agent-authored prompts have
  distinct failure modes (over-specification, context leakage, ambiguous output contracts, silent degradation across
  pipeline stages) that the diagnostic table below does NOT cover. The summary in
  [Writing Prompts as an Agent](#writing-prompts-as-an-agent) is incomplete — the reference holds the workflow.

## What's Wrong With Your Prompt?

- **Wrong format** — add explicit format + example. See [Output Format](#output-format)
- **Missing information** — be more specific about what to include. See [Be Specific](#be-specific)
- **Hallucination** — add context, request citations. See [Provide Context](#provide-context)
- **Ignores instructions** — place critical rules at top and end, use XML tags. See
  [Persistent Context](#prompting-in-persistent-context)
- **Complex reasoning fails** — use extended thinking or CoT. See [Reasoning](#reasoning)
- **Inconsistent results** — add 3-5 examples. See [Examples](#use-examples-few-shot)
- **Too verbose** — specify word/sentence limits. See [Be Specific](#be-specific)
- **Security concerns** — validate input, filter output. See [`${CLAUDE_SKILL_DIR}/references/security.md`]

## References

- **Reasoning techniques** — [`${CLAUDE_SKILL_DIR}/references/reasoning-techniques.md`] CoT variants (zero-shot,
  few-shot, auto), Tree-of-Thoughts, Self-Consistency, extended thinking (adaptive + manual), reasoning models
  (o3/o4-mini), CRANE constrained reasoning, academic citations
- **Learning paradigms** — [`${CLAUDE_SKILL_DIR}/references/learning-paradigms.md`] ICL theory, zero/few-shot
  techniques, example selection research, generated knowledge prompting, active prompting
- **Workflow patterns** — [`${CLAUDE_SKILL_DIR}/references/workflow-patterns.md`] Prompt chaining topologies, iterative
  refinement, meta prompting, APE, automated optimization survey
- **Prompt security** — [`${CLAUDE_SKILL_DIR}/references/security.md`] OWASP Top 10 for LLM 2025, injection defense,
  agentic pipeline security, threat modeling, defense patterns
- **Optimization strategies** — [`${CLAUDE_SKILL_DIR}/references/optimization-strategies.md`] Promptware engineering
  lifecycle, DSPy declarative optimization, RAG integration, manual iteration discipline
- **Claude-specific** — [`${CLAUDE_SKILL_DIR}/references/claude-specific.md`] Adaptive thinking, effort parameter,
  prefilling, prompt caching (automatic + explicit, 1-hour TTL), structured outputs, context windows, technique
  combinations
- **Long context** — [`${CLAUDE_SKILL_DIR}/references/long-context.md`] Document organization patterns, XML structuring
  for multi-doc, chunking strategies, context rot mitigation
- **Agent & tool patterns** — [`${CLAUDE_SKILL_DIR}/references/agent-patterns.md`] ReAct, PAL, Reflexion, ART, ACE
  implementation patterns, failure modes, pattern selection
- **Agent-authored prompts** — [`${CLAUDE_SKILL_DIR}/references/agent-authored-prompts.md`] Agents writing prompts:
  decomposition workflow, quality dimensions, failure modes, SPL pattern, pipeline rules
- **Persistent context** — [`${CLAUDE_SKILL_DIR}/references/persistent-context.md`] Technique transfer to skills/system
  prompts, instruction degradation research, format sensitivity, declarative vs procedural, U-shaped attention,
  minimalism principle
- **Structured data formats** — [`${CLAUDE_SKILL_DIR}/references/structured-data-formats.md`] Format benchmarks (KV vs
  table vs YAML vs JSON), TOON verdict, output format restrictions, CFPO, format selection rules
- **Context engineering** — [`${CLAUDE_SKILL_DIR}/references/context-engineering.md`] The discipline beyond prompts:
  context types, quality principles, retrieval strategies, management patterns, layered architecture

Read the relevant reference before proceeding.

---

## Core Techniques

Start with the simplest technique that fits the problem. Most issues are solved by the first three.

### Be Clear and Direct

**The golden rule:** show your prompt to a colleague with minimal context. If they're confused, Claude will be too.

#### Provide Context

Tell Claude:

- What the task results will be used for
- Who the audience is
- What success looks like

#### Be Specific

- "Summarize this" → "Summarize in 3 bullets, each under 20 words"
- "Make it better" → "Fix grammar errors, reduce word count by 30%"
- "Analyze the data" → "Calculate YoY growth, identify top 3 trends"

#### Output Format

Always specify format explicitly. Show an example if structure matters:

```
Extract the following as JSON:
- Product name
- Price (number only)
- In stock (boolean)

Example output:
{"name": "Widget Pro", "price": 29.99, "in_stock": true}
```

### Use Examples (Few-Shot)

3-5 examples typically sufficient. Cover edge cases. Format consistency and input distribution matter more than perfect
label accuracy. Performance plateaus after 8-16 examples.

**Example selection rules:**

- Cover diversity — represent different categories, edge cases, styles
- Order simple to complex — build understanding progressively
- Balance output classes — equal representation across categories
- Put representative examples last — recency bias makes later examples more influential
- Prioritize format consistency over perfect labeling
- Wrap in `<examples>` tags for clear separation
- In system context, examples at the start outperform those placed later (primacy bias)

**Choosing the right paradigm:**

- Simple, well-known task → zero-shot (just ask)
- Need specific output format → one-shot (1 example)
- Complex classification / nuanced judgment → few-shot (3-5 examples)
- Domain-specific task → few-shot with domain examples
- Highly nuanced + complex reasoning → few-shot + CoT

Extended paradigm details and ICL theory: see [`${CLAUDE_SKILL_DIR}/references/learning-paradigms.md`].

### Use XML Tags

Separate components for clarity and parseability:

```xml
<instructions>
Analyze the contract for risks.
</instructions>

<contract>
{{CONTRACT_TEXT}}
</contract>

<output_format>
List risks in <risks> tags, recommendations in <recommendations>.
</output_format>
```

- Use consistent tag names throughout the prompt
- Reference tags in instructions: "Using the contract in `<contract>`..."
- Nest for hierarchy: `<outer><inner>...</inner></outer>`
- Critical for multi-component prompts — significantly improves instruction following

### Reasoning

For complex reasoning, ask Claude to show its work:

```
Think through this in <thinking> tags.
Then provide your answer in <answer> tags.
```

**Critical:** Claude must output its thinking. Without outputting the thought process, no thinking actually occurs.

**Reasoning models (Claude adaptive thinking, OpenAI o-series):**

- These models reason internally — do NOT add "think step by step" (it's redundant and may degrade quality)
- Prefer general instructions ("think thoroughly") over prescriptive step-by-step plans
- Use `<thinking>` tags in few-shot examples to demonstrate desired reasoning style
- Ask for self-verification: "Before finishing, verify your answer against [criteria]"
- Use the `effort` parameter to control reasoning depth, not prompt-level CoT

**Standard models (no native reasoning):**

- Use explicit CoT when the problem requires multi-step reasoning
- Use extended thinking when the problem requires exploring multiple approaches
- Use neither for simple factual tasks

**CoT trade-off:** helpful for structural formatting and complex logic; harmful for tasks with many mechanical
constraints (word limits, format rules).

Detailed techniques, ToT, self-consistenc