AGENT.md

AGENT.md defines a CompozyOS agent: structured frontmatter plus a required Markdown prompt body. Current CompozyOS agents live in CompozyOS resource directories:

$COMPOZY_HOME/agents/<agent-name>/AGENT.md
<workspace>/.compozy/agents/<agent-name>/AGENT.md
<additional-root>/.compozy/agents/<agent-name>/AGENT.md

The parser is strict. Unknown frontmatter fields fail loading.

Quick Reference

When tools and toolsets are empty, the agent definition does not add an allowlist. For a bare managed session, hosted MCP projects the full availability-gated callable catalog. Populate tools or toolsets only when the agent should be limited to that explicit surface. Discovery-only policies can still name compozy__bootstrap or compozy__catalog; CompozyOS just no longer injects those toolsets as a default cap for every bare hosted session. Agents should discover CompozyOS-native runtime capabilities by resolving canonical compozy__tool_search, inspect descriptors through canonical compozy__tool_info, and invoke the harness-returned dedicated tool reference before shelling out to equivalent compozy ... commands. Operator-only management examples include MCP OAuth login/logout, daemon lifecycle, raw secret writes, and trust-root config. These flows remain CLI/HTTP/UDS by design and are not promoted into the tool surface.

If tools, toolsets, or a delegated session policy requires a concrete tool surface, hosted MCP is part of the startup contract. CompozyOS fails session creation before provider startup when it cannot project that surface; it does not send the agent a prompt that requires unavailable tools.

CompozyOS also adds a daemon-owned runtime envelope around the agent body at session startup. The envelope states that the session is running inside CompozyOS, carries session/workspace facts, and is not something agent authors need to repeat in every AGENT.md.

Discovery And Precedence

CompozyOS loads visible agents from the workspace snapshot attached to a session.

Discovery is first-wins. If two files define the same name, CompozyOS keeps the first one found and does not merge lower-precedence definitions.

Reserved Builtin Names

coordinator and dreaming-curator are virtual, CompozyOS-owned role identities. They have embedded prompts, resolve without authored directories, and never appear in public agent catalogs. Creating, updating, renaming, duplicating, or publishing either name from an extension fails with agent_name_reserved; CompozyOS does not create or modify an authored directory.

general is different: it is the normal managed public agent created by installation and remains editable. Other authored agents may be selected through [roles.<role>].agent; doing so changes the route to that agent and does not modify a builtin prompt.

Parser Rules

Complete Annotated Example

---
# Required. This must match the directory name when loaded by name.
name: reviewer

# Optional if [defaults].provider is set in config.toml.
provider: claude

# Optional. Defaults to the provider models.default.
model: claude-sonnet-5

# Optional. Empty uses the provider/adapter default; explicit none is a real value.
reasoning_effort: max

# Optional. Set only when this agent should be limited to these ToolIDs.
tools:
  - "mcp__github__*"

# Optional. Set only when this agent should be limited to these toolsets.
toolsets:
  - "compozy__coordination"

# Optional. Denies always narrow the allowed set.
deny_tools:
  - "compozy__network_send"

# Optional. Defaults to [permissions].mode.
permissions: approve-reads

# Optional. Display-only UI/CLI/API organization path.
category_path:
  - Engineering
  - Review

# Optional. Merged after top-level and provider MCP servers.
mcp_servers:
  - name: github
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
    secret_env:
      GITHUB_TOKEN: "env:GITHUB_TOKEN"

# Optional. Agent-scoped hooks automatically match this agent name.
hooks:
  - name: reviewer-started
    event: session.post_create
    mode: async
    command: printf
    args: ["reviewer ready\n"]
---

You are a senior code reviewer.

Review code for correctness, security boundaries, data loss, races, and missing tests.
Put blocking findings first and cite the relevant file or symbol.

Field Details

name

provider

command

model

The exact model ID is applied through the active ACP model option after session creation/load. An unadvertised ID fails with model_unavailable; CompozyOS never aliases it or falls back to the provider default.

reasoning_effort

At session start, CompozyOS applies model first, refreshes the advertised ACP options, then applies the effort before the first prompt. Explicit none is sent when advertised; empty sends no effort RPC. Missing or unsupported live options fail loudly with reasoning_option_missing or reasoning_effort_unsupported.

tools

toolsets

deny_tools

permissions

skills

The current runtime supports:

skills:
  disabled:
    - review
    - deploy-production

skills.disabled does not add new roots and does not create an agent-only skill mode. CompozyOS resolves the normal bundled -> marketplace -> user -> additional -> workspace set, overlays the winning agent's skills/ directory, then disables any logical skill names listed here for that agent. This is separate from the global skills settings field disabled_skills; use AGENT.md skills.disabled for one agent's tombstones and settings for daemon-managed global defaults.

category_path

Use category_path when a large agent set needs a stable visual grouping:

category_path:
  - Marketing
  - Sales

This field does not affect provider selection, permissions, tools, scheduling, skill resolution, hooks, memory, or ACP startup. It is not a multi-tag list; it is one ordered path. Root-level agents omit the field or use an empty array. CompozyOS rejects categories: [...] and category_path: "Marketing/Sales" because the runtime has one canonical array shape and no compatibility aliases.

mcp_servers

hooks

Agent hook declarations use the same fields as [[hooks.declarations]] in config.toml. When a hook matcher includes agent_name, it must match this agent's name; CompozyOS then scopes the hook to this agent.

Provider Examples

These snippets show the minimal agent shape for the core built-in providers. API-key providers such as OpenRouter, z.ai, Moonshot/Kimi, and Vercel AI Gateway use the same provider and model frontmatter once their credential slots are configured in config.toml or settings.

Claude

---
name: claude-reviewer
provider: claude
model: claude-sonnet-5
reasoning_effort: max
permissions: approve-reads
---

Review the requested change for correctness and missing tests.

Codex

---
name: codex-builder
provider: codex
model: gpt-5.6-sol
permissions: approve-all
---

Implement scoped code changes, run verification, and summarize the diff.

Gemini

---
name: gemini-researcher
provider: gemini
model: gemini-3.1-pro-preview
permissions: approve-reads
---

Analyze the repository context and return concise implementation guidance.

OpenCode

---
name: opencode-worker
provider: opencode
permissions: approve-all
---

Work through implementation tasks with a small, reviewable diff.

Copilot

---
name: copilot-helper
provider: copilot
permissions: approve-reads
---

Inspect the codebase and answer questions with file-backed references.

Cursor

---
name: cursor-agent
provider: cursor
permissions: approve-all
---

Make focused edits and keep changes aligned with project conventions.

Kiro

---
name: kiro-planner
provider: kiro
permissions: approve-reads
---

Turn product requirements into concrete implementation notes.

Pi

---
name: pi-assistant
provider: pi
permissions: approve-reads
---

Provide concise assistance grounded in the active workspace.

Recognized Sidecars

An agent directory accepts two kinds of sidecars next to AGENT.md:

Sidecars are loaded independently. Exactly one capability layout (single-file or directory) is allowed per agent; mixing layouts is a hard error.

MCP Sidecar

Place mcp.json next to AGENT.md when MCP definitions are generated or easier to maintain as JSON.

~/.compozy/agents/reviewer/
  AGENT.md
  mcp.json

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "secret_env": {
        "GITHUB_TOKEN": "env:GITHUB_TOKEN"
      }
    }
  }
}

Sidecar behavior:

Runtime Resolution

The Tools and Toolsets rows describe configured agent policy. Empty means no agent-local allowlist; hosted MCP projects the full availability-gated callable catalog unless another policy layer narrows it. Denies still win.

RFC 001 Drift

The current runtime diverges from the broader RFC 001 draft in these ways:

RFC examples also use permission values such as plan. Current CompozyOS uses deny-all, approve-reads, and approve-all.

Common Errors

Related Pages

• config.toml documents provider and permission defaults.
• mcp.json documents sidecar schema and replacement rules.
• Agent Providers explains built-in provider behavior.