Documentation

Prompts

Prompts shape how Agent Zero thinks, speaks, and uses tools. The safest way to customize them is through a user-owned Agent Profile, not by editing the root prompt files directly.

Use usr/agents For Custom Prompts

Put custom profile prompts under /a0/usr/agents/<profile-name>/prompts/. Root-level prompts under /a0/prompts and root profiles under /a0/agents are the base install and can change during updates.

/a0/usr/agents/my_writer_profile/
└── prompts/
    ├── agent.system.main.role.md
    └── agent.system.main.communication.md

The User Override Rule

As a rule of thumb: whatever is in /a0/usr, if it has the same ID as something in the root /a0 area, the user-owned version replaces or extends the root version.

This is why custom prompts, profiles, plugins, and projects belong under /a0/usr. Your edits survive updates more cleanly, and the root install can remain the base reference.

Create A Prompt Profile

  1. Create a folder under /a0/usr/agents/<profile-name>/.
  2. Add only the prompt files you want to override.
  3. Keep each file focused: role, communication style, solving rules, or tool-specific behavior.
  4. Select the profile from the Agent Profile menu or Agent Config settings.

You do not need to copy every default prompt. Agent Zero merges your custom pieces with the defaults.

Common Prompt Files

  • agent.system.main.role.md: what the profile is excellent at.
  • agent.system.main.communication.md: tone, level of detail, and collaboration style.
  • agent.system.main.solving.md: how the agent should approach work.
  • agent.system.tool.*.md: tool-specific guidance.

Start with one file. Small prompt overrides are easier to debug than a huge copied prompt tree.

Prompt Variables

Some prompts can include variables that Agent Zero fills at runtime. Examples include {{date_time}}, {{agent_name}}, and {{tools}}.

Use variables sparingly. A clear instruction usually beats a clever template.

Write Good Prompt Instructions

  • Say what the profile should be excellent at.
  • Give concrete behaviors, not personality fog.
  • Prefer short sections and examples.
  • Do not hardcode secrets or private data.
  • Keep root prompts as references and put edits under /a0/usr/agents.

For source-linked prompt loading internals, use DeepWiki for Agent Zero.