Agent Creator

It does not create the skills an agent references -- for that, use skill-creator; agent-creator only wires the agent TOML and workflow around skills that already exist or are created alongside it. It also does not define hooks -- those live in the plugin's hooks/hooks.json, never in the agent file.

Agent Creator

Agent Workflow (MANDATORY)

Before ANY agent creation, delegate via spawn_agent — spawn 2 agents in parallel (single message, two spawn_agent calls). A Codex agent TOML has no tool-list field of its own — tool access is governed by sandbox_mode, not a per-agent list — so any internal delegation a generated agent performs must itself read as spawn_agent by bare agent name, never a Claude-style team-spawn primitive:

1. explore-codebase - Check existing agents, analyze patterns
2. research-expert - Fetch latest agent conventions

mcp__context7__query-docs is a direct MCP call, not a spawned agent — invoke it directly (alongside the 2 spawn_agent calls) to get examples from existing agents.

After creation, run bun test scripts/lib/agent-toml.test.ts then sniper for validation.

Overview

Critical Rules

1. Unique kebab-case name - matches the filename, is what spawn_agent targets
2. Complete TOML - name; description with a Use when… / Do NOT use for… routing pattern; model as an explicit tier from the Model Tier Matrix below (never the bare gpt-5.6 alias) with a matching model_reasoning_effort; sandbox_mode; nickname_candidates ASCII-only, non-empty, no duplicates (Codex silently drops the whole agent otherwise — it never becomes spawnable); developer_instructions covering every section in required-sections.md, including the "Inherited rules (from AGENTS.md)" block
3. Hooks belong to the plugin, not the agent - plugins/<plugin>/hooks/hooks.json; there is no hooks field on a Codex agent
4. Validate - bun test scripts/lib/agent-toml.test.ts (checks the model matrix and agentRoleViolations), then sniper
5. Internal delegation - every developer_instructions describes delegation as spawn_agent calls by name; never a generic agent when a domain expert exists

Architecture

plugins/<plugin-name>/
├── agents/
│   └── <agent-name>.toml    # Agent definition (TOML, not Markdown)
├── skills/
│   ├── skill-a/
│   └── solid-[stack]/
├── hooks/
│   └── hooks.json           # Plugin-level Pre/Post tool validation
└── .codex-plugin/
    └── plugin.json

→ See architecture.md for details

Reference Guide

Concepts

Templates

Model Tier Matrix

Choose the tier explicitly — never the bare gpt-5.6 alias. Full rationale: docs/reference/creating-skills-agents.md (model policy section).

Terra/medium (Terra's default effort) is the executor tier for the 12 framework experts: a 15-run codex exec 0.152.1 benchmark on 2026-09-02 (3 bounded coding tasks × 5 configs, hidden tests) passed every test on every tier while Terra medium was 1.7x faster and half the cost of Sol medium, and a 6-run repetition passed 6/6. Later the same day, owner decision "passe en terra medium" added explore-codebase, research-expert, and websearch to Terra/medium too — this trio is volume/read work (doc lookup, web search, codebase exploration), NOT covered by the coding-task benchmark; the known Terra risk below is unverified rather than measured for these three. Until 2026-09-02, Sol kept 3 judgment gates at high (challenger, security-expert, plus design-expert at xhigh); two same-day owner decisions ("seul le designer en high", then "security-expert en high") retired Sol xhigh fleet-wide and left exactly 2 agents at Sol/high — design-expert and security-expert — while challenger joined Sol/medium. Sol/medium also holds the analysis/orchestration agents and the coordinator session stays Sol high; Luna max keeps the 5 mechanical agents. sniper moved to Sol/medium on 2026-09-02 (owner decision): it validates code with tooling and tests, where the benchmark showed medium equal to high. prompt-engineer — previously a Sol/high judgment gate alongside challenger and security-expert — also moved to Sol/medium the same day (owner decision: "il est assez intelligent"), joining the analysis/research/coordination agents. Known risk: openai/codex#32389 (Terra intermittently returns an empty final response after tool use) is still open — the coordinator's on-disk PRD check plus the challenger and sniper gates turn it into a retry, never a silent bad merge; for the 3 volume agents, the same-day mitigation is procedural: a research/exploration agent whose final report is empty or truncated is relaunched immediately with the same brief, never accepted as "nothing found" (see plugins/ai-pilot/skills/lead-orchestration/SKILL.md and plugins/codex-rules/rules/03-agent-teams.md).

Quick Reference

Create New Agent

# 1. Research existing agents
→ explore-codebase + research-expert

# 2. Create the TOML
touch plugins/<plugin>/agents/<agent-name>.toml

# 3. Add/confirm plugins/<plugin>/hooks/hooks.json (never inside the agent TOML)

# 4. Validate
bun test scripts/lib/agent-toml.test.ts
→ sniper

Adapt Existing Agent

# 1. Copy similar agent
cp plugins/nextjs-expert/agents/nextjs-expert.toml plugins/new-plugin/agents/new-expert.toml

# 2. Adapt with sed
sed -i '' "s/nextjs/newstack/g; s/Next\.js/NewStack/g" agents/new-expert.toml

# 3. Update skills.config paths, model tier, nickname_candidates

Validation Checklist

• name unique, kebab-case, matches the filename
• description follows Use when… / Do NOT use for…
• model is an explicit tier from the Model Tier Matrix, with a matching model_reasoning_effort
• sandbox_mode set (read-only / workspace-write / danger-full-access)
• nickname_candidates non-empty, ASCII, no duplicates
• developer_instructions covers every required-sections.md section, incl. Inherited rules (from AGENTS.md)
• No hooks, tool-list, or display-color key on the agent TOML
• Every [[skills.config]] path resolves on disk
• bun test scripts/lib/agent-toml.test.ts passes
• sniper reports zero errors

Related: Skill Creator

When creating an agent, you often need to create skills too.

Use skill-creator to create skills for the agent:

Best Practices

DO

• Use skill-creator for associated skills
• Reference the solid-[stack] skill for SOLID rules
• Include Gemini Design guidance inside developer_instructions for UI agents
• Pick model + reasoning effort from the Model Tier Matrix, never guess

DON'T

• Write in French (English only)
• Skip the Agent Workflow section inside developer_instructions
• Put a hooks table, a tool list, or a display color on the agent TOML
• Create an agent without its skills
• Assign the bare gpt-5.6 alias, or put a judgment role (design-expert, security-expert at Sol/high; challenger, sniper, prompt-engineer at Sol/medium) on Terra or Luna