Instructions

agent/instructions.md is the always-on system prompt. It's the one piece of prose the model sees on every turn. It's required on the root agent; subagents may inline instructions in their agent.ts instead.

Authoring forms

Three forms cover every case.

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

// agent/instructions.ts
import { defineInstructions } from "@cursor/july";

export default defineInstructions({
  markdown: `You are the on-call assistant for ${process.env.TEAM_NAME}.`,
});

How instructions reach the model

On the local runtime, instructions land in the session workspace as AGENTS.md, and the harness loads them natively. On the cloud runtime, they're prepended to the first prompt, because the cloud VM doesn't share the local session workspace.

The local workspace is a real Cursor project directory, so the harness may also load ambient AGENTS.md and .cursor config from ancestor directories. Agent config → Local cwd covers controlling that.

Best Practices

Keep them a few lines: identity, when to use which tool, 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: length, format, fences. That contract is what your evals gate.
• Move procedures to skills. A multi-step workflow the model only sometimes needs belongs in agent/skills/, where it loads on demand and keeps the always-on prompt small.

Instructions are the third lever in the hillclimbing loop, after host preparation and evidence shape. If a fixture keeps failing, look there before rewriting prose.

What's next

Continue with these pages:

• Skills: procedures the model loads only when relevant
• Agent config: the file next to this one
• Hillclimbing: iterating on instructions with evidence