Instructions

Purpose and Scope

Instructions are eve's always-on system prompt: the permanent identity and standing rule set that should apply to every turn in a session. They are not a task-specific recipe that the agent chooses to load later. If a behavior must shape every model call, such as tone, persona, compliance language, or a global constraint, it belongs in instructions. eve prepends the resolved instruction text to every model call in the session, which makes this file one of the most important context-control surfaces in an agent project.

Sources: docs/instructions.mdx

This page explains how to author instructions, when to use Markdown versus TypeScript, how directory-based instruction fragments are ordered, and how instructions differ from skills and tools. The goal is to help agent authors decide what belongs in the permanent prompt and what should move into another capability. Keeping this boundary clear matters because instructions consume context every turn, while other capabilities can be loaded or executed only when needed.

Relevant Source Files

• docs/instructions.mdx - Defines the public instructions contract, including agent/instructions.md, agent/instructions.ts, defineInstructions, directory merging rules, dynamic instructions, and guidance about skills, tools, and disclosure responsibilities.

Authoring Model

The minimum instruction surface is a Markdown file at the agent root. In a conventional eve project, that file is agent/instructions.md, and the contents are the prompt. There is no wrapper syntax for the Markdown form: whatever text you write becomes the permanent prompt text. This makes the simplest authoring path easy to review in code review and easy for non-framework specialists to edit, because the file reads like the policy or identity text the model will receive.

You are a concise assistant. Use tools when they are available.

Sources: docs/instructions.mdx

Use this file for stable behavior rather than situational procedures. Good instruction content includes the assistant's role, the expected tone, global safety constraints, disclosure language, and durable preferences that should remain true across all sessions. Poor instruction content includes long workflows, optional playbooks, and rare troubleshooting procedures, because those inflate every prompt even when the user is asking an unrelated question. eve's documentation explicitly recommends keeping instructions short and stable, then using skills for procedures that only matter for some requests.

Markdown, TypeScript, and Build-Time Resolution

Markdown is the default choice when the prompt is static. Switch to agent/instructions.ts when the prompt needs typed helpers, local lib/ code, or build-time values. The TypeScript entry point exports defineInstructions from eve/instructions and passes a single markdown field containing the resolved prompt text. This is still an instruction prompt, not a runtime tool: the TypeScript module is a way to produce Markdown during compilation rather than a way to run code during a conversation.

import { defineInstructions } from "eve/instructions";
import { buildInstructionsPrompt } from "./lib/prompts.js";
 
export default defineInstructions({
  markdown: buildInstructionsPrompt(),
});

Sources: docs/instructions.mdx

A module-backed prompt runs once at build time. eve captures the resulting Markdown in the compiled manifest, and the runtime serves the same prompt for every session without re-running the module. That behavior is important for predictability: build-time helpers can centralize prompt text or assemble sections, but they should not be used for per-user, per-tenant, or per-channel decisions unless they are wrapped in the dynamic capability mechanism described later. Treat instructions.ts as a prompt compiler, not as a runtime decision engine.

The root instruction file has a mutual-exclusion rule. You may author agent/instructions.md or agent/instructions.ts, but not both at the root. Having both is a build error. This prevents ambiguity about which root prompt should come first and keeps the project layout inspectable. If a project grows beyond one file, use the instruction directory composition model instead of trying to combine both root file formats.

Splitting Instructions Across Files

For larger standing prompts, add an agent/instructions/ directory. eve reads entries in that directory non-recursively, accepts .md files and .ts modules, and combines them in alphabetical order using localeCompare. This gives teams a deterministic way to split a permanent prompt into named sections such as identity, response style, domain vocabulary, and compliance disclosures. The non-recursive rule keeps the merge model simple: only direct entries in the directory participate.

Sources: docs/instructions.mdx

The root file and the directory can coexist. When they do, the root instruction content is placed first, followed by sorted directory entries. That ordering lets a project keep the highest-level identity in agent/instructions.md while adding more specialized always-on fragments under agent/instructions/. Because directory entries sort by filename, use names that make the intended order obvious, such as 00-identity.md, 10-tone.md, or 20-disclosure.md. The docs do not require numeric prefixes, but explicit naming helps reviewers understand prompt precedence.

A TypeScript file inside agent/instructions/ can wrap either defineInstructions or defineDynamic. The static case behaves like the root TypeScript module: it resolves Markdown for the compiled manifest. The dynamic case is for runtime prompt resolution, such as deriving instructions from auth, tenant, or channel context. Keep the distinction visible in filenames and code review, because dynamic instructions can make the prompt depend on the session environment while static instructions should remain reproducible from the build.

Instructions, Skills, and Tools

Instructions and skills both feed text into the model context, but they differ in timing. Instructions are always loaded on every turn, while skills under agent/skills/* are loaded on demand when the model calls load_skill. The practical design rule is simple: permanent identity and standing rules belong in instructions; optional procedures belong in skills. This keeps the default prompt smaller and lets specialized procedures enter context only when the user request calls for them.

Sources: docs/instructions.mdx

Instructions also differ from tools. Instructions never run code. They can tell the model when and how to use available capabilities, but they cannot perform typed executable behavior themselves. When an agent needs to call an API, read data, perform a calculation, or take an action with a structured input and output contract, define a tool instead. A useful instruction might say, "Use tools when they are available," but the implementation of the action belongs in agent/tools/, not in the prompt.

Dynamic Instructions and Runtime Context

When the prompt must depend on runtime session context, use dynamic instructions by wrapping defineInstructions in a defineDynamic resolver. The docs call out auth, tenant, and channel as examples of context that can affect the resolved prompt. This is the right fit for multi-tenant agents that need tenant-specific vocabulary, authenticated user constraints, or channel-specific disclosure text. It is also the boundary that keeps static build-time prompt generation separate from runtime session-aware prompt resolution.

Sources: docs/instructions.mdx

Because dynamic instructions affect what the model sees, treat them as part of the agent's authorization and context-control design. A dynamic resolver can help avoid hard-coding every tenant's rules into a single permanent file, but it also means the effective system prompt is no longer visible from one static Markdown file alone. Document the resolver inputs, keep the generated text concise, and test representative contexts so the agent receives the expected prompt in each route, tenant, or channel scenario.

Responsible Disclosure and Safety Notes

The documentation includes an explicit deployer responsibility note: the deployer must ensure the agent complies with applicable laws. If an eve agent communicates with people, law may require disclosing that they are interacting with an automated AI system. eve does not add that disclosure automatically. If your deployment needs it, put the disclosure in instructions, channel responses, or both. Instructions are often the right baseline because they apply on every turn, but channel responses may be needed when the disclosure must appear in a particular surface.

Sources: docs/instructions.mdx

A practical review pass for instructions should ask four questions. First, is every sentence meant to apply on every turn? Second, would any long procedure be better as a skill? Third, does any desired behavior require executable code and therefore a tool? Fourth, does any user-, tenant-, or channel-specific text require dynamic resolution rather than build-time Markdown? Answering these questions keeps the prompt stable, avoids unnecessary context bloat, and makes later changes easier to reason about.

Next Steps

Start with agent/instructions.md for the smallest useful prompt, then migrate to agent/instructions.ts only when build-time composition is valuable. If the prompt grows, split it into a root file plus deterministic entries under agent/instructions/. Move situational procedures into skills, implement actions as tools, and use dynamic instructions only when runtime context must change the prompt. For adjacent concepts, read the skills, tools, dynamic capabilities, and context-control pages next.