| name | prompt-engineering |
| description | Prompt engineering workflow for designing, rewriting, debugging, evaluating, and optimizing LLM prompts, system prompts, developer prompts, few-shot examples, structured-output instructions, tool-use prompts, and prompt eval cases. Use when prompt behavior, reliability, safety, cost, latency, or model fit is the main task. Do not use for generic prose editing, model selection alone, or ordinary documentation work with no prompt artifact. |
Prompt Engineering
Treat prompts as small behavioral specs. Improve them by naming the job,
testing the behavior, changing one important thing at a time, and preserving
the prompt's operating context.
Core Workflow
- Scope the prompt job.
Identify the target model or provider, audience, runtime surface, inputs,
tools, output contract, constraints, and where the prompt will live. If the
prompt belongs to a repo, inspect existing prompts, schemas, examples,
tool definitions, evals, logs, and docs before asking avoidable questions.
- Define success before rewriting.
State the desired behavior, hard requirements, acceptable variation, known
failure modes, and evidence that would prove the prompt improved. If success
is vague, turn it into 3-7 concrete cases before editing.
- Choose the lightest pattern that fits.
Use direct instructions for simple tasks, structured sections for context
control, few-shot examples for format or judgment calibration, schemas for
machine-readable output, tool-use instructions for action boundaries, and
repetition only when the model repeatedly drops critical constraints.
- Draft with clean boundaries.
Put task, context, constraints, examples, tools, and output format in
separate labeled sections. Delimit user-controlled or retrieved content
clearly. Keep stable instructions before variable content when prompt
caching, reuse, or maintainability matters.
- Evaluate against reality.
Test representative, edge, adversarial, and regression cases. Compare outputs
against explicit criteria instead of intuition. Record which failures changed
and which remained.
- Iterate deliberately.
Change one major variable at a time: instruction wording, context ordering,
examples, output schema, tool contract, reasoning guidance, or model
settings. Preserve the previous prompt and test cases until the new version
wins on the target criteria.
- Ship the prompt with evidence.
Return the final prompt, assumptions, changed behavior, eval cases, expected
outputs or grading criteria, remaining risks, and any provider-specific
settings the caller must preserve.
When To Use
- design, rewrite, debug, or review an LLM prompt
- create or revise a system prompt, developer prompt, tool-use prompt, few-shot
examples, structured-output instruction, grader prompt, or prompt eval set
- investigate why a prompt is unreliable, unsafe, too costly, too slow, or
mismatched to a target model
- optimize an existing prompt while preserving behavior and evidence
Not For
- model selection alone
- generic prose editing, README writing, marketing copy, or voice matching
- ordinary LLM integration code when the prompt behavior is not the main issue
- security review where data exposure, authorization, tenant isolation, or tool
abuse is the central risk
Compose With
- When the session provides an OpenAI docs skill or official-doc tool, use it
for OpenAI-specific current model, API, structured-output, tool-calling,
reasoning, caching, or pricing behavior; otherwise verify official OpenAI
docs directly. For other providers, verify current official provider docs
when those details affect the prompt.
- Add a testing workflow when the main job is test strategy, evidence quality,
grading design, or acceptance criteria rather than prompt wording.
- Add a security workflow when prompt injection, hidden instruction leakage,
unsafe tool use, data exposure, or trust boundaries dominate the risk.
- Ownership rule with
context-engineering: picking which facts, files,
or examples to load is context-engineering; deciding how to word the
prompt, schema, or example is this skill. When work spans both, draft the
context packet first, then own the prompt artifact here.
Prompt Design Rules
- Put the user's real task first; do not optimize a prompt before the objective
and failure mode are clear.
- Prefer explicit success criteria over broad "be better" instructions.
- Separate stable policy from per-request data and untrusted content. When the
prompt embeds retrieved or user-supplied material, fence it with explicit
delimiters (e.g.
<<untrusted:source>> ... <</untrusted>>, matching the
context-engineering convention) and tag fact provenance with
[src:code|user|tool|docs|memory|inferred] so downstream graders can detect
leakage and instruction-override attempts.
- Specify output shape with examples or schemas when downstream code depends on
structure.
- Use examples that demonstrate decisions, not examples that merely repeat the
instruction.
- Include negative and boundary cases when failure would be costly, silent, or
hard to notice.
- Keep prompts short enough to maintain; move large context to retrieval,
tools, files, or references when possible.
- Verify current official provider guidance before making model- or API-specific
claims. Do not rely on memory for rapidly changing model behavior.
- Treat provider guidance as conditional. Load provider notes only when the
target model, API, or runtime surface makes them relevant.
Anti-Patterns
Prompts that look polished but fail in practice:
- Over-explanation: repeating the same instruction in three different
registers; the model averages them and weakens all three.
- Role stacking: layering "you are an expert X, careful Y, helpful Z"
before the task; clutter without behavioral effect.
- Examples that contradict instructions: when a few-shot demo violates a
rule, the example wins.
- Repetition without structure: restating constraints in prose instead of
putting them in a labeled section or schema.
- Vague quality bars: "be helpful", "be thorough", "use best practices"
without observable criteria.
- Schema mixed with freeform: asking for JSON and commentary; the model
picks one and the parser breaks.
Failure Diagnosis
When a prompt fails, classify the failure before rewriting:
- missing context: the model did not receive facts it needed
- ambiguous instruction: multiple reasonable outputs satisfy the prompt
- weak output contract: format, fields, or refusal behavior are underspecified
- bad examples: examples teach the wrong pattern or conflict with rules
- context collision: retrieved, user, or tool content overrides intent
- tool boundary drift: the model calls tools too early, too late, or with bad arguments
- model mismatch: the prompt assumes capabilities, settings, or reasoning behavior the model does not provide
- evaluation gap: the prompt looks better on anecdotes but fails representative cases
Output Shapes
Omit Original Prompt Or Version and Run Metadata for tiny rewrites when
they are unavailable or not material.
For a prompt rewrite:
## Original Prompt Or Version
...
## Final Prompt
...
## What Changed
...
## Eval Cases
...
## Run Metadata
...
## Assumptions And Risks
...
For prompt debugging:
## Diagnosis
Failure category and evidence.
## Original Prompt Or Version
...
## Revision
Changed prompt section or full prompt.
## Validation
Cases that should pass, fail, or remain uncertain.
## Run Metadata
...
Reference Map
