Modify the system prompt
The CLI ships with a default system prompt. You have two ways to influence it: append your own guidance on top, or replace it entirely. Append is the right default for most integrations.
Append vs replace
- Append: keep the CLI defaults and add your own coding standards, repo conventions, or persona. Recommended.
- Replace: take full control of the system prompt. Only do this if you have a strong reason; you lose the CLI's built-in tool guidance, safety rules, and formatting.
Both methods accept either inline text or a file path. The file path mirrors the CLI's `--sys-prompt` / `--append-system-prompt` flags.
Append to the default prompt
Use this for repo-specific rules, brand voice, or workflow guardrails.
The TypeScript and Python SDKs also accept a file path. Anything that looks like a path is read from disk; everything else is treated as inline text.
Replace the default prompt
Use this only when you need to fully define the agent's behaviour. You are responsible for tool guidance, safety rules, and output formatting.
Per-agent instructions
The high-level `Agent.create()` API takes an `instructions` field that becomes part of the appended prompt. Use this for short-lived agents that need a focused persona.
Best practices
- Default to appending. Replacing is rarely the right answer.
- Keep prompts in files under version control. Put them next to the code they govern.
- Be specific about success criteria (“tests pass”, “file compiles”) so the agent knows when it can stop.
- State what the agent should not do. “Do not edit migration files” is more useful than a long list of allowed paths.
- If you maintain multiple agents, share a base prompt and append per-agent overrides on top.