kind: agent

Defines a named subagent/specialist delegated to by the main AI session. Source: xcaf/agents/<name>/agent.xcaf. Compiled to agents/<name>.md per provider.

Defines a named subagent that the main AI session delegates to. Each agent carries its own system prompt, tool access, and optional skill, rule, and MCP bindings. xcaffold compiles it to agents/<id>.md with YAML frontmatter for each supported target provider.

In every provider, the compiled output lands in that provider's agents directory — .claude/agents/, .cursor/agents/, .github/agents/, .gemini/agents/, .agents/agents/, .codex/agents/ — where the main session picks it up and dispatches to it by name.

Required: kind, version, name

Source Directory

xcaf/agents/<name>/agent.xcaf

Example Usage

Minimal agent

.xcaf

---
kind: agent
version: "1.0"
name: reviewer
description: Reviews pull requests for correctness and style.
tools: [Read, Glob, Grep]
readonly: true
---

Review the provided diff for correctness, style, and test coverage.
Flag issues with a severity: `CRITICAL`, `WARN`, or `INFO`.
Report: "Reviewed <N> files, found <M> issues."

Full agent — React developer

.xcaf

---
kind: agent
version: "1.0"
name: react-developer
description: >-
  Implements React components, hooks, and UI features for frontend-app.
  Authorized to modify src/components/, src/hooks/, src/pages/, and
  src/styles/. Consults the component-patterns skill before authoring
  any new component.
model: sonnet
tools:
  - Read
  - Edit
  - Write
  - Bash
  - Glob
  - Grep
memory:
  - user-prefs
  - project-context
skills:
  - component-patterns
rules:
  - react-conventions
mcp:
  - browser-tools
---

## Role
Implements and maintains React UI components for `frontend-app`.
You are the ONLY agent authorized to modify `src/components/`.

## Stack
- React 18, TypeScript 5.x, Next.js 15 (App Router)
- Tailwind CSS v4, Shadcn/UI
- Vitest + React Testing Library, Storybook

## Component Rules
- **Co-locate tests**: every component gets a `<Component>.test.tsx` beside it.
- **No inline styles**: Tailwind utility classes only.
- **Export from barrel**: add new components to `src/components/index.ts`.
- **Accessibility first**: all interactive elements need `aria-label`.

## Mandatory Deliverables
1. Run `pnpm test --filter frontend-app` — all tests must pass.
2. Run `pnpm lint` — zero ESLint errors.
3. Report: "Added <N> components, <M> tests passing."

## DO NOT
- Modify files outside `src/components/`, `src/hooks/`, `src/pages/`, `src/styles/`.
- Use class-based components.
- Leave `any` types in props.

Field Reference

Required Fields

Field	Type	Description
`kind`	`string`	Resource type. Must be `agent`.
`version`	`string`	File format version. Must be `"1.0"`.
`name`	`string`	Unique agent identifier. Must match `[a-z0-9-]+`.

Optional Fields

Field	Type	Description
`description`	`string`	Human-readable purpose of this agent. Used for delegation and auto-invocation.
`model`	`string`	LLM model identifier or alias resolved at compile time. Bare tier aliases (`sonnet`, `opus`, `haiku`) are passed through for runtime resolution.
`effort`	`string`	Reasoning effort level hint for the model provider.
`max-turns`	`int`	Maximum conversation turns before the agent exits.
`tools`	`[]string`	Ordered list of tools this agent may invoke. Omit to inherit all available tools.
`disallowed-tools`	`[]string`	Tools explicitly denied to this agent.
`readonly`	`bool`	When `true`, restricts the agent to read-only tool access.
`permission-mode`	`string`	Security mode controlling tool authorization behavior.
`disable-model-invocation`	`bool`	Prevents the agent from spawning sub-agents.
`user-invocable`	`bool`	Whether users can invoke this agent directly via slash command.
`background`	`bool`	Runs the agent in background mode without interactive prompts.
`isolation`	`string`	Process isolation level for the agent session.
`memory`	`string` or `[]string`	Named memory banks attached to this agent. A single string value is accepted for backward compatibility.
`color`	`string`	Display color for terminal output differentiation.
`initial-prompt`	`string`	System prompt prepended to every conversation.
`skills`	`[]string`	Skill resource IDs attached to this agent. Must match top-level `skills:` map keys.
`rules`	`[]string`	Rule resource IDs governing this agent. Must match top-level `rules:` map keys.
`mcp`	`[]string`	MCP server resource IDs available to this agent. Must match top-level `mcp:` map keys.
`mcp-servers`	`map[string]MCPConfig`	Inline MCP server definitions keyed by server name. Same field schema as `kind: mcp`.
`hooks`	`HookConfig`	Agent-scoped lifecycle hooks. Same structure as `kind: hooks`.
`targets`	`map[string]TargetOverride`	Per-provider overrides keyed by provider name (`antigravity`, `claude`, `copilot`, `cursor`, `gemini`).

