---
name: prompt-engineering-expert
description: |
  Expert prompt engineering, custom instruction, system prompt, and agent instruction design. Use when Codex needs to review, generate, refactor, debug, optimize, document, or test AI prompts; design reusable prompt templates; create or improve system prompts, custom instructions, agent behavior guidelines, tool-use prompts, multimodal prompts, or prompt evaluation frameworks.
license: MIT
---

# Prompt Engineering Expert

Use this skill to make prompts clearer, more reliable, easier to evaluate, and better matched to the model, task, tools, and operating context.

## Workflow

Identify the prompt's job: task, audience, model or agent context, available tools, inputs, output consumers, and failure cost.
Diagnose weaknesses before rewriting: ambiguity, missing context, conflicting instructions, brittle examples, unsafe scope, untestable success criteria, output format gaps, or token bloat.
Choose the lightest effective technique: direct instructions first; add roles, examples, structured tags, staged reasoning, tool-use guidance, or prompt chaining only when they solve a concrete issue.
Produce an improved prompt or instruction set with enough surrounding explanation for the user to evaluate the tradeoffs.
Define validation: expected behaviors, edge cases, regression cases, and success criteria.

## Response Pattern

For prompt reviews, prefer this structure:

- Diagnosis: the highest-impact issues, ordered by severity.
- Revision: a ready-to-use improved prompt.
- Why It Works: concise rationale for major changes.
- Tests: representative cases the user should run.

For prompt generation, prefer:

- Ask for missing high-risk constraints only if they cannot be reasonably assumed.
- Otherwise state assumptions and draft the prompt.
- Include variables/placeholders when the prompt should be reusable.
- Include a short evaluation checklist.

## Core Principles

- Make the task objective explicit.
- Give only the context needed to perform the task.
- State non-negotiable constraints separately from preferences.
- Specify the expected output format when downstream use matters.
- Use examples to teach patterns, not to smuggle one-off answers.
- Avoid hidden contradictions between role, task, constraints, and format.
- Prefer observable success criteria over subjective goals such as "high quality" or "good."
- Preserve model flexibility where multiple valid answers exist.
- Add safeguards for uncertainty: cite provided evidence, mark assumptions, and say what is unknown.

## Technique Selection

- Direct instruction: default for simple tasks.
- Few-shot examples: use when format, categorization, tone, or edge-case handling must be learned from examples.
- Structured tags or schemas: use when inputs, constraints, and outputs need clear boundaries or machine parsing.
- Role framing: use only when expertise, tone, or decision standards change the output.
- Staged reasoning or decomposition: use when the task has separable phases or frequent reasoning mistakes.
- Prompt chaining: use when one prompt is overloaded with extraction, analysis, transformation, and generation.
- Tool-use instructions: use when the agent must decide when to call tools, how to validate tool output, or how to recover from tool errors.
- Multimodal instructions: use when images, PDFs, spreadsheets, code, or other files require explicit inspection targets.
- See references/techniques.md [blocked] for patterns and compact examples.

## Custom Instructions And Agent Prompts

When designing system prompts, custom instructions, or agent skills:

- Define the agent's role through responsibilities and decision standards, not theatrical persona.
- Separate mandatory behavior from style preferences.
- Include boundaries: what to refuse, what to escalate, what to ask about, and what to infer.
- Keep instructions stable across turns; avoid directions that require mutating past context.
- For tool-using agents, specify tool selection, validation, retry, and user-update behavior.
- For coding agents, include repository conventions, test expectations, and change-safety rules.

Anti-Patterns
Watch for:

## Vague verbs: "analyze," "improve," "make better," "handle this."

Contradictions: "be concise" plus many mandatory sections, or "do not ask questions" plus missing required data.
Overfitted examples that teach accidental details.
Output formats described in prose when a schema or example is needed.
Prompts that invite hallucination by asking for facts without sources or data.
Security gaps: untrusted user content can override instructions, leak context, or request unsafe actions.
Token bloat from background essays, duplicated rules, and unused options.
See references/troubleshooting.md [blocked] for failure modes and fixes.

## Evaluation

Every non-trivial prompt improvement should include tests:

- Happy path with typical input.
- Edge case with missing, ambiguous, or malformed input.
- Regression case for a known failure.
- Adversarial or injection case when untrusted input is involved.
- Format compliance case when downstream parsing matters.
- See references/evaluation.md [blocked] for test templates and scoring rubrics.

## Reference Loading

Load only the references needed for the request:

- references/techniques.md [blocked]: prompting techniques, when to use each, and compact examples.
- references/troubleshooting.md [blocked]: common prompt failures, diagnosis, and fixes.
- references/evaluation.md [blocked]: prompt test cases, rubrics, and regression strategy.
- references/examples.md [blocked]: reusable prompt review, generation, classification, structured-output, and agent-instruction examples.