# Instructions

Instructions are the always-on prompt for every turn. A root agent
requires them, and a subagent may inline `instructions` in `agent.ts`
instead.

## Authoring forms

| Form | Use it when |
| --- | --- |
| `bot/instructions.md` | Most agents |
| `bot/instructions.ts` | Generated prompts. Default-export `defineInstructions({ markdown })` or a string |
| `bot/instructions/` | A long prompt split across files, joined 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 the file loads. See
[Add egress and secrets](/docs/deployment.md#add-egress-and-secrets) for
reading secrets inside a handler.

## Delivery

A local turn sends the instructions, with a short identity section, as the system prompt, and a turn in the cloud includes the same text in the first user message. Nothing is written to the workspace as `AGENTS.md`, but a parent directory's `AGENTS.md` can still reach a local session. See
[Local cwd](/docs/reference/agent-config.md#local-cwd).

## Contents

Keep instructions to a few lines that cover identity, when to use each
tool, and the output shape. A short version of the
[quickstart](/docs/quickstart.md) reviewer:

```md
# PR reviewer

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, such as "use X before answering
about Y". State the output contract, including length and format, so
your [evals](/docs/evals.md) can gate it. Move occasional multi-step
workflows into [skills](/docs/reference/skills.md), which load on demand.
