Agent Definitions

An agent definition tells AGH which agent to start and what startup prompt to give it. The definition is a directory with an AGENT.md file and optional sidecars:

~/.agh/agents/code-reviewer/
  AGENT.md
  mcp.json
  capabilities.toml

mcp.json declares MCP servers in JSON form, and capabilities.toml (or a capabilities/ directory) declares the unified capability catalog the runtime projects into brief discovery, rich discovery, and explicit kind:"capability" transfer. See Agent Capabilities for the catalog format.

AGENT.md is a Markdown file with required frontmatter and a required body. AGH parses the frontmatter into runtime configuration, then uses the Markdown body as the startup system prompt.

Minimal valid file

---
name: code-reviewer
provider: claude
model: claude-sonnet-4-6
permissions: approve-reads
---
You are a senior code reviewer.

Review code for correctness, security, and maintainability. Be direct, cite the relevant file or
symbol, and separate blocking defects from suggestions.

The body after the second --- is trimmed and stored as the agent prompt. An empty body is a validation error.

Discovery paths

AGH resolves agents from the workspace snapshot attached to the session.

Discovery order is first-wins:

1. Workspace root
2. Additional roots, in the registered order
3. Global AGH home

If two definitions use the same name, AGH keeps the first one it found. It does not merge or inherit from the lower-precedence definition.

Resolution cascade

Session creation first resolves the agent name, then resolves the provider and runtime fields.

The bootstrap general agent created by agh install intentionally contains only name: general and a prompt. Its provider and model come from ~/.agh/config.toml.

Tool discovery works the same way. The tools and toolsets frontmatter fields start empty, but the effective runtime policy adds agh__bootstrap and agh__catalog by default unless a deny or runtime policy layer removes them. Agents should use agh__tool_search -> agh__tool_info -> invoke for AGH-native capabilities and agh__skill_search -> agh__skill_view for skill loading before falling back to equivalent agh ... shell commands. Operator-only management — daemon lifecycle, MCP OAuth login/logout, trust-root config, raw secret writes, and cross-session terminal-state mutation — stays on the CLI/HTTP/UDS surfaces and is intentionally absent from the tool family.

Frontmatter reference

These are the frontmatter fields accepted by the current internal/config parser.

The parser accepts YAML frontmatter first. If YAML parsing fails, it tries TOML frontmatter. In both formats, unknown fields fail validation.

MCP servers

Inline MCP servers are useful when a tool belongs to one agent:

---
name: pr-reviewer
provider: claude
mcp_servers:
  - name: github
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_TOKEN: "replace-with-token"
---
You review pull requests and use GitHub context when it is available.

You can also place an mcp.json sidecar next to AGENT.md:

{
  "mcp_servers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "replace-with-token"
      }
    }
  }
}

Sidecar behavior is precise:

• mcp.json may use either mcp_servers or mcpServers.
• Server names are map keys in mcp.json.
• env values are sent as literal strings; AGH does not expand shell placeholders inside MCP server definitions.
• When an inline server and sidecar server have the same name, the sidecar replaces the whole server object.
• Across runtime scopes, MCP servers merge in this order: top-level config, provider, agent, then active skills.

Complete examples

Claude Code reviewer

---
name: code-reviewer
provider: claude
model: claude-sonnet-4-6
tools: ["mcp__github__*"]
toolsets: ["agh__coordination"]
deny_tools: ["agh__network_send"]
permissions: approve-reads
mcp_servers:
  - name: github
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_TOKEN: "replace-with-token"
---

You are a senior code reviewer.

Focus on defects that can change runtime behavior: incorrect error handling, security boundaries,
data loss, races, and missing tests. Put blocking findings first. Use short, direct comments with
file and symbol references.

Codex implementation agent

---
name: implementation
provider: codex
model: gpt-5.4
permissions: approve-all
---
You implement scoped software changes end to end.

Read the task, inspect the repository before editing, keep changes limited to the requested
surface, run the relevant verification commands, and summarize the exact files changed.

Draft RFC fields not accepted today

RFC 001 proposes a larger portable agent format. The current parser is strict, so these fields must not be used in a live AGENT.md yet.

Agent-scoped skills and memory are still part of the design direction, but today skills and memory are resolved by the runtime systems, not by agent frontmatter.

Common validation failures

Related pages

• Agent Capabilities covers the optional capability catalog sidecar that sits next to AGENT.md and feeds network discovery.
• Providers lists every built-in provider and the provider config shape.
• Spawning follows the ACP subprocess startup path.
• Session Lifecycle explains the durable session that wraps each spawned agent.