prompt-engineering

What this skill does

**User request**: $ARGUMENTS

Create, update, or review an LLM prompt. Prompts act as manifests: clear goal, clear constraints, freedom in execution.

**If no request provided**: Ask the user whether they want to create a new prompt, update an existing one, or review prompt structure.

**If creating**: Discover goal, constraints, and structure through targeted questions, then draft against the canonical template.

**If updating**: Read the existing prompt, identify issues against principles, make targeted high-signal fixes only.

**If reviewing**: Read the prompt, scan against the canonical template, cross-cutting principles, and anti-patterns. Report issues without modifying the file. For deeper structural audit, delegate to `/review-prompt`.

**Modifier — when the prompt is an agent**: Declare every required tool in frontmatter — agents run isolated and don't inherit tools (see Agents specialization below). Applies on top of the create or update branch.

**If diagnosing a failing prompt**: Load `references/metaprompting.md` and follow its pre-flight check ("when metaprompting is the wrong tool") before the diagnose-from-failures → surgical-revision workflow.

## Before writing — discover context

Missing domain knowledge creates ambiguous prompts. You can't surface latent requirements you don't understand. Surface these before drafting:

| Context Type | What to Surface |
|--------------|-----------------|
| **Domain knowledge** | Industry terms, conventions, patterns, constraints |
| **User types** | Who interacts, expertise level, expectations |
| **Success criteria** | What good output looks like, what makes it fail |
| **Edge cases** | Unusual inputs, error handling, boundary conditions |
| **Constraints** | Hard limits (length, format, tone), non-negotiables |
| **Integration context** | Where the prompt fits, what comes before/after |

**Interview method**:

| Principle | How |
|-----------|-----|
| **Generate candidates, learn from reactions** | Don't ask open-ended "what do you want?" Propose concrete options: "Should this be formal or conversational? (Recommended: formal for enterprise context)" |
| **Mark recommended options** | Reduce cognitive load. For single-select, mark one "(Recommended)". For multi-select, mark sensible defaults or none if all equally valid. |
| **Outside view** | "What typically fails in prompts like this?" "What have you seen go wrong before?" |
| **Pre-mortem** | "If this prompt failed in production, what would likely cause it?" |
| **Discovered ≠ confirmed** | When you infer constraints from context, confirm before encoding. Includes ambiguous scope (list in/out assumptions). |
| **Encode explicit statements** | When the user states a preference or requirement, it must appear in the final prompt. |
| **Domain terms** | Ask for definitions, don't guess. Jargon you don't understand creates ambiguous prompts. |
| **Missing examples** | Ask for good/bad output examples when success criteria are unclear. |

When unsure whether to keep probing, ask one more question — every requirement discovered now is one fewer failure later.

Critical ambiguities (those that would cause prompt failure) require clarification even if the user wants to move on. Minor ambiguities can be documented with chosen defaults and proceed.

## The canonical template

The reference shape for a system prompt. Each section has one job. Keep each section short. Add detail only where it changes behavior.

```
Role
Personality          (optional — see below)
Goal
Success criteria
Constraints
Output
Stop rules
```

| Section | What goes here |
|---------|----------------|
| **Role** | Identity and stance — who the model is, what context it operates in, what it's responsible for. One or two sentences. |
| **Personality** | Voice, tone, formality, warmth, directness. Shapes how the assistant *sounds* to the user. Skip when the prompt is a worker, internal-pipeline, transformation, extraction, or any non-user-facing task — Personality is for user-facing (conversational or customer-facing) surfaces only. |
| **Goal** | The user-visible outcome the run produces. State the destination, not the path. |
| **Success criteria** | What must be true before the final answer. Include the **degradation paths**: when to **retry** (transient failure), **fallback** (alternative method), **abstain** (refuse with reason), **ask** (for the smallest missing field). The four verbs prevent loops and silent guessing. |
| **Constraints** | Rules that must hold throughout the run — policy, safety, business, evidence, side-effect limits. Reserve absolutes (MUST/NEVER) for true invariants; for judgment calls (when to search, ask, iterate, retry), use decision rules: "When X, do Y; otherwise Z." When multiple non-invariant rules apply, mark priority (MUST > SHOULD > PREFER) so conflicts resolve predictably. |
| **Output** | Format, length, audience, structure. Be specific only where it changes behavior — don't over-prescribe shape the model already gets right from Goal. |
| **Stop rules** | Loop control: when to stop pursuing more information and answer with what you have. Distinct from Success (target state) and degradation (non-success behavior). |

**Success vs. Constraints vs. Stop rules** — three different jobs that authors frequently conflate. For a retrieval agent, the boundary looks like:
- *Success criteria*: "answer addresses every part of the asked question" — the target state.
- *Constraints*: "ground every factual claim in retrieved content; never invent citations" — rules that hold throughout.
- *Stop rules*: "when one more search would not change the answer, write" — the loop-exit rule.

Conflating Success and Stop causes agents to over-search or stop early. Conflating Constraints and Success buries the target inside hard rules. Conflating Constraints and Stop turns a permanent rule into a one-shot exit.

Constraints bound the path, not the destination — a rule like *"don't fail to answer"* just restates the goal negatively, adding no new boundary on how the work gets done. Real constraints are blockers along the path: forbidden methods, resource limits, required evidence, side-effect rules. Test for a real constraint: would it still apply if the goal changed? *"Never invent citations"* would (any factual task); *"don't fail to answer"* wouldn't.

**When to use canonical headers vs. theme/phase organization:**
- Use the canonical headers when the prompt is a single-purpose system prompt for an assistant (one Role, one Goal, runtime in a deployment).
- Theme or phase organization fits when the prompt's structure is itself non-trivial — multi-phase workflows, skills with subdomains, instructional documents (this skill is one) — so long as every applicable canonical section is answerable on read.

For non-trivial sections, pull techniques from `references/system-prompt-patterns.md` rather than inventing — verification loops, retrieval/tool budgets, output contracts, ambiguity handling, high-risk self-check, decision-rules.

## Specializations

The canonical template applies directly to **system prompts**. Two further classes — **skills** and **agents** — add conventions on top of the same skeleton.

### Skills

A skill is a directory, not a file. SKILL.md is the entry; companion files (references/, assets/, scripts/) live alongside. On top of the canonical template:

- **Folder architecture** — directory with SKILL.md + appropriate companions. Domain knowledge and reference data live in companions, not front-loaded in SKILL.md (progressive disclosure).
- **Description as trigger** — the frontmatter `description` field is a *trigger specification* for the model's matching algorithm, not a human summary. Pattern: **what + when + trigger terms users actually say**, under 1024 characters (Claude Code's enforced limit). Strong: "Adversarial code review that spawns a fresh-eyes subagent. Use for PR review, code audit, pre-merge quality check. Triggers: review my PR, audi