# Packaged custom-agent schema notes

This file documents the strict Codex custom-agent shape used by the packaged `.codex/agents/*.toml` files.

## Required fields

- `name` (string)
- `description` (string)
- `developer_instructions` (multiline string)

## Common optional fields used in this package

- `model` (string)
- `model_reasoning_effort` (string)
- `sandbox_mode` (string)
- `mcp_servers` (table)

## Source of truth split

- `.codex/config.toml` carries only global session and subagent settings such as `[agents].max_threads` and `[agents].max_depth`.
- `.codex/agents/*.toml` carries the standalone custom-agent definitions.
- `templates/codex/routing-profiles.toml` is package metadata that documents the shipped routing policy without extending Codex runtime config.

## Example

```toml
name = "reviewer"
description = "PR reviewer focused on correctness, security, and missing tests."
model_reasoning_effort = "high"
sandbox_mode = "read-only"

developer_instructions = """
Review code like an owner.
Prioritize correctness, security, behavior regressions, and missing test coverage.
Lead with concrete findings and avoid style-only comments unless they hide a real bug.
"""
```
