Skip to main content
Each agent is defined by a markdown file at ~/.operator/agents/<name>/AGENT.md. The file content becomes the agent’s prompt — its personality, instructions, and capabilities.

​
Creating an Agent

Create a directory and prompt file: 
mkdir -p ~/.operator/agents/myagent
Write ~/.operator/agents/myagent/AGENT.md: 
You are a helpful assistant focused on code review.
Always explain your reasoning before suggesting changes.
Be concise but thorough.
Then register it in operator.yaml: 
agents:
  myagent:
    models:
      - "anthropic/claude-sonnet-4-6"
    transport:
      type: slack
      bot_token_env: SLACK_BOT_TOKEN
      app_token_env: SLACK_APP_TOKEN

​
Workspace

Each agent has a workspace at ~/.operator/agents/<name>/workspace/. This is the working directory for all tool calls — shell commands, file reads/writes, and list_files all resolve relative paths against it. Files persist across conversations and job runs.

​
System Prompt Assembly

The full system prompt is assembled from multiple sources, split into a stable prefix and dynamic suffix separated by a cache boundary: Stable prefix (cached across turns):
  1. SYSTEM.md — system preamble (auto-created at ~/.operator/SYSTEM.md)
  2. AGENT.md — agent prompt body (verbatim)
  3. Available skills — discovered from skills/*/SKILL.md
Dynamic suffix (changes per conversation/turn): 4. Context block — platform, channel, user, workspace info (or job block for jobs) 5. Pinned memories — always injected regardless of similarity (chat only) 6. Transport extras — e.g. Slack channel list, messaging instructions The stable prefix is reused across turns via Anthropic prompt-cache breakpoints, reducing token costs for multi-turn conversations.

​
Model Fallback

Agents inherit models from defaults unless overridden. The model list is a fallback chain — if the first model errors (overloaded, rate limited, down), the next is tried automatically.

​
Headless Agents

Agents without a transport block have no chat interface but are available for:
  • Running jobs
  • Being spawned as sub-agents via the spawn_agent tool