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

// 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.

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 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 is the pattern:

# 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 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: procedures the model loads only when relevant
• Agent config: the file next to this one
• Hillclimbing: iterating on instructions with evidence