# Instructions

Agent instructions form the always-on system prompt and reach the model
on every turn. A root agent requires them; a subagent may inline
`instructions` in `agent.ts` instead.

## Authoring forms

| Form | Use it when |
| --- | --- |
| `bot/instructions.md` | Plain Markdown for most agents |
| `bot/instructions.ts` | Generated prompts. Default-export `defineInstructions({ markdown })` or a plain string |
| `bot/instructions/` directory | A long prompt split across files, composed in filename order |

```ts
// bot/instructions.ts
import { defineInstructions } from "@grok/agent-sdk";

export default defineInstructions({
  markdown: "You are the on-call assistant for the payments team.",
});
```

The `markdown` string is fixed when this file loads. Read a secret in
a handler, a tool, or a callback. See
[Add egress and secrets](/docs/deployment.md#add-egress-and-secrets).

## Delivery

Instructions land in the session workspace as `AGENTS.md`, and the
harness loads them natively. Parent directories can still contribute
ambient `AGENTS.md` and `.cursor` settings;
[Agent config: local cwd](/docs/reference/agent-config.md#local-cwd) covers how to
control that.

## Contents

Keep them a few lines: identity, when to use which tool, and the output
shape. The [quickstart PR approver](/docs/quickstart.md) is the pattern:

```md
# PR approver

You review GitHub pull requests. Be specific and brief.

1. Call `inspect_pr` first. Never judge a change you haven't fetched.
2. Match your review to the complexity it reports.
3. Never approve a draft.

End with one sentence: the verdict and why.
```

Name the tools and the decision rule ("use X before answering about
Y"), not general encouragement. State the output contract, including
length, format, and fences, so your [evals](/docs/evals.md) can gate it.
Put multi-step workflows the model only sometimes needs in
`bot/skills/`; they load on demand and keep the always-on prompt small.

## Related

- [Skills](/docs/reference/skills.md): procedures the model loads only when relevant
- [Agent config](/docs/reference/agent-config.md): the file next to this one
- [Hillclimbing](/docs/hillclimbing.md): iterating on instructions with
  evidence