prompt-engineer

Prompt Engineer

Turn a rough brief into a tight, unambiguous prompt that another agent can execute with minimal guesswork. The skill runs a short interview, generates the prompt, and offers to save or print it.

When this skill runs

Two modes:

• Create mode — the user wants a new prompt from scratch.
• Refine mode — the user pastes an existing prompt and wants it tightened, restructured, or upgraded. Detect this if the user supplies a prompt and asks to "improve", "refine", "fix", "rewrite", or "upgrade" it.

If unclear, ask.

Workflow

1. Detect mode (create vs refine).
2. Discovery interview — Round 1 below. Batch the questions so the user answers once, not five times.
3. Pattern selection — pick a pattern from references/patterns.md if one matches the user's goal. If nothing fits, build from scratch.
4. Conditional questions — only ask Round 2 questions whose answers materially change the prompt.
5. Draft the prompt using the chosen format and detail level.
6. Append a test run suggestion — one or two short example invocations the user can paste in to test it.
7. Ask where it should go — save to .prompts/<name>.md (or .prompt.json for JSON format), print to chat, or both.

Round 1 — required questions (ask all at once)

Use the ask_user_input_v0 tool when available so the user can tap answers on mobile. Otherwise ask as a short numbered list.

1. Goal — what should this prompt accomplish? (one or two sentences)
2. Target model — Claude Opus, Claude Sonnet, Claude Haiku, GPT-4-class, GPT reasoning model (o-series), Gemini, or other. This shifts both format and how much hand-holding is needed.
3. Detail level — Lean or Comprehensive. See "Detail levels" below.
4. Self-verification — should the executing agent check its own output before returning? Yes or no.
5. Prompt structure format — XML tags (default for Claude), Markdown headings (good for GPT/Gemini, human-readable), or JSON (best when the prompt is generated/stored programmatically).
6. Expected output format — what should the agent return? Prose, structured JSON (with schema), Markdown, code, a list, a table, etc.

Round 2 — conditional questions

Ask only those that matter. Skip the rest.

• Variables — what inputs will be slotted into the prompt at runtime? Name them ({{customer_email}}, {{source_text}}). Skip if the prompt is self-contained.
• Background context — anything the agent needs to know that isn't obvious from the task itself: domain, audience, brand voice, prior decisions.
• Examples — does the user have 1-3 input/output pairs for few-shot? Few-shot examples lift quality more than almost any other lever; ask unless the task is trivial.
• Persona — should the agent adopt a specific role (e.g., "senior Laravel reviewer", "Australian copywriter")? If the user didn't say, infer one from the goal but mention it in the draft so they can override.
• Tools available — does the executing agent have web search, code execution, file access, MCP servers? If yes, the prompt should reference them by name and say when to use them.
• Constraints / anti-requirements — things to NOT do. These often matter more than positive instructions. Ask for at least one if the user hasn't given any.
• Stop conditions / iteration — one-shot or multi-step? When should the agent stop?

Detail levels

The user picks one. They differ in length and rigour, not quality — Lean is correct for many tasks.

Lean (~150-350 words)

Use when the task is well-defined and the model already knows how to do it (summarise, classify, rewrite, translate, simple extraction). Includes:

• Role (one line)
• Task (one paragraph)
• Inputs (named variables)
• Output format (one paragraph or short schema)
• 1-2 key constraints

No persona biography, no exhaustive instruction list, no edge-case manual. Trust the model.

Comprehensive (~500-1500 words)

Use when the task is novel, high-stakes, ambiguous, multi-step, or feeds a downstream system that breaks on malformed output. Includes everything in Lean, plus:

• Context block (domain, audience, prior work)
• Numbered step-by-step instructions
• Output schema with per-field rules and types
• 1-3 few-shot examples
• Edge case handling (what to do if input is empty, malformed, ambiguous, contradictory)
• Clarification policy (when to ask vs when to proceed with stated assumption)
• Refusal policy if relevant (what's out of scope)
• Self-verification checklist if the user said yes to verification

If the user is unsure which to pick, ask: "Is the cost of a wrong answer high enough to justify a longer prompt?" If yes → Comprehensive. If no → Lean.

Self-verification block

If the user wants verification, add a section near the end of the generated prompt that instructs the agent to silently check its output against specific criteria before returning. Tailor the checks to the task. Examples:

• For extraction prompts: "verify every field in the schema is present and typed correctly; verify no field was hallucinated outside the source text."
• For code prompts: "verify the code compiles in your head; verify it handles the edge cases listed above; verify the public interface matches what was requested."
• For writing prompts: "verify the piece answers the brief; verify tone matches the audience; verify there are no factual claims you can't back up."

The verification block should be specific — "check your work" is useless. List the actual conditions.

Prompt structure format

The three formats produce different scaffolds. See references/templates.md for full templates.

• XML (default for Claude): semantic tags like <role>, <context>, <task>, <inputs>, <instructions>, <output_format>, <examples>, <verification>. Claude is trained on this style and it parses reliably.
• Markdown: ## Role, ## Task, ## Inputs, etc. Human-readable, version-control friendly, works well for GPT and Gemini.
• JSON: every section is a key in a single object. Use when prompts are generated or stored programmatically. Variables become {{placeholder}} strings inside JSON values.

If the target model is Claude and the user has no strong preference, use XML. If the target model is GPT/Gemini and no preference, use Markdown.

Model-aware adjustments

See references/model-notes.md for full detail. Short version:

• Reasoning models (o-series, Claude with extended thinking): less explicit chain-of-thought scaffolding needed — they reason internally. Don't tell them "think step by step"; just specify what good output looks like.
• Smaller/faster models (Haiku, GPT mini): more explicit step lists, more examples, tighter output schemas. Less inference room.
• Frontier models (Opus, GPT-4-class): can handle more abstract instructions and longer context. Still benefit from clear output specs.

Output language

Any prose the generated prompt asks the executing agent to produce should default to Australian English spelling and tone, unless the user specifies otherwise. Note this in the generated prompt explicitly (e.g., "Write in Australian English: 'organise' not 'organize', 'colour' not 'color'.") — saying it in the prompt is more reliable than relying on the model to infer.

Test run suggestion

Every generated prompt ends with a short section (outside the prompt itself, or as a trailing comment) showing one or two example invocations the user can paste in to sanity-check it:

# Test run
Paste this into [target model] to verify:

[example filled-in invocation with sample variables]

Keep it short — one realistic example is enough.

Output

After drafting, ask the user whether to save to .prompts/<descriptive-name>.md (or .prompt.json for JSON format), print to chat, or both. Default file name: derive a short kebab-case name from the goal (e.g., summarise-customer-emails.md). If saving, also offer to add a # <Name> header comment with the goal, target model, and date so the file is self-documenting.

When to consult references

• references/patterns.md — read before drafting if the goal matches a common pattern (classification, extraction, agent loop, RAG, code generation, code review, summarisation, rewriting, structured-output generation). The pattern file gives you a proven scaffold to fill in.
• references/templates.md — read when generating the prompt, to get the exact XML/Markdown/JSON scaffold for the chosen format.
• references/model-notes.md — read if the target model is one you're less sure about, or if the user mentions reasoning models, small/fast models, or non-Claude/GPT models.

Refine mode

When the user pastes an existing prompt and asks to improve it:

1. Read it carefully. Don't rewrite reflexively — some prompts are fine.
2. Identify concrete issues: ambiguity, missing output format, missing examples, no edge case handling, contradictory instructions, role/task mismatch, format wrong for the target model, no self-verification when one is needed, overlong when Lean would do, too lean when Comprehensive is needed.
3. Ask the same Round 1 questions, but only the ones whose answers can't be inferred from the existing prompt.
4. Produce a rewritten version. Then list the specific changes made in a short bullet list under the rewritten prompt, so the user can see what shifted and why. Don't pad — if you only changed three things, list three.

Honesty about prompt engineering

Prompt engineering has fashion cycles. Some advice is overstated. Be honest with the user:

• "Think step by step" helps weaker/older models more than frontier or reasoning models.
• Few-shot examples beat almost every other technique for structured output.
• Long persona biographies ("You are a world-class expert with 30 years of experience…") rarely improve output; a one-line role is usually enough.
• JSON-formatted prompts are not inherently better than XML or Markdown for Claude. They're better only when the prompt is generated/stored programmatically.
• Forcing the model to "double-check" with no specific criteria mostly wastes tokens. Specific verification works; vague verification doesn't.

If the user asks for one of these techniques and it won't help their case, say so plainly and suggest what would help instead.