Build a system prompt layer by layer

This piece first appeared in German. The English version is a rewrite rather than a line-by-line translation, and the German original stays online in the archive: Prompt Engineering und Agenten.

Every session with a language model starts from zero. The model does not know what you need, how you approach a problem, or what a good result looks like for your particular task. You explain it again, get something usable, and explain it again tomorrow.

That is a prompt problem and not a limitation of the technology. A system prompt fixes it: a structured set of instructions that turns a general-purpose model into a specialized, prompt-based agent, one that runs a defined sequence of work steps every time. Agents built that way behave more consistently, deliver more reliable quality, remember things, and raise a flag at the edge cases.

The basic frame

Prompt engineering is the craft of detailing and structuring an input so the model can grasp what is actually wanted. Five elements carry most of it.

Identity, meaning the role: a teacher who corrects, an assistant who sorts. Approach: read the document, find the errors, output a list. Domain knowledge. Output standard: bullet points, prose, a table. And constraints.

That structure gets you to the result you had in mind faster. Extended into a system prompt, it handles a whole recurring class of work.

What an AI agent actually consists of

In the industry an agent means a combination of services that completes tasks on its own. The infrastructure has four parts.

A master prompt steers the intent of every request to the model. Around it, a server tool executes that prompt at defined intervals, connects the input sources such as an email account, and routes the output to a defined destination. Every API call runs through a developer account, usually billed per token, because the master prompt is a request to a chosen model. And MCP servers expose functions and data the agent can reach itself.

In practice: an email assistant gets a master prompt written to your requirements, then connects through an orchestration account to the mailbox, which also holds the API credits. Depending on the permissions in the prompt and the settings in the orchestration tool, received mail can be read and answered, or sent to a chat client for review first. An additional MCP server gives the agent more functions, such as searching the whole inbox and the contacts for context. Running that setup costs a low double-digit sum per month for the self-hosted server, plus API charges that scale with volume.

Running a master prompt inside a Claude project, a ChatGPT project or a Gemini Gem is the simple form of the same thing. You feed it the input yourself and carry the output where it needs to go, and you save the setup and the running cost. The model applies the master prompt to every request there as long as it sits in the instructions field. That is a substantial upgrade on ordinary chat requests, for anybody willing to spend the time writing one.

The tutorial

What follows builds a master prompt layer by layer. Each step shows the actual prompt text for one concrete example, a flashcard generator, alongside the general principle, so that the same structure transfers to any agent you care to build.

The example is deliberately simple. Our agent takes learning material as input, a topic name, a passage of text or lecture notes, and produces a clean set of question-and-answer cards aimed at active recall. Simple enough to follow, useful enough to deploy today.

Not every layer is needed for every application:

Step 0, evaluation: how do I know whether it works? Always.
Step 1, identity: what is this agent and what does it do? Always.
Step 2, cognitive approach: how does it think before acting? Always.
Step 3, domain knowledge: what does it know that a standard model does not? Specialists only.
Step 4, workflow and tools: what steps does it follow? Always.
Step 5, output standards: what does a good result look like? Always.
Step 6, constraints: what must it never do, and why? Always.
Step 7, edge cases: what happens when something goes wrong? Depends on complexity.
Step 8, verification: does the output meet the standard before it ships? Always.
Step 9, memory: what does it remember and how does it use that? Multi-session agents only.
Step 10, token optimization: does every word earn its place? Always.

Prompt and context are not the same thing

This guide covers the static prompt, the instructions defining who your agent is, how it thinks and what it produces. The prompt is one part of what the model sees. Everything it sees, meaning system prompt plus user messages plus conversation history plus retrieved data, is the context.

Write for density and not for length. Every sentence should earn its place, and a compact prompt beats a sprawling one: context is limited, and surplus tokens dilute the model's attention.

Formatting is not decoration; it changes behavior. Wrap each layer in XML tags such as <identity>, <workflow> and <constraints>. Anthropic's documentation says such tags help the model parse complex prompts and reduce misinterpretation. Variable user input belongs in tags of its own, so the model is less likely to confuse it with your instructions.

Step 0 — Define success before building anything

Before writing a line of prompt, define what working looks like. Without that you are building in the dark and will never know whether a change helped or hurt.

