v1-prompt-engineering

---
name: v1-prompt-engineering
description: Use when writing, reviewing, or migrating prompts, system prompts, hooks, skills, or agent instructions. Triggers on "optimize prompt", "system prompt", or "prompt migration".
---
# Prompt Engineering

Improve prompts by tying every instruction to a concrete failure mode, output contract, or evaluation result.

For GPT-5.5, the OpenAI Responses API, OpenRouter, `reasoning_effort`, or model-migration specifics, load `references/gpt-5-5-patterns.md`. For GPT-5.4 hosts only, also load `references/gpt-5-4-patterns.md` (short deltas; load 5.5 first for shared contracts).

For Claude 5 generation hosts (Opus 5.5, Fable 5.1), `output_config.effort`, structured outputs, or Claude prompt migration, load `references/claude-5-patterns.md`.

## Quick Start

1. Identify the host, model family, tool surface, and output consumer. For GPT-5.5, OpenAI Responses API, or OpenRouter hosts, load `references/gpt-5-5-patterns.md`. On GPT-5.4 only, load that file first, then `references/gpt-5-4-patterns.md` for deltas. For Claude 5 generation hosts, load `references/claude-5-patterns.md`.
2. Write the smallest prompt that can pass the task.
3. Add only blocks that fix a named failure mode.
4. Test against representative inputs before adding more instruction text.
5. Remove instructions that do not change behavior in test examples.

## Prompt Contract

Every production prompt should define:

| Contract | Include |
| --- | --- |
| Outcome | What the model must produce or decide |
| Inputs | Source material, tools, files, schemas, and trusted context |
| Constraints | Safety, grounding, permissions, latency, or missing-data behavior |
| Output | Exact format, sections, schema, or artifact destination |
| Done | Success criteria and stop conditions |

If a prompt block does not support one of these rows, delete it or move it to documentation outside the prompt.

## Instruction Value Gate

Before keeping an instruction, classify it:

- **Keep:** trigger, gate, artifact, command, threshold, example, failure mode, or stop rule.
- **Rewrite:** vague advice that can become one of those forms.
- **Delete:** generic quality language with no observable decision.

This is the Instruction-Value-Gate / no-op test; `v1-skilling-it` holds the canonical treatment and the full skill failure-mode vocabulary (sediment, sprawl, leading words).

```markdown
# Weak
Be careful and produce a high-quality answer.

# Strong
Before finalizing, verify each required field is present. If a field cannot be derived from the input, output `null` and add the field name to `missing_fields`.
```

## Workflow

### 1. Baseline

Draft the smallest prompt that includes the outcome, inputs, output contract, and missing-information behavior. Do not add examples, role framing, or reasoning instructions yet.

### 2. Evaluate

Run or manually simulate at least three representative cases:

- normal case
- edge or ambiguity case
- missing or conflicting input case

Record what failed: wrong trigger, invented fact, wrong format, excessive verbosity, premature stop, bad tool use, unsafe action, or weak refusal/blocked handling.

### 3. Patch Only The Failure

Use the narrowest pattern that fixes the observed failure:

| Failure | Prompt patch |
| --- | --- |
| Wrong format | Add exact output schema or template |
| Missing fields | Add required-field checklist and missing-field behavior |
| Fabricated facts | Add grounding rule and citation/source constraint |
| Overlong answer | Add section limits or verbosity contract |
| Premature stop | Add completeness contract and blocked-item format |
| Tool misuse | Add tool prerequisites, stop rules, and recovery behavior |
| Weak routing | Add trigger and non-trigger examples |

Avoid adding broad persona language unless the failure is specifically tone, audience, or authority handling.

### 4. Use Examples When Rules Are Ambiguous

Add 2-3 input/output examples when the model must learn a format, boundary, or classification that prose cannot define compactly.

Each example must cover a different decision. Do not include examples that all demonstrate the same obvious case.

### 5. Verify And Prune

After changes, rerun the examples. Keep the change only if it fixes a failure without introducing a worse one.

Then prune:

- repeated constraints
- unsupported performance claims
- generic phrases like "be thorough," "high quality," or "careful"
- reasoning instructions when the output contract already forces the needed work
- confidence scores unless a downstream decision consumes them

## Useful Blocks

### Grounded Answer

```xml
<grounding>
- Use only the provided context and retrieved tool outputs.
- Label inference explicitly.
- If evidence is missing, say what is missing instead of filling the gap.
</grounding>
```

### Structured Output

When the API supports structured outputs (`output_config.format`, or tools with `strict: true`), enforce the schema there and keep only the missing-data rules in the prompt:

```xml
<output_contract>
- Use `null` for unavailable optional values.
- Return an error object when required schema information is missing.
</output_contract>
```

Without API enforcement, add `Output only valid JSON matching the requested schema.` and `Do not invent fields.` to the block.

### Tool Workflow

```xml
<tool_rules>
- Use tools only when they materially improve correctness.
- Run prerequisite reads before edits or external actions.
- If a tool returns empty or partial results, try one fallback query before marking the item blocked.
- Ask before irreversible external mutations.
</tool_rules>
```

## Reference Files

- `references/advanced.md` - Carry-forward patterns for concise context, degrees of freedom, and plain constraint wording.
- `references/gpt-5-5-patterns.md` - GPT-5.5 ready-to-paste blocks, the reasoning-effort ladder, OpenAI Responses API and OpenRouter chat-completions runtime notes, and migration defaults.
- `references/gpt-5-4-patterns.md` - Short GPT-5.4-only deltas; load after `gpt-5-5-patterns.md` when still on 5.4.
- `references/claude-5-patterns.md` - Claude 5 generation (Opus 5.5, Fable 5.1) runtime notes: adaptive thinking and `output_config.effort`, structured outputs instead of prefill, tool-choice limits, and plain-constraint wording.

• SKILL.md 6 KB
• agents/openai.yaml 1 KB
• references/advanced.md 3 KB
• references/claude-5-patterns.md 2 KB
• references/gpt-5-4-patterns.md 3 KB
• references/gpt-5-5-patterns.md 8 KB