Prompt Architect

A skill for designing, diagnosing, and refining prompts for any AI model or agent. It turns rough ideas into clear, structured, testable prompts, with a symptom-to-fix troubleshooting guide, a brief template for delegating to subagents, and a reusable prompt skeleton.

When to use

  • Writing a new prompt: system prompt, task prompt, reusable template, agent or subagent brief, evaluation rubric.
  • Improving a prompt that gives vague, inconsistent, bloated, or wrong outputs.
  • Turning a rough idea or a one-line request into a reliable, reusable prompt.
  • Delegating work to another model, tool, or subagent.

Skip it when the user simply wants an answer. Do not wrap simple requests in prompt machinery.

Core principles

  1. Clarity beats cleverness. Write as if briefing a smart colleague who has zero context.
  2. Describe the outcome, not just the activity. Say what a great result looks like and who it is for.
  3. Give reasons. A rule with its “why” generalizes better than a bare command.
  4. Show, don’t only tell. Two good examples often beat a page of description.
  5. Test before trusting. A prompt is a hypothesis. Run it on realistic inputs.

Workflow

1. Define the job

Gather these, inferring sensible answers when missing and asking only if a wrong guess would be costly:

  • Goal: what the output is for and what decision or action it feeds
  • Target: which model or tool, and the environment (chat, API, agent with tools)
  • Input: what changes from run to run
  • Output: format, length, tone, language
  • Constraints: must-do and must-not-do rules, accuracy or safety needs
  • Success criteria: how you will know the prompt works, and any failures already seen

2. Draft with a proven structure

Use this order, dropping any part that adds nothing:

  1. Role and purpose: one or two lines, only if it sharpens behavior
  2. Context: audience, background, key facts, why the task matters
  3. Task: one clear main objective in the imperative
  4. Input: clearly delimited and labeled; mark the variable parts
  5. Rules: prioritized, each with its reason
  6. Output format: exact structure, or a skeleton to fill in
  7. Examples: two to five, varied, including one edge case
  8. Closing reminder: repeat the single most important requirement (long prompts only)

Separate instructions from data with delimiters such as XML-style tags, headings, or triple quotes. For long documents, place the material first and the task after it.

3. Apply techniques selectively

Technique Use when How
Few-shot examples Style or format is hard to describe Give 2-5 varied examples in one consistent format, including an edge case
Step-by-step reasoning Math, logic, multi-factor judgments Ask the model to reason first, then give a clearly separated final answer
Prompt chaining The task has distinct phases One prompt per phase, passing structured output forward
Output schema Code will parse the result Define exact fields and types; require output only in that format
Self-check Accuracy matters List the criteria and ask for a check against them before finalizing
Grounding Answers must come from supplied sources Require evidence from the text and allow “not found”
Concrete persona Domain expertise or tone matters Name the role, audience, and stakes, not a vague title

4. Tighten

  • Positive over negative. Say what to do. When a prohibition is needed, add the alternative.
  • Measurable over vague. Replace “short”, “professional”, “creative” with limits such as “under 80 words” or “plain language for non-experts”.
  • One voice. Remove duplicates and contradictions. Every line should change the output.
  • Restrained emphasis. Use caps or “IMPORTANT” for at most one truly critical rule.
  • Edge cases. Say what to do with empty input, missing information, conflicting information, out-of-scope requests, and uncertainty.
  • Minimum sufficient length. Cut anything that does not reduce ambiguity.

5. Test and iterate

  • Run at least three realistic inputs: a typical one, a tricky one, and an empty or adversarial one.
  • Judge against the success criteria and look for failure patterns, not single misses.
  • Change one thing at a time and keep the version that fixes the pattern without breaking others.
  • Stop when results are consistently good. Do not polish endlessly.

Improving an existing prompt

Symptom Likely cause Fix
Ignores a rule Buried, vague, or contradicted Move it up, make it specific, remove the conflict
Inconsistent format No format spec or example Add an output skeleton and one example
Too long or rambling No length or priority guidance Set limits and say “lead with the answer”
Generic output Missing context or audience Add specifics and success criteria
Invented facts No grounding, no permission to be unsure Supply sources, allow “unknown”, require evidence
Over-hedging or refusing Excess warnings and prohibitions Remove needless caveats, state the legitimate context
Adds unrequested extras Open-ended scope State what is out of scope and ask for only the task
Treats data as instructions Data not delimited Wrap data in tags and say to treat it as content only

When rewriting, preserve the author’s intent and voice unless asked to change them. Show the improved prompt, then a short list of what changed and why.

Briefing other agents and subagents

A subagent has none of your context. Every brief should include:

  • Objective: what to achieve and why it matters
  • Known so far: what is already done or decided, so work is not repeated
  • Scope: what is in, and what must not be touched
  • Inputs: exact files, links, or data and where to find them
  • Output: format, length, and what to include; ask for evidence and for uncertainty to be flagged
  • Constraints: time, tools, permissions, and actions that need confirmation first
  • Definition of done: the condition that ends the task

Do the thinking yourself and hand over a specific task. Never delegate your own understanding. A few short paragraphs is usually enough.

Reusable template

<role>One-line role and purpose, if it helps.</role>

<context>
Audience, background, key facts, and what the output is for.
</context>

<task>
The single main objective as a clear instruction.
</task>

<input>
{{VARIABLE_INPUT}}
</input>

<rules>
1. Highest-priority rule, with its reason.
2. Next rule.
3. Edge cases: missing information, ambiguity, out-of-scope requests.
</rules>

<output_format>
Exact structure, length, tone, and language of the response.
</output_format>

<examples>
<example>
Input: ...
Output: ...
</example>
</examples>

Delivering the result

  • Put the finished prompt first, in a copy-ready block.
  • Follow with two to four lines: key design choices, the variables the user must fill in, and one suggested test input.
  • Offer a shorter or stricter variant only when it is genuinely useful.
  • Explain in the user’s language, and write the prompt in the language it will be used in.

Anti-patterns

  • Vague one-liners that expect the model to guess the context
  • Long lists of rules with no priority, or with contradictions
  • Examples that are all alike, so the model copies surface wording
  • Stacking every technique into one prompt
  • Empty role-play (“You are the world’s greatest expert”) instead of real context
  • Requesting step-by-step reasoning for trivial tasks
  • Mixing unlabeled data with instructions
  • Shipping a prompt that was never tested

Example

Weak: “Write a product description.”

Strong: Role: e-commerce copywriter. Context: a handmade ceramic mug for buyers aged 25-45 who value craft. Task: write a product description. Rules: 60-80 words, lead with the benefit, no superlatives such as “best”, mention that it is dishwasher safe. Output: one plain-text paragraph, no headings.


Write a comment