> Discover all available pages from the documentation index: https://mastra.ai/llms.txt

# Instructions

An agent's `instructions.md` holds its always-on system prompt: the model reads it on every turn. Use it to define the agent's identity, tone, role, and standing rules.

Instructions are always in context, so keep them for stable behavior that applies to every request. Move anything conditional, large, or action-oriented out of `instructions.md` and into [`tools/`](https://mastra.ai/reference/file-based-agents/tools) or [`skills/`](https://mastra.ai/reference/file-based-agents/skills), which the model uses only when relevant.

## Quickstart

Add an `instructions.md` at the agent root. Whatever you write becomes the prompt, so the shortest version is a single sentence.

```markdown
You are a helpful weather assistant. Answer questions about current conditions and forecasts.
```

## What goes in instructions

Effective instructions cover the parts of an agent's behavior that don't change between requests:

- Role and identity
- Tone and style
- Standing rules
- Output format

Move conditional, large, or action-oriented guidance into [`tools/`](https://mastra.ai/reference/file-based-agents/tools) or [`skills/`](https://mastra.ai/reference/file-based-agents/skills), which the model uses only when relevant.

## Dynamic instructions

When the prompt needs to change per request, for example based on the current user or runtime context, set a dynamic `instructions` function in [`config.ts`](https://mastra.ai/reference/file-based-agents/config) instead of using `instructions.md`. A function `instructions` wins over `instructions.md`, so the static file is ignored when both are present.

```typescript
import { agentConfig } from '@mastra/core/agent'

export default agentConfig({
  model: 'openai/gpt-5.5',
  instructions: ({ runtimeContext }) => {
    const tier = runtimeContext.get('tier') ?? 'standard'
    return `You are a support agent. Treat this as a ${tier}-tier customer.`
  },
})
```

## Build-time behavior

Mastra reads `instructions.md` and inlines its contents into the generated code when the bundler builds your project. The deployed agent doesn't read the file at runtime, so changes to `instructions.md` take effect only after the next build.

## Precedence with config

Instructions can come from `instructions.md` or from the `instructions` field in [`config.ts`](https://mastra.ai/reference/file-based-agents/config):

- A dynamic (function) `instructions` in `config.ts` wins over `instructions.md`.
- Otherwise `instructions.md` wins over a static `instructions` string.
- If neither is present, the build fails and names the agent directory.