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/, .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 (`claude`, `cursor`, `copilot`, `gemini`, `antigravity`).

`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: claude, cursor, antigravity, copilot, 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	body only	yes (TOML key)
`description`	yes	yes	yes	yes	body only	yes
`model`	yes (resolved)	mapped only ¹	yes (resolved)	yes (resolved)	body only	yes (resolved)
`effort`	yes	—	—	—	—	—
`max-turns`	yes	—	—	`max_turns` ²	—	—
`tools`	yes (inline)	—	yes (YAML list)	yes (YAML list)	—	yes (TOML array)
`disallowed-tools`	yes	—	—	—	—	—
`readonly`	transforms ³	yes	—	—	—	—
`permission-mode`	yes	—	—	—	—	—
`disable-model-invocation`	—	—	yes	—	—	—
`user-invocable`	—	—	yes	—	—	—
`background`	yes	`is_background` ²	—	—	—	—
`isolation`	yes	—	—	—	—	—
`memory`	yes	—	—	—	—	—
`color`	yes	—	—	—	—	—
`initial-prompt`	yes	—	—	—	—	yes (`system_prompt`)
`skills`	yes (inline)	—	—	—	—	—
`hooks`	yes (YAML)	—	—	—	—	—
`mcp-servers`	yes (YAML)	—	yes (YAML)	`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/react-developer.md

Agent compiled as a specialist note (persona profile). Fidelity note RENDERER_KIND_DOWNGRADED emitted to stderr indicating that Antigravity does not support native agent definitions. name, description, model, and body content are folded into the note body; no frontmatter fields are emitted.

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 (`claude`, `cursor`, `copilot`, `gemini`, `antigravity`).

`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: claude, cursor, antigravity, copilot, 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	body only	yes (TOML key)
`description`	yes	yes	yes	yes	body only	yes
`model`	yes (resolved)	mapped only ¹	yes (resolved)	yes (resolved)	body only	yes (resolved)
`effort`	yes	—	—	—	—	—
`max-turns`	yes	—	—	`max_turns` ²	—	—
`tools`	yes (inline)	—	yes (YAML list)	yes (YAML list)	—	yes (TOML array)
`disallowed-tools`	yes	—	—	—	—	—
`readonly`	transforms ³	yes	—	—	—	—
`permission-mode`	yes	—	—	—	—	—
`disable-model-invocation`	—	—	yes	—	—	—
`user-invocable`	—	—	yes	—	—	—
`background`	yes	`is_background` ²	—	—	—	—
`isolation`	yes	—	—	—	—	—
`memory`	yes	—	—	—	—	—
`color`	yes	—	—	—	—	—
`initial-prompt`	yes	—	—	—	—	yes (`system_prompt`)
`skills`	yes (inline)	—	—	—	—	—
`hooks`	yes (YAML)	—	—	—	—	—
`mcp-servers`	yes (YAML)	—	yes (YAML)	`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/react-developer.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