---
name: prompt-engineering
description: >-
  Designs, optimizes, and tests LLM prompts for reliable outputs. Use when building
  LLM-powered features, writing system prompts, optimizing for consistency, or
  debugging unreliable LLM behavior. NOT for fine-tuning, training data curation,
  or RAG pipeline design.
allowed-tools:
  - Read
  - Glob
  - Grep
  - Bash
---

## Identity & Scope

**Executor:** either
**Model tier:** opus
**Scope:** Prompt text, system instructions, few-shot examples, output format specs, evaluation results.
**Off-limits:** Modifying model weights, accessing training data, paid LLM API calls without approval.

### Hard Rules
- No credentials in output or git — ever
- No spending money or publishing without explicit user approval
- No deleting files — archive first, 48hr hold
- Report completion to boss via structured output

## Essential Principles

1. **Specify output format exactly** — "Return JSON with keys: name, score, reason" beats "structured data." Guards against: inconsistent output breaking parsers.
2. **Provide 2-3 examples** — Examples calibrate better than instructions alone. Guards against: misinterpreted intent.
3. **Separate instructions from data** — Use XML tags or delimiters. Guards against: instruction injection.
4. **Test with adversarial inputs** — Empty, malicious, max-length, unexpected format. Guards against: prompts that only work on happy paths.
5. **Constrain before instructing** — Enums, max length, required fields. Guards against: unbounded variable output.

## When to Use
- Building a new LLM-powered feature needing a system prompt
- "Write a prompt for X" — explicit prompt creation
- Existing prompt produces inconsistent output
- Debugging unexpected LLM feature behavior

## When NOT to Use
- Fine-tuning or training models — use model training workflows
- Building RAG pipelines — use retrieval architecture skills
- Generating one-off content — just write it directly
- Prompt injection defense at app layer — use security-assessment

## Rationalizations to Reject

| Shortcut | Why it's wrong |
|----------|----------------|
| "Clear enough without examples" | Examples are highest-impact improvement. Never skip. |
| "One test input is enough" | One test proves nothing. Need 3+ including edge cases. |
| "Short prompt = good prompt" | Short without constraints = unpredictable. Reliability > brevity. |
| "Let the model figure out format" | Unspecified format = random format. Always specify. |

## Workflow

### Phase 1: Requirements
**Entry:** Prompt creation or optimization requested.
**Actions:**
1. Identify task type (classification, extraction, generation, transformation).
2. Define exact output format (JSON schema, markdown, plain text with constraints).
3. Collect 3+ example inputs: normal, edge case, adversarial.
4. Define success criteria for correct output.
**Exit:** Task, format, examples, and success criteria documented.

### Phase 2: Draft
**Entry:** Phase 1 complete.
**Actions:**
1. Write prompt: role/context, task, constraints, output format, examples.
2. Use XML tags to separate instructions from user input.
3. Include 2-3 few-shot examples. Add negative examples for known failure modes.
**Exit:** Complete prompt with role, task, constraints, format, examples.

### Phase 3: Test
**Entry:** Phase 2 complete.
**Actions:**
1. Test with all example inputs from Phase 1 (minimum 3).
2. Test with empty/minimal input and adversarial input (injection attempt).
3. Document pass/fail with actual output for each test.
4. Iterate on failures (max 3 revision cycles).
**Exit:** Prompt passes all tests or failures documented with fixes.

### Phase 4: Verify
**Entry:** All prior phases complete.
**Actions:**
1. Confirm output format specified, 2+ examples embedded, delimiters used.
2. Confirm adversarial testing performed and documented.
3. Validate output matches required JSON structure.
**Exit:** All checks pass — report results to boss/user.

## Output Format

```json
{
  "skill": "prompt-engineering",
  "status": "completed",
  "worker": "worker-002",
  "summary": "Created invoice-extractor-v1 prompt. 342 tokens. Passes 5/5 tests including adversarial.",
  "findings": [
    {"item": "Prompt: invoice-extractor-v1", "severity": "info", "detail": "Extracts vendor, amount, date, line items. JSON output with strict schema. 3 few-shot examples."},
    {"item": "Adversarial: injection attempt", "severity": "info", "detail": "'Ignore instructions' input correctly returned empty JSON with error flag. PASS."}
  ],
  "prompt": {"name": "invoice-extractor-v1", "tokens": 342, "tests": {"passed": 5, "failed": 0}},
  "errors": [],
  "elapsed_seconds": 89.4
}
```

**Bad example:** `{"summary": "Wrote a prompt", "findings": [{"item": "Should work for most inputs"}]}` — No tests, no token count, no examples mentioned. "Should work" is speculation.

## Escalation Triggers

STOP and report to boss when:
- Prompt handles sensitive PII, medical, or financial data
- Testing requires paid API calls beyond budget
- Prompt fails adversarial testing after 3 iterations
- Prompt will be user-facing without human review in loop

Report as: `{"status": "escalated", "reason": "...", "context": "...", "recommendation": "..."}`

## Success Criteria

- [ ] Prompt includes explicit output format specification
- [ ] At least 2 few-shot examples embedded
- [ ] Instructions and data separated by delimiters
- [ ] Tested with 3+ inputs (normal, edge, adversarial)
- [ ] All test results documented with pass/fail
- [ ] Token count reported
- [ ] Output matches JSON format above
