AGENT.md

AGENT.md defines an AGH agent: structured frontmatter plus a required Markdown prompt body. Current AGH agents live in AGH resource directories, not in the draft RFC .agents directory:

$AGH_HOME/agents/<agent-name>/AGENT.md
<workspace>/.agh/agents/<agent-name>/AGENT.md
<additional-root>/.agh/agents/<agent-name>/AGENT.md

The parser is strict. Unknown frontmatter fields fail loading.

Quick Reference

Field	Type	Default	Valid values	Description
`name`	string	required	Non-empty. Must match the requested agent name when loaded by name.	Agent identity and discovery key.
`provider`	string	`[defaults].provider`	Built-in provider key or custom provider key.	Provider used to resolve command, model, and API key metadata.
`command`	string	Provider `command`	Non-empty when overriding.	Agent-specific ACP launch command.
`model`	string	Provider `default_model`	Any string.	Agent-specific model metadata.
`tools`	string array	empty	Exact canonical ToolIDs or namespace-prefix wildcards.	Additional agent tool allowlist grammar.
`toolsets`	string array	empty	Canonical ToolsetIDs.	Additional named tool bundles allowed for the agent.
`deny_tools`	string array	empty	Exact canonical ToolIDs or namespace-prefix wildcards.	Tool denies that always narrow the agent grants.
`permissions`	string	`[permissions].mode`, default `approve-all`	`deny-all`, `approve-reads`, `approve-all`	Agent-specific permission mode.
`mcp_servers`	array of MCP server objects	empty	Each object requires `name` and `command`.	Agent-local MCP servers.
`hooks`	array of hook declarations	empty	Same declaration shape as config hooks.	Agent-scoped hook declarations.
Markdown body	Markdown text	required	Non-empty after trimming.	Startup prompt sent as the agent system prompt.

Even when tools and toolsets are empty, AGH adds the discovery toolsets agh__bootstrap and agh__catalog at runtime unless effective policy denies them. Agents should discover AGH-native runtime capabilities with agh__tool_search, inspect descriptors with agh__tool_info, and invoke dedicated tools before shelling out to equivalent agh ... commands. Operator-only management flows — daemon lifecycle, MCP OAuth login/logout, raw secret writes, and trust-root config — remain CLI/HTTP/UDS by design and are not promoted into the tool surface.

Discovery And Precedence

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

Order	Source	Path
1	Workspace root	`<workspace>/.agh/agents/<name>/AGENT.md`
2	Additional roots	`<additional-root>/.agh/agents/<name>/AGENT.md`, in registered order
3	Global home	`$AGH_HOME/agents/<name>/AGENT.md`

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

Parser Rules

Rule	Behavior
Frontmatter delimiter	The file must start with `---` and include a closing `---`.
Frontmatter language	YAML is parsed first. If YAML fails, AGH tries TOML frontmatter.
Unknown fields	Unknown YAML or TOML fields are errors.
Body	The Markdown body after frontmatter is trimmed. Empty body fails with `agent prompt is required`.
Name match	`LoadAgentDef(name)` requires the parsed `name` to match the requested directory/name.
Sidecar	`mcp.json` next to `AGENT.md` is optional and replaces same-name inline MCP servers as whole objects.

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 default_model.
model: claude-sonnet-4-6

# Optional. Add only extra ToolIDs beyond default discovery.
tools:
  - "mcp__github__*"

# Optional. Add only extra toolsets beyond agh__bootstrap + agh__catalog defaults.
toolsets:
  - "agh__coordination"

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

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

# 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`

Attribute	Value
Type	string
Default	none
Required	yes
Valid values	Non-empty string. No lowercase or slug pattern is currently enforced.
Description	Agent identity used for discovery, CLI/API selection, hook scoping, and duplicate resolution.

`provider`

Attribute	Value
Type	string
Default	`[defaults].provider`
Required	Required at resolution time unless `[defaults].provider` is set.
Valid values	Built-in provider key or custom `[providers.<name>]` key.
Description	Selects the provider command, default model, provider MCP servers, and API key environment metadata.

`command`

Attribute	Value
Type	string
Default	Selected provider `command`
Required	no
Valid values	Non-empty command when set.
Description	Overrides the provider launch command for this agent. The command is parsed with shell-style quoting and launched without a shell.

`model`

Attribute	Value
Type	string
Default	Selected provider `default_model`
Required	no
Valid values	Any string. Empty is allowed if the provider has no default.
Description	Agent-specific model metadata.

`tools`

Attribute	Value
Type	string array
Default	empty
Required	no
Valid values	Exact canonical ToolIDs such as `agh__skill_view`, or namespace-prefix wildcards such as `agh__skill_` and `mcp__github__`. `*`, dotted names, hyphens, uppercase, suffix wildcards, and mid-segment wildcards are rejected.
Description	Additional agent tool allowlist grammar consumed by the registry policy layer. It does not raise authority above `[permissions].mode`; default discovery still comes from the runtime overlay unless denied.

`toolsets`

Attribute	Value
Type	string array
Default	empty
Required	no
Valid values	Canonical ToolsetIDs such as `agh__catalog` or `linear__read`.
Description	Additional named tool bundles allowed for the agent. Toolsets are separate from `tools`; do not place toolset IDs in `tools`. AGH adds `agh__bootstrap` and `agh__catalog` at runtime by default unless denied.

`deny_tools`

Attribute	Value
Type	string array
Default	empty
Required	no
Valid values	Same grammar as `tools`: exact canonical ToolIDs or namespace-prefix wildcard patterns.
Description	Explicit narrowing layer. A deny can overlap an allow; later policy evaluation treats the deny as taking precedence.

`permissions`

Attribute	Value
Type	string
Default	`[permissions].mode`, which defaults to `approve-all`
Required	no
Valid values	`deny-all`, `approve-reads`, `approve-all`
Description	Overrides the global permission mode for this agent.

`mcp_servers`

Attribute	Value
Type	array of MCP server objects
Default	empty
Required	no
Valid values	Each object requires `name` and `command`; `args` and `env` are optional.
Description	Agent-local MCP servers merged after top-level config and provider MCP servers.

Server field	Type	Default	Valid values	Description
`name`	string	required	Non-empty.	Server merge key.
`command`	string	required	Non-empty.	MCP server command.
`args`	string array	empty	Strings.	Command arguments.
`env`	string map	empty	String keys and values.	Literal environment values. No shell expansion is performed.

`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; AGH then scopes the hook to this agent.

Field	Type	Default	Valid values	Description
`name`	string	required	Non-empty.	Hook name.
`event`	string	required	Current dot-form hook event.	Event that triggers the hook.
`mode`	string	`async`	`sync` or `async`; `sync` only for sync-eligible events.	Dispatch mode.
`required`	boolean	`false`	`true` or `false`; required hooks must be `sync`.	Whether hook failure blocks the source operation.
`priority`	integer	Agent-definition source default.	Integer.	Ordering priority.
`timeout`	duration	`0s`; subprocess executor uses 5 seconds when zero.	Non-negative Go duration.	Hook timeout.
`matcher`	object	scoped to this agent.	Hook matcher fields.	Narrows eligibility.
`command`	string	empty	Required for subprocess hooks unless nested executor fields are used.	Subprocess command.
`args`	string array	empty	Strings.	Command arguments.
`env`	string map	empty	String keys and values.	Explicit hook environment values.
`executor.kind`	string	`subprocess` when a command is present.	`subprocess` or `wasm` for user declarations.	Executor kind.

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-4-6
permissions: approve-reads
---

Review the requested change for correctness and missing tests.

Codex

---
name: codex-builder
provider: codex
model: gpt-5.4
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:

Sidecar	Purpose	Reference
`mcp.json`	Declare MCP servers in JSON form.	MCP Sidecar below.
`capabilities.toml` / `capabilities.json` or `capabilities/.toml` / `capabilities/.json`	Declare the unified capability catalog projected into brief discovery, rich discovery, and `kind:"capability"` transfer.	Agent Capabilities.

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.

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

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

Sidecar behavior:

Rule	Behavior
Accepted top-level keys	`mcpServers` and `mcp_servers`.
Server names	The map keys are server names.
Unknown fields	Fail parsing.
Same-name inline server	The sidecar replaces the whole inline server object.
Missing file	Treated as absent.

Runtime Resolution

Runtime value	Resolution order	Failure mode
Agent name	explicit CLI/API agent name, then `[defaults].agent`	Fails if empty.
Provider	`AGENT.md` `provider`, then `[defaults].provider`	Fails if still empty.
Command	`AGENT.md` `command`, then provider `command`	Fails if empty after provider resolution.
Model	`AGENT.md` `model`, then provider `default_model`	Empty is allowed.
Tools	`AGENT.md` `tools`	Must be exact canonical ToolIDs or approved namespace-prefix wildcards.
Toolsets	`AGENT.md` `toolsets`	Must be canonical ToolsetIDs.
Deny tools	`AGENT.md` `deny_tools`	Same grammar as `tools`; denies narrow later policy evaluation.
Permissions	`AGENT.md` `permissions`, then `[permissions].mode`	Must be a supported permission mode.
MCP servers	Top-level config, provider, agent, active skills	Same-name TOML entries merge fields; JSON sidecars replace whole objects.

The Tools and Toolsets rows describe configured agent policy. Effective runtime discovery also adds agh__bootstrap and agh__catalog by default. Denies still win after that overlay.

RFC 001 Fields Not Accepted Today

The current parser rejects these draft RFC fields as unknown.

Field	RFC purpose	Current behavior
`description`	Human description.	Rejected.
`skills.inherit`	Control inherited skills.	Rejected.
`skills.disabled`	Disable inherited skills for one agent.	Rejected.
`skills.extra_sources`	Add agent-specific skill roots.	Rejected.
`memory.inherit`	Control inherited memory.	Rejected.
`memory.scope`	Default write scope for memory.	Rejected.
`memory.auto_consolidate`	Agent-scoped memory consolidation.	Rejected.

RFC examples also use permission values such as plan and paths such as .agents/<name>/AGENT.md. Current AGH uses deny-all, approve-reads, approve-all and .agh/agents/<name>/AGENT.md.

Common Errors

Error	Cause	Fix
`config: missing YAML frontmatter`	The file does not start with a frontmatter block.	Add an opening and closing `---` block.
`config: unterminated YAML frontmatter`	The opening delimiter has no closing delimiter.	Close the frontmatter before the prompt body.
`unknown field`	A draft or misspelled frontmatter field is present.	Remove it or move the setting to a supported config surface.
`agent prompt is required`	The body after frontmatter is empty.	Add the agent prompt.
`agent.permissions must be one of ...`	Unsupported permission value.	Use `deny-all`, `approve-reads`, or `approve-all`.
`provider "<name>" command is required`	A custom provider has no command.	Add `[providers.<name>].command` or set `command` in `AGENT.md`.

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

On this page