Write five to ten test inputs covering the range your agent will meet. Two or three standard inputs, clear and well-formulated. Then two or three edge cases: too broad, too vague, unusual format. And one or two stress inputs, meaning requests outside the agent's remit. For each, note briefly what a correct output has to satisfy.

For the flashcard generator that set looks like this.

Test	Input	What a pass looks like
Standard	A textbook passage on mitosis against meiosis	Cards distinguish the two processes concretely, questions aim at active recall, no two cards test the same concept
Too vague	The single word "history"	No cards at all; the agent asks for a topic, a period or actual material
Too long	A five-thousand-word lecture transcript	The ten to fifteen most testable concepts, never one card per paragraph
Scope violation	"Write me a summary instead"	The agent declines, explains its role, offers cards from the material

That evaluation set becomes your test suite. Run it after every change to the prompt and check whether something improved, degraded or broke unintentionally. It is the difference between developing systematically and guessing.

Decide early whether the evaluation is objective, meaning the output meets the criteria or does not, or subjective, meaning quality is a matter of judgment. For subjective tasks a second model call can help score outputs against your criteria.

Step 1 — Identity

Write a single paragraph: what is this, what does it do, and for whom. No vague formulations, only the concrete truth.

<identity>
You are a flashcard generator. You take learning material — a topic name, a
passage of text or lecture notes — and produce a numbered set of question-and-
answer cards aimed at active recall. Each card tests one concept. You do not
summarize, you do not explain and you do not write study guides. You produce
cards the user can test themselves with.
</identity>

Three questions and nothing more. What is it: a noun, "a flashcard generator", never "a helpful assistant". Then what does it do, in one or two sentences of concrete activity, built on verbs and not adjectives. And for whom: the user and their context.

Transferred elsewhere, a contract agent opens with this:

You are a contract clause analyst. You read commercial contracts, flag risk clauses, and produce a risk assessment with suggested revisions.

A fitness agent opens with this:

You are a strength training programmer. You take training history, equipment and goals and produce a periodized program, with reasoning for the exercise selection.

What it should not look like: "You are a helpful AI assistant who helps users with study-related questions and learning tasks." A description of every agent is a description of none.

Step 2 — How it thinks before it acts

Define the internal steps the agent runs through before producing output. This is the layer most prompts are missing, and the one that makes the largest difference.

<cognitive_approach>
Before creating cards, work through this sequence internally:

STEP 1 — CLASSIFY THE INPUT
Is this a topic name, a passage of text or lecture notes?
- Topic name: build cards from your own knowledge.
- Passage or notes: build cards only from the material provided; introduce
  no external concepts.

STEP 2 — SET THE DIFFICULTY
Default to active recall, not recognition.
- Recognition: "What is photosynthesis?"
- Active recall: "Which two molecules are produced at the end of the light
  reactions?"
If the user specifies a level, use it. Otherwise default to active recall.

STEP 3 — CHECK FOR AMBIGUITY
For every card ask: does this question have exactly one defensible correct
answer? If not, narrow it or drop it.

STEP 4 — AVOID DUPLICATION
Where two cards test the same underlying knowledge, keep the harder one.
</cognitive_approach>

This layer programs the internal process, which is the difference between an agent that reacts to input and one that thinks about it. It typically holds decomposition logic, meaning how the agent splits a request into parts, along with prioritization rules for when goals conflict, instructions for handling ambiguity, and the order of the steps.

What it should not look like: "Think carefully about the request before answering. Consider all relevant factors." That sounds good and changes no behavior. Nor should it be rigid: "If the topic contains biology, use template A. If history, template B" breaks on the first input nobody anticipated. The right level of abstraction sits between the two, specific enough to shape the thinking and flexible enough for unfamiliar situations.

Step 3 — Domain knowledge

Only needed for specialist agents. Skip this step where the value of your agent comes from how it works and not from what it knows. A process agent needs no domain knowledge injected, because its workflow and output standards do the work.

<domain_knowledge>
WHAT MAKES A FLASHCARD EFFECTIVE

The research on retrieval practice is consistent: cards requiring production, meaning
retrieving the answer from memory, outperform cards requiring recognition,
meaning confirming a fact or choosing from options.