`hooks` block

Agent-scoped lifecycle hooks. Same structure as kind: hooks.

PreToolUse — Runs before any tool invocation.
PostToolUse — Runs after any tool invocation.
SessionStart, Stop, Notification, SubagentStop, InstructionsLoaded, PreCompact, ConfigChange — Session lifecycle events.

`mcp-servers` block

Agent-scoped MCP server definitions. Not merged with project-level mcp:. Same field schema as kind: mcp.

`targets` block

Per-provider overrides keyed by provider name. When present, the resource compiles only for listed providers. See Targets for the full concept, including filtering semantics and the dual-purpose map syntax.

Each key under agents.<id>.targets.<target> maps to a TargetOverride struct. Valid target keys are: antigravity, claude, copilot, cursor, gemini, codex.

Field	Type	Status
`suppress-fidelity-warnings`	`*bool`	Parsed, not compiled
`hooks`	`map[string]string`	Parsed, not compiled
`skip-synthesis`	`*bool`	Parsed, not compiled

Provider Fidelity

Not all fields survive compilation to every provider. The table below shows which xcaffold fields are emitted for each target. Fields marked — are dropped silently unless noted.

Field	Claude	Cursor	Copilot	Gemini	Antigravity	Codex (Preview)
`name`	yes	yes	yes	yes	yes (frontmatter)	yes (TOML key)
`description`	yes	yes	yes	yes	yes	yes
`model`	yes (resolved)	mapped only ¹	yes (resolved)	yes (resolved)	yes (resolved)	yes (resolved)
`effort`	yes	—	—	—	—	—
`max-turns`	yes	—	—	`max_turns` ²	yes (`maxTurns`)	—
`tools`	yes (inline)	—	yes (YAML list)	yes (YAML list)	yes (YAML list)	yes (TOML array)
`disallowed-tools`	yes	—	—	—	yes (`disabledTools`)	—
`readonly`	transforms ³	yes	—	—	yes	—
`permission-mode`	yes	—	—	—	—	—
`disable-model-invocation`	—	—	yes	—	—	—
`user-invocable`	—	—	yes	—	yes (`userInvocable`)	—
`background`	yes	`is_background` ²	—	—	—	—
`isolation`	yes	—	—	—	—	—
`memory`	yes	—	—	—	—	—
`color`	yes	—	—	—	—	—
`initial-prompt`	yes	—	—	—	yes	yes (`system_prompt`)
`skills`	yes (inline)	—	—	—	yes	—
`rules`	—	—	—	—	yes	—
`hooks`	yes (YAML)	—	—	—	—	—
`mcp-servers`	yes (YAML)	—	yes (YAML)	`mcpServers` ²	yes (`mcpServers`)	—

Footnotes

Cursor emits model only when IsMappedModel returns true. Unmapped values are dropped with an AGENT_MODEL_UNMAPPED warning to stderr.
Key name differs from the xcaffold canonical: max_turns (snake_case), is_background, mcpServers (camelCase).
Claude: when readonly: true and no tools are specified, emits tools: [Read, Grep, Glob] rather than a readonly key.

Filesystem-as-Schema

When an agent .xcaf file lives at xcaf/agents/<name>/agent.xcaf, the kind: and name: fields can be omitted from the YAML. The parser infers:

