---
title: Instructions
description: Add system context or durable user context with instructions.md or instructions.ts.
url: "https://eve.dev/docs/instructions"
docs_index: /llms.txt
---

> For an index of all documentation, see [/llms.txt](/llms.txt).

Instructions are text you write for the model in `agent/instructions.md` or `agent/instructions.ts`. Use system-role instructions for the agent's identity and standing rules. Use user-role instructions for application context that belongs in the conversation history, such as an imported brief or retrieved memory.

## Author instructions

The smallest instructions are a markdown file at the agent root. Its contents are the prompt:

```md title="agent/instructions.md"
You are a concise assistant. Use tools when they are available.
```

Keep this file to stable behavior such as identity, tone, and standing rules.

## System and user roles

System-role instructions stay outside the conversation history, and eve includes them on every model call. When you deploy a new version, or `eve dev` reloads, existing sessions use the current system instructions.

eve adds static user-role instructions to a new session's history once, in source order. A newer deployment doesn't add them again or replace them.

## Markdown vs TypeScript

Put a static system prompt in markdown (`agent/instructions.md`). Switch to a TypeScript module (`agent/instructions.ts`) when you need typed composition, `lib/` code, build-time values, or a user-role message:

```ts title="agent/instructions/brief.ts"
import { defineInstructions } from "eve/instructions";
import { buildCustomerBrief } from "../lib/customer";

export default defineInstructions({
  content: buildCustomerBrief(), // blank content adds nothing
  role: "user", // "system" or "user"; omit for "system"
});
```

The module, including its ESM and [asset imports](./reference/typescript-api#asset-imports) such as a prompt imported with `?raw`, runs once at build time and never at runtime. See [Authored module lifecycle](./reference/typescript-api#authored-module-lifecycle).

## Split instructions across a directory

For more than one file, add an `agent/instructions/` directory. eve reads its `.md` files and `.ts` modules, but not subdirectories. A `.ts` file can export `defineInstructions` or `defineDynamic`. Static system and user entries apply in alphabetical filename order (`localeCompare`).

A root `agent/instructions.md` (or `.ts`) can sit beside the directory, and the root file comes first. Having both `instructions.md` and `instructions.ts` at the root is a build error.

## Dynamic instructions

To compute instructions from auth, tenant, channel, or external data, use `defineDynamic((ctx) => ...)` and return `defineInstructions(...)` or `null`. The function runs before each ordinary model call. Use `ctx.memo(key, fn)` to keep a JSON result fixed for a key.

A dynamic system instruction applies, outside history, while the function returns it.

A dynamic user instruction joins the conversation history only when its content changes:

- Before a turn's first model call, it joins ahead of the turn's input.
- During a turn, a change appends at the current position.
- Returning `null` adds nothing and resets change tracking, so a later return of the earlier text adds it again.
- Existing history is not removed.
- Change tracking survives deployments, clear, and compaction.

See [Dynamic capabilities](./guides/dynamic-capabilities) for examples and failure behavior.

A session that replaced a [stranded session](./concepts/execution-model-and-durability#what-a-replacement-session-receives) can receive the earlier conversation. In a user-role instruction, read the earlier session's stream with `sessions.attach()` and `transcriptOf()`, memoized by that session's ID.

## History controls and prompt caching

[Compaction](./concepts/sessions-runs-and-streaming#compact-clear-and-end) treats user-role instructions like any other history, so a summary can replace their text. Clear removes them with the rest of the conversation history and doesn't run static or dynamic instructions again. System-role instructions remain, because they are outside history.

Keep system-role content stable and ahead of frequently changing context when you can, so providers can reuse the prompt prefix. Cache behavior and billing depend on the provider, and eve doesn't promise a cache hit.

User-role instructions only append, so they keep the earlier prompt prefix the same. eve's notes about available skills and parked agents are user-role history too. A changed note appends after earlier steps. eve skips an unchanged note until history is cleared or compacted.

## Instructions vs skills

Instructions and [skills](./skills) both add text to the model's context, at different times:

|                          | Loaded                                                | Use for                                                  |
| ------------------------ | ----------------------------------------------------- | -------------------------------------------------------- |
| System-role instructions | Outside history on every model call                   | Permanent identity and standing rules                    |
| User-role instructions   | Once for static ones; on each change for dynamic ones | Application context that belongs in conversation history |
| `agent/skills/*`         | On demand, when the model loads one with `eve__skill` | Optional procedures that should not bloat every turn     |

Keep instructions short and stable. Put long or situational procedures in [skills](./skills). Put typed behavior that runs code in a [tool](./tools), because static instructions never run code at runtime.

## Disclaimer

As the deployer, it is your responsibility to ensure your agent complies with applicable laws.

Where an eve agent communicates with people, law may require you to disclose that they are interacting with an automated AI system. eve doesn't add this disclosure; configure it in your instructions or channel responses.

## What to read next

- [Tools](./tools): typed actions, the next capability to add
- [Context control](./concepts/context-control): all the levers for what the model sees
- [Skills](./skills): on-demand procedures, the counterpart to always-on instructions
- [Memory](./memory): provider-backed context that outlives a session, recalled before each turn

---

For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md)

For an index of all available documentation, see [/llms.txt](/llms.txt)

For agent-facing discovery, including API and MCP surfaces, see [/agents.md](/agents.md)