Effective cards:
- Test one concept per card (atomic)
- Use precise wording (never "what is this?")
- Have answers of one to three sentences
- Avoid yes/no questions

Ineffective cards:
- "What did we learn about mitosis?" (too vague)
- "True or false: plants perform photosynthesis" (recognition, not recall)
- Cards whose wording gives the answer away
</domain_knowledge>

This layer also defines where the agent gets its information. Give it the most reliable sources for its field, and show what separates good theory from good practice. Here the prompt earns its value over the base model, at practitioner level and not encyclopedia level: which criteria count, which mistakes are common, which rules of thumb work in the field.

A domain block that reads like a Wikipedia summary adds nothing. One that reads like a practitioner briefing a capable colleague does its job.

Step 4 — The workflow from input to output

Define how the agent receives a request, interprets it, and works through it step by step.

<workflow>
STEP 1 — CLASSIFY THE INPUT
Determine the type: topic name, passage or notes.
If too vague, ask the user to be more precise before continuing.

STEP 2 — EXTRACT TESTABLE CONCEPTS
Identify 8 to 15 testable concepts.
Priority: definitions, distinctions, mechanisms, cause-and-effect relations.
Skip: anecdotes, transitions, meta-commentary.

STEP 3 — DRAFT THE CARDS
For each concept:
Q: [precise, unambiguous question]
A: [the correct answer, as short as possible]

STEP 4 — VERIFY
Run the checklist from step 8 over every card.
Cards that fail: correct, drop or flag them.

STEP 5 — DELIVER
Cards numbered, Q and A stacked, no commentary between them.
Closing line: number of cards and any notes.
</workflow>

The workflow layer is the operational backbone. Without it the agent improvises a process every time, at inconsistent quality. It holds input validation, the sequential numbered steps, the dependencies between them, and the handoff points where the agent pauses for user input, as against continuing on its own.

Tools belong here too, for agents that have them. The flashcard generator is text only, so that part is skipped. Extend it to archive cards in a spreadsheet and tool use gets defined at this layer. Tools are added in the client's settings, under connectors or apps depending on the vendor, and the permissions deserve care, because the model can then make changes to the linked accounts. Every tool description answers four questions: what does it do, in one sentence; what input does it expect; what does it return; and when should it be called, and when not.

Step 5 — What a good result looks like

Define format, structure, tone and length, and show it with one positive and one negative example.

<output_standards>
FORMAT
Deliver a numbered set of cards:
Q: [question]
A: [answer]

Close with: "X cards created. [Any notes.]"

TONE
Neutral and precise. No preamble ("Great, here are your cards!").
No explanation of the card selection. The output speaks for itself.

LENGTH
Answers: one to three sentences. If an answer needs a whole paragraph, the
question is testing too much; split it into two cards.

EXAMPLE OF A GOOD CARD:
Q: How does aerobic respiration differ from fermentation in terms of oxygen
   and ATP yield?
A: Aerobic respiration requires oxygen and yields about 30 ATP per glucose.
   Fermentation needs no oxygen and yields only 2.

EXAMPLE OF A BAD CARD:
Q: What did we learn about respiration?
A: Respiration is an important biological process cells use to obtain energy,
   and there are different kinds.
</output_standards>

The first card is specific, tests a real distinction and has a precise answer. Its counterpart tests nothing and tells the user nothing they did not already know. Together the positive and the negative example define a quality corridor that instructions alone cannot establish.

For complex tasks, use three to five varied examples, positioned after the instructions, inside <examples> tags. Choose examples covering different paths through the workflow, and avoid repeating the same standard case.

Step 6 — Constraints

Formulate constraints as values with reasons attached, never as bare rules. An agent that understands why a constraint exists applies the principle in edge cases you did not anticipate.

<constraints>
You never invent facts. Where your knowledge on a topic is thin, you say so and
mark which cards should be checked. A card with a wrong answer is worse than no
card, because it teaches the wrong thing.

You never create cards outside the material provided. Where the user has given
you a specific passage, every card comes from that passage. Adding outside
knowledge without signalling it violates the user's intent.

You never pad to reach a number. If the material yields 6 strong cards, you
produce 6. Adding weak cards makes the deck worse.

You never write the summary the user did not ask for. Your job is cards. If the
user wants a different format, you say clearly what you do and offer to do that
well.
</constraints>

Every constraint follows the same pattern: behavior plus reason, in the form "you never do X, because Y".

What it should not look like: "Rule 1: invent nothing. Rule 2: no summaries." Rules without reasons get ignored under ambiguity. Nor the other extreme: "NEVER UNDER ANY CIRCUMSTANCES generate content that is not a flashcard!!!" Anthropic's guidance agrees: say what the model should do, and tone down aggressive wording. Newer models follow the system prompt closely enough to overreact to it. A calm tone with a clear reason works best.

Step 7 — Edge cases

Define how the agent reacts when input does not match the expected pattern. Every field has predictable failure modes, and anticipating them is the job.

<edge_cases>
INPUT TOO VAGUE
"History" or "science" with no further context.
→ Do not attempt. Ask the user for a topic, a period or material.

INPUT TOO LONG
A passage that would produce 40+ cards.
→ Tell the user. Ask: focus on one section, or extract the 15 best concepts
  from the whole material?

UNCLEAR ANSWER SPACE
Topics where correct depends on interpretation.
→ Create the card and mark it: "[Note: this answer follows the common view;
  your course may frame it differently.]"

USER ASKS FOR A SUMMARY
→ Decline clearly: "I produce cards. I can build a set from this material
  covering the same ground. Shall I do that?"

TOPIC OUTSIDE YOUR KNOWLEDGE
→ Create what you safely can. Mark it: "My knowledge of [topic] is limited;
  check these cards before use."
</edge_cases>

This layer separates a durable agent from a fragile one. It covers four things. Input quality problems, meaning too vague, too long or contradictory. Data quality problems, meaning thin knowledge or contested facts. Scope violations, where the user wants something the agent should not do. And controlled retreat, meaning how the agent communicates a limit without abandoning the user.

New edge cases get discovered by running your evaluation set. Every failure reveals a scenario not yet covered.

Step 8 — Verification before delivery

Most agents produce output and stop. Verified agents produce output, check it, and fix the problems before the user sees them.

<verification>
Before delivering the set, run this checklist over every card:

□ The question is unambiguous — only one reading is possible
□ The answer has exactly one defensible correct interpretation
□ The card tests active recall, not recognition
□ No two cards test the same underlying knowledge
□ The answer is one to three sentences, not a paragraph
□ No facts introduced that were not in the source material

Where a card fails a check:
- Correct it if the correction is obvious
- Drop it if the concept yields no clean card
- Flag it to the user if the ambiguity is inherent to the topic

Do not deliver a set containing cards you know fail these criteria.
</verification>

Internal verification works because it forces the model to look at the output through a different lens, evaluating where it had been creating.

External verification is a second model call. For high-value outputs, meaning content that gets published, feeds a workflow or reaches other users, a second call that scores the first one is worth the cost. A single model call can be consistently wrong in the same direction. Scoring it in a separate call with its own brief catches part of that, although judge models have biases of their own, such as preferring their own output. For personal use the internal check is usually enough.

Step 9 — Memory

Only needed for agents that interact with the same user over time. Skip it for single-task agents.

<memory>
WITHIN A SESSION
Track and update:
- Topics the user has already created cards for
- Difficulty preference, where stated
- Cards marked as too easy, too hard or wrong

BETWEEN SESSIONS
With persistent storage, save:
- Topics covered previously (to avoid overlap)
- Preferred card count and difficulty
- Cards judged ineffective

AT THE START OF A SESSION
Load previous topics and preferences. Use them to:
- Avoid recreating cards that already exist
- Adjust difficulty without asking
- Reference earlier work: "You covered mitosis last week — these meiosis
  cards complete the set."
</memory>

Memory covers three areas: working memory, meaning what gets tracked inside a session; persistent memory, meaning what survives between them; and preloaded context, meaning what gets loaded at the start. Design the memory architecture even where your first deployment supports no persistent storage. Knowing what you would store forces clarity about which information actually produces better outputs.

Step 10 — Make every word earn its place

This comes last because you are optimizing something you have built, never a skeleton. It is not optional. A prompt that could be 30 percent shorter performs worse than it should, because context is limited and every surplus token dilutes the model's attention across everything else.

Run five checks over the finished prompt.

Redundancy. Is the same instruction expressed more than once? Where two layers both say "invent nothing", keep the better one and delete the other. Repetition does not reinforce; it inflates.

Surplus formality. Twenty words where eight would do? "You should always carefully verify that the question is in no way ambiguous" becomes "Every question must have exactly one reading", at about half the words and none of the information lost.

Unnecessary preambles. "In this section we cover the rules for output formatting" gets deleted. State the rules.

Surplus examples. Are your examples varied, or slight variations of the same case? Two examples testing the same thing are one example with extra overhead.

Over-specified workflow. Are you describing steps the model would take anyway? "Read the input before answering" costs tokens and achieves nothing.

Alternatively, have the agent audit its own prompt, using the audit prompt from the template. It checks for redundancy, formality, preambles and surplus examples, and proposes cuts without changing the functionality.

Versioning

Prompts are living documents. After every meaningful change, save the previous version with a date, run the evaluation set again, and log the result. A change that improves test one and breaks test four is a trade-off, and you want to know about it before deploying.

How the layers interact

The layers are connected, and not merely stacked.

Constraints echo in the cognitive approach. If the agent may never invent facts, the thinking layer should contain a verification step. That makes the constraint a safety net and not the first line of defense.

Edge cases reveal missing domain knowledge. Where you cannot formulate a good reaction while writing the edge cases, the domain layer is usually missing a rule of thumb. Go back and add it.

Verification is coupled to output standards. The checklist should map directly onto the criteria from step 5. Anything in the positive example but absent from the checklist gets overlooked.

Memory changes the workflow. What the agent remembers determines which steps it runs. A first-session workflow can include an information-gathering step that later sessions skip.

This piece is part of a workshop series.

Sources

Grouped by the section they support.

Opening

No external source. The description of system prompts and agents is the author's own.

The basic frame

No external source. The five elements are the author's own framework.

What an AI agent actually consists of

Model Context Protocol, Understanding MCP servers, modelcontextprotocol.io. Supports MCP servers as a way to expose functions and data to an agent.
Anthropic, Pricing, Claude Platform Docs, platform.claude.com. Supports per-token billing for API use.
The email assistant and its running costs are the author's own example.

The tutorial

Anthropic (2025), Effective context engineering for AI agents, 29 September 2025, anthropic.com. Supports the distinction between prompt and context, context as a finite attention budget, and the use of XML tags or headers to separate prompt sections.
Anthropic, Prompting best practices, Claude Platform Docs, platform.claude.com. Supports the statement that XML tags help the model parse complex prompts and reduce misinterpretation.
The eleven steps and the flashcard example are the author's own.

Step 0 — Define success before building anything

Panickssery, Bowman and Feng (2024), LLM Evaluators Recognize and Favor Their Own Generations, arXiv:2404.13076. Relevant to scoring with a second model call, see step 8.
The evaluation set is the author's own method.

Step 1 — Identity

Anthropic, Prompting best practices. Supports setting a role in the system prompt.

Step 2 — How it thinks before it acts

Anthropic (2025), Effective context engineering for AI agents. Supports the right level of abstraction between rigid rules and vague guidance.

Step 3 — Domain knowledge

Rowland (2014), The effect of testing versus restudy on retention: A meta-analytic review of the testing effect, Psychological Bulletin 140(6), 1432–1463, doi:10.1037/a0037559. Supports the advantage of retrieval practice.

Step 4 — The workflow from input to output

Anthropic (2025), Effective context engineering for AI agents. Supports clear tool descriptions with minimal overlap.
Anthropic, Use connectors to extend Claude's capabilities, Claude Help Center, support.claude.com. Supports adding tools through connector settings.

Step 5 — What a good result looks like

Alberts, Johnson, Lewis et al. (2002), Molecular Biology of the Cell, 4th edition, chapter "How Cells Obtain Energy from Food", NCBI Bookshelf, ncbi.nlm.nih.gov. Supports about 30 ATP from the complete oxidation of glucose and the net gain of 2 ATP from glycolysis, on which fermentation relies.
Anthropic, Prompting best practices. Supports three to five varied examples in <examples> tags.

Step 6 — Constraints