kind: agent from the parent directory name (agents/)
name: from the grandparent directory name (e.g., researcher from agents/researcher/agent.xcaf)

When kind: or name: are present in the YAML, they must match the inferred values.

Compiled Output

Claude

Output path: .claude/agents/react-developer.md

.xcaf

---
name: react-developer
description: >-
  Implements React components, hooks, and UI features for frontend-app.
  Authorized to modify src/components/, src/hooks/, src/pages/, and
  src/styles/. Consults the component-patterns skill before authoring
  any new component.
model: claude-sonnet-4-5
tools: [Read, Edit, Write, Bash, Glob, Grep]
memory: project
skills: [component-patterns]
---

## Role
Implements and maintains React UI components for `frontend-app`.
…

All supported fields are emitted. The model alias (sonnet) is resolved to the full model ID. skills is inlined. disable-model-invocation and user-invocable are not Claude fields and are not emitted.

Cursor

Output path: .cursor/agents/react-developer.md

.xcaf

---
name: react-developer
description: >-
  Implements React components, hooks, and UI features for frontend-app.
  Authorized to modify src/components/, src/hooks/, src/pages/, and
  src/styles/. Consults the component-patterns skill before authoring
  any new component.
readonly: true
---

## Role
…

Cursor emits name, description, model (mapped models only — unmapped values dropped with AGENT_MODEL_UNMAPPED warning), readonly, and background (renamed to is_background). All other fields — tools, memory, skills, rules, mcp, effort, permission-mode, color, initial-prompt, hooks, mcp-servers — are dropped.

Copilot

Output path: .github/agents/react-developer.agent.md

.xcaf

---
name: react-developer
description: >-
  Implements React components, hooks, and UI features for frontend-app.
  Authorized to modify src/components/, src/hooks/, src/pages/, and
  src/styles/. Consults the component-patterns skill before authoring
  any new component.
model: claude-sonnet-4-6
tools:
  - Read
  - Edit
  - Write
  - Bash
  - Glob
  - Grep
---

## Role
…

Copilot emits name, description, model (resolved), tools (YAML list), disable-model-invocation, user-invocable, and mcp-servers. Fields memory, skills, rules, mcp, effort, permission-mode, readonly, background, isolation, color, initial-prompt, and hooks are dropped.

Native passthrough: when .claude/agents/ is present in the project, Copilot skips compilation for agents and reads the Claude output directly (CLAUDE_NATIVE_PASSTHROUGH).

Gemini

Output path: .gemini/agents/react-developer.md

.xcaf

---
name: react-developer
description: >-
  Implements React components, hooks, and UI features for frontend-app.
  Authorized to modify src/components/, src/hooks/, src/pages/, and
  src/styles/. Consults the component-patterns skill before authoring
  any new component.
model: gemini-2.5-flash
tools:
  - Read
  - Edit
  - Write
  - Bash
  - Glob
  - Grep
max_turns: 10
mcpServers:
  browser-tools:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-browser-tools"]
---

## Role
…

Gemini emits name, description, model (resolved), tools (YAML list), max_turns (snake_case, from max-turns), and mcpServers (camelCase, from mcp-servers). Fields memory, skills, rules, mcp, effort, permission-mode, readonly, background, isolation, color, initial-prompt, and hooks are dropped.

Antigravity

Output path: .agents/agents/<id>.md

Antigravity compiles agents to flat Markdown files with YAML frontmatter and a Markdown system prompt body. name, description, model (resolved), tools (list), mainAgent (true), subagent (true), commandExecutionPolicy (sandbox), skills, and inline mcpServers are emitted in the frontmatter. Body content is rendered as the system prompt. Fields without native equivalents (memory, effort, permission-mode, background, isolation, color, hooks) are dropped with fidelity notes.

Codex (Preview)

Output path: .codex/agents/react-developer.toml

Codex is the first provider to use a non-Markdown agent format. Agents are compiled to TOML files. name becomes the TOML table key. description, model (resolved), tools (TOML array), and initial-prompt (as system_prompt) are emitted. Fields without a Codex equivalent — memory, skills, rules, mcp, effort, permission-mode, readonly, background, isolation, color, hooks, mcp-servers — are dropped.

