System Prompt Assembly

System prompt assembly is how an agent harness builds system instructions from sources such as identity, tool guidance, runtime information, and a skill catalog. The harness also prepares separate tool definitions and conversation context. A file can exist on disk without contributing a single word to the request.

If an agent misses a fact already written in MEMORY.md, first check whether that text was actually sent. Here, the file holds a private preview address. The default request omits it because memory loading is Off.

Think of preparing a briefing packet. You can put a document's title in the table of contents without attaching the document. The recipient gets the packet you assembled, even if your desk holds everything needed to answer the question. A skill catalog and an unread memory file create exactly this distinction.

How System Prompt Assembly Works

The harness is the application around the model. Before a request, it selects source material and places it into the fields expected by the model API. This lesson uses a small, deterministic harness with three fields:

Within system, four sections always appear: Identity, Tool guidance, Runtime, and User preferences. Each has a heading and a body. The harness joins them in that order, with blank lines between sections. A fifth section, Available skills, appears when the skill is enabled.

These sections have different sources. The identity describes the assistant's job. Tool guidance says to read a file before proposing an edit. The environment supplies Workspace: /demo/docs. User settings supply Use concise English. Combining them produces one system document while preserving the boundary between each source.

The tool guidance is ordinary prose. The tool definitions are separate structured records: Read takes path; Edit takes path, old_text, and new_text. Attaching these definitions performs no file operation. Executing a requested tool belongs to the tool-calling loop.

The exact boundaries depend on the runtime. For example, the Agent SDK customization guide distinguishes additions to the system prompt from project context delivered through the conversation. Here, skill bodies and memory are placed into labeled message blocks. That placement is this harness's convention, not a universal rule for every agent product.

System Prompt Assembly Step by Step

The default request asks: “Where is this project's private preview?” The skill is set to Loaded, and memory loading is Off. Both source files exist in the fixture.

1. Build the four base sections. Copy the identity, tool guidance, workspace environment, and user preference into system, one section per beat. None supplies the preview address.
2. Add the skill catalog. The fifth section contains docs-check: Review documentation changes. It describes what the skill does. It does not contain the skill's instructions.
3. Check activation and load the skill body. Loaded means an explicit selection has already asked the harness to provide this skill. It copies Check every relative link in the changed page. from skills/docs-check/SKILL.md into a labeled context block. The original file remains available.
4. Check memory loading and omit its body. MEMORY.md contains Private preview: https://preview-cedar.example. Loading is Off, so this text stays outside the request. The omission does not delete the file.
5. Finish the request. Seal the five-section system document, attach the two tool definitions, and build the user message. Its two text blocks contain the loaded skill instructions and the user's task.
6. Inspect the payload. A search finds relative link in the skill block. It finds no https://preview-cedar.example anywhere in the request. The animation stops here, before any model response.

The request is structurally complete, but it lacks the private fact the task asks about. Turning Load memory On adds that fact to the message content. The system prompt and tool definitions remain byte-for-byte equivalent to the corresponding Off run.

A Listed Skill Supplies a Description; a Loaded Skill Supplies Instructions

A skill has three states in the experiment. Disabled omits both its catalog entry and its body. Listed includes its description in system. Loaded includes that same description and also copies its instructions into message context. Moving from Listed to Loaded changes what the request says about how to perform the work, even though its number of system sections stays at five.

This is an example of progressive disclosure: provide enough metadata to discover a skill, then supply its detailed instructions when selected. The Agent Skills integration guide describes this separation and allows explicit user activation. The experiment starts from that explicit selection; it does not simulate a model deciding which skill to use.

Memory loading is independent. Try Listed with memory On: the private preview address is available while the skill instructions remain absent. Then try Loaded with memory Off: the instructions are available while the address remains absent. Those two requests demonstrate why “the agent has the files” is too imprecise to diagnose a context problem.

Each row also carries two tool definitions and one task block. These counts describe the request's structure; they are not token counts.

When debugging an agent, inspect the assembled request as well as the source files. Search for the missing instruction or fact, then locate the field that carries the match. With both files loaded here, the preview address is in messages[0].content[1]: the second text block of the first message. With only memory loaded, it moves to messages[0].content[0]. With memory Off, it matches no field. A correct source file cannot supply evidence to the current request if its contents were never included. The context and memory lesson follows what happens when supplied context later needs to be summarized or carried into another session.

Edge Cases

• No optional bodies loaded. The request still has its base instructions, tool definitions, and task. Its lack of file context is visible rather than replaced with fabricated content.
• Skill disabled. The harness omits the Available skills section entirely. It does not advertise an unavailable skill with an empty body.
• Catalog present, instructions absent. This is the normal Listed state. Finding the skill name in the payload does not prove that its body was loaded.
• Memory file present, loading off. The file persists, but its address is absent from the assembled request. Nothing in the experiment predicts whether a model would guess, ask for help, or request a file read.
• Both bodies loaded. The user message has three text blocks: skill instructions, memory, and the task. Inclusion supplies evidence; it does not guarantee that a model uses it correctly.

Common Mistakes

• Calling the entire input a system prompt. In this request format, system, tools, and messages are separate application-visible fields. Tool definitions have their own field even though a provider may serialize them into model input internally. The tool-use documentation describes that distinction.
• Treating a catalog entry as full instructions. Compare the short description with the body-only direction to check relative links. They are different text with different jobs.
• Treating assembly order as instruction authority. Numbered sections show where text was appended. They do not establish a conflict-resolution hierarchy, and later text does not automatically win.
• Reading source availability as model knowledge. Presence on disk, presence in a catalog, and presence in the request are separate facts. Check the last one when diagnosing missing context.
• Assuming loaded text is trustworthy or obeyed. Loading establishes availability. Trust, instruction precedence, and model behavior require separate treatment.

A Note on Simplification

This is an explainer, not a substitute for formal training in agent systems. It uses authored in-memory sources and a small request assembler, with no model response. The section order, explicit activation state, and context placement are illustrative choices. Real runtimes also handle permissions, instruction precedence, untrusted content, tokenization, caching, context limits, and provider-specific formatting. No private system prompt is reproduced, and no model behavior or token cost is measured here.