TOML

[react-developer]
description = "Implements React components, hooks, and UI features for frontend-app."
model = "codex-mini-latest"
tools = ["Read", "Edit", "Write", "Bash", "Glob", "Grep"]
system_prompt = """

## Role
Implements and maintains React UI components for `frontend-app`.
…
"""

Previous← Provider Kinds Nextkind: context →

kind: agent

Defines a named subagent/specialist delegated to by the main AI session. Source: xcaf/agents/<name>/agent.xcaf. Compiled to agents/<name>.md per provider.

Required: kind, version, name

Source Directory

xcaf/agents/<name>/agent.xcaf

Example Usage

Minimal agent

.xcaf

---
kind: agent
version: "1.0"
name: reviewer
description: Reviews pull requests for correctness and style.
tools: [Read, Glob, Grep]
readonly: true
---

Review the provided diff for correctness, style, and test coverage.
Flag issues with a severity: `CRITICAL`, `WARN`, or `INFO`.
Report: "Reviewed <N> files, found <M> issues."

Full agent — React developer

.xcaf

---
kind: agent
version: "1.0"
name: react-developer
description: >-
  Implements React components, hooks, and UI features for frontend-app.
  Authorized to modify src/components/, src/hooks/, src/pages/, and
  src/styles/. Consults the component-patterns skill before authoring
  any new component.
model: sonnet
tools:
  - Read
  - Edit
  - Write
  - Bash
  - Glob
  - Grep
memory:
  - user-prefs
  - project-context
skills:
  - component-patterns
rules:
  - react-conventions
mcp:
  - browser-tools
---

## Role
Implements and maintains React UI components for `frontend-app`.
You are the ONLY agent authorized to modify `src/components/`.

## Stack
- React 18, TypeScript 5.x, Next.js 15 (App Router)
- Tailwind CSS v4, Shadcn/UI
- Vitest + React Testing Library, Storybook

## Component Rules
- **Co-locate tests**: every component gets a `<Component>.test.tsx` beside it.
- **No inline styles**: Tailwind utility classes only.
- **Export from barrel**: add new components to `src/components/index.ts`.
- **Accessibility first**: all interactive elements need `aria-label`.

## Mandatory Deliverables
1. Run `pnpm test --filter frontend-app` — all tests must pass.
2. Run `pnpm lint` — zero ESLint errors.
3. Report: "Added <N> components, <M> tests passing."

## DO NOT
- Modify files outside `src/components/`, `src/hooks/`, `src/pages/`, `src/styles/`.
- Use class-based components.
- Leave `any` types in props.

Field Reference

Required Fields

Field	Type	Description
`kind`	`string`	Resource type. Must be `agent`.
`version`	`string`	File format version. Must be `"1.0"`.
`name`	`string`	Unique agent identifier. Must match `[a-z0-9-]+`.

Optional Fields

Field	Type	Description
`description`	`string`	Human-readable purpose of this agent. Used for delegation and auto-invocation.
`model`	`string`	LLM model identifier or alias resolved at compile time. Bare tier aliases (`sonnet`, `opus`, `haiku`) are passed through for runtime resolution.
`effort`	`string`	Reasoning effort level hint for the model provider.
`max-turns`	`int`	Maximum conversation turns before the agent exits.
`tools`	`[]string`	Ordered list of tools this agent may invoke. Omit to inherit all available tools.
`disallowed-tools`	`[]string`	Tools explicitly denied to this agent.
`readonly`	`bool`	When `true`, restricts the agent to read-only tool access.
`permission-mode`	`string`	Security mode controlling tool authorization behavior.
`disable-model-invocation`	`bool`	Prevents the agent from spawning sub-agents.
`user-invocable`	`bool`	Whether users can invoke this agent directly via slash command.
`background`	`bool`	Runs the agent in background mode without interactive prompts.
`isolation`	`string`	Process isolation level for the agent session.
`memory`	`string` or `[]string`	Named memory banks attached to this agent. A single string value is accepted for backward compatibility.
`color`	`string`	Display color for terminal output differentiation.
`initial-prompt`	`string`	System prompt prepended to every conversation.
`skills`	`[]string`	Skill resource IDs attached to this agent. Must match top-level `skills:` map keys.
`rules`	`[]string`	Rule resource IDs governing this agent. Must match top-level `rules:` map keys.
`mcp`	`[]string`	MCP server resource IDs available to this agent. Must match top-level `mcp:` map keys.
`mcp-servers`	`map[string]MCPConfig`	Inline MCP server definitions keyed by server name. Same field schema as `kind: mcp`.
`hooks`	`HookConfig`	Agent-scoped lifecycle hooks. Same structure as `kind: hooks`.
`targets`	`map[string]TargetOverride`	Per-provider overrides keyed by provider name (`antigravity`, `claude`, `copilot`, `cursor`, `gemini`).

`hooks` block

Agent-scoped lifecycle hooks. Same structure as kind: hooks.

PreToolUse — Runs before any tool invocation.
PostToolUse — Runs after any tool invocation.
SessionStart, Stop, Notification, SubagentStop, InstructionsLoaded, PreCompact, ConfigChange — Session lifecycle events.

`mcp-servers` block

Agent-scoped MCP server definitions. Not merged with project-level mcp:. Same field schema as kind: mcp.

`targets` block

Each key under agents.<id>.targets.<target> maps to a TargetOverride struct. Valid target keys are: antigravity, claude, copilot, cursor, gemini, codex.

Field	Type	Status
`suppress-fidelity-warnings`	`*bool`	Parsed, not compiled
`hooks`	`map[string]string`	Parsed, not compiled
`skip-synthesis`	`*bool`	Parsed, not compiled

Provider Fidelity

Not all fields survive compilation to every provider. The table below shows which xcaffold fields are emitted for each target. Fields marked — are dropped silently unless noted.

Field	Claude	Cursor	Copilot	Gemini	Antigravity	Codex (Preview)
`name`	yes	yes	yes	yes	yes (frontmatter)	yes (TOML key)
`description`	yes	yes	yes	yes	yes	yes
`model`	yes (resolved)	mapped only ¹	yes (resolved)	yes (resolved)	yes (resolved)	yes (resolved)
`effort`	yes	—	—	—	—	—
`max-turns`	yes	—	—	`max_turns` ²	yes (`maxTurns`)	—
`tools`	yes (inline)	—	yes (YAML list)	yes (YAML list)	yes (YAML list)	yes (TOML array)
`disallowed-tools`	yes	—	—	—	yes (`disabledTools`)	—
`readonly`	transforms ³	yes	—	—	yes	—
`permission-mode`	yes	—	—	—	—	—
`disable-model-invocation`	—	—	yes	—	—	—
`user-invocable`	—	—	yes	—	yes (`userInvocable`)	—
`background`	yes	`is_background` ²	—	—	—	—
`isolation`	yes	—	—	—	—	—
`memory`	yes	—	—	—	—	—
`color`	yes	—	—	—	—	—
`initial-prompt`	yes	—	—	—	yes	yes (`system_prompt`)
`skills`	yes (inline)	—	—	—	yes	—
`rules`	—	—	—	—	yes	—
`hooks`	yes (YAML)	—	—	—	—	—
`mcp-servers`	yes (YAML)	—	yes (YAML)	`mcpServers` ²	yes (`mcpServers`)	—

Footnotes

Cursor emits model only when IsMappedModel returns true. Unmapped values are dropped with an AGENT_MODEL_UNMAPPED warning to stderr.
Key name differs from the xcaffold canonical: max_turns (snake_case), is_background, mcpServers (camelCase).
Claude: when readonly: true and no tools are specified, emits tools: [Read, Grep, Glob] rather than a readonly key.

Filesystem-as-Schema

When an agent .xcaf file lives at xcaf/agents/<name>/agent.xcaf, the kind: and name: fields can be omitted from the YAML. The parser infers:

kind: agent from the parent directory name (agents/)
name: from the grandparent directory name (e.g., researcher from agents/researcher/agent.xcaf)

When kind: or name: are present in the YAML, they must match the inferred values.

Compiled Output

Claude

Output path: .claude/agents/react-developer.md

.xcaf

---
name: react-developer
description: >-
  Implements React components, hooks, and UI features for frontend-app.
  Authorized to modify src/components/, src/hooks/, src/pages/, and
  src/styles/. Consults the component-patterns skill before authoring
  any new component.
model: claude-sonnet-4-5
tools: [Read, Edit, Write, Bash, Glob, Grep]
memory: project
skills: [component-patterns]
---

## Role
Implements and maintains React UI components for `frontend-app`.
…

Cursor

Output path: .cursor/agents/react-developer.md

.xcaf

---
name: react-developer
description: >-
  Implements React components, hooks, and UI features for frontend-app.
  Authorized to modify src/components/, src/hooks/, src/pages/, and
  src/styles/. Consults the component-patterns skill before authoring
  any new component.
readonly: true
---

## Role
…

Cursor emits name, description, model (mapped models only — unmapped values dropped with AGENT_MODEL_UNMAPPED warning), readonly, and background (renamed to is_background). All other fields — tools, memory, skills, rules, mcp, effort, permission-mode, color, initial-prompt, hooks, mcp-servers — are dropped.

Copilot

Output path: .github/agents/react-developer.agent.md

.xcaf

---
name: react-developer
description: >-
  Implements React components, hooks, and UI features for frontend-app.
  Authorized to modify src/components/, src/hooks/, src/pages/, and
  src/styles/. Consults the component-patterns skill before authoring
  any new component.
model: claude-sonnet-4-6
tools:
  - Read
  - Edit
  - Write
  - Bash
  - Glob
  - Grep
---

## Role
…

Copilot emits name, description, model (resolved), tools (YAML list), disable-model-invocation, user-invocable, and mcp-servers. Fields memory, skills, rules, mcp, effort, permission-mode, readonly, background, isolation, color, initial-prompt, and hooks are dropped.

Native passthrough: when .claude/agents/ is present in the project, Copilot skips compilation for agents and reads the Claude output directly (CLAUDE_NATIVE_PASSTHROUGH).

Gemini

Output path: .gemini/agents/react-developer.md

.xcaf

---
name: react-developer
description: >-
  Implements React components, hooks, and UI features for frontend-app.
  Authorized to modify src/components/, src/hooks/, src/pages/, and
  src/styles/. Consults the component-patterns skill before authoring
  any new component.
model: gemini-2.5-flash
tools:
  - Read
  - Edit
  - Write
  - Bash
  - Glob
  - Grep
max_turns: 10
mcpServers:
  browser-tools:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-browser-tools"]
---

## Role
…

Gemini emits name, description, model (resolved), tools (YAML list), max_turns (snake_case, from max-turns), and mcpServers (camelCase, from mcp-servers). Fields memory, skills, rules, mcp, effort, permission-mode, readonly, background, isolation, color, initial-prompt, and hooks are dropped.

Antigravity

Output path: .agents/agents/<id>.md

Codex (Preview)

Output path: .codex/agents/react-developer.toml

TOML

[react-developer]
description = "Implements React components, hooks, and UI features for frontend-app."
model = "codex-mini-latest"
tools = ["Read", "Edit", "Write", "Bash", "Glob", "Grep"]
system_prompt = """

## Role
Implements and maintains React UI components for `frontend-app`.
…
"""

Previous← Provider Kinds Nextkind: context →

kind: agent

Source Directory

Example Usage

Minimal agent

Full agent — React developer

Field Reference

Required Fields

Optional Fields

hooks block

mcp-servers block

targets block

Provider Fidelity

Filesystem-as-Schema

Compiled Output

Claude

Cursor

Copilot

Gemini

Antigravity

Codex (Preview)

kind: agent

Source Directory

Example Usage

Minimal agent

Full agent — React developer

Field Reference

Required Fields

Optional Fields

hooks block

mcp-servers block

targets block

Provider Fidelity

Filesystem-as-Schema

Compiled Output

Claude

Cursor

Copilot

Gemini

Antigravity

Codex (Preview)

`hooks` block

`mcp-servers` block

`targets` block

`hooks` block

`mcp-servers` block

`targets` block