# Agent Creator

> Use when creating expert agents. Generates agent.toml (model tier, sandbox_mode, developer_instructions with required sections) and wires skill references.

- Skill: `fusengine/agent-creator-2` (Agent Skill, multi-file: 11 files)
- Install (CLI): `npx skillmds@latest add fusengine/agent-creator-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/fusengine/agent-creator-2/raw
- Safety review: pending (external: skill-scanner PASS, skillspector CAUTION)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: fusengine (https://skillmd.com/u/fusengine)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/fusengine/agent-creator-2

---


<objective>
Agent Creator scaffolds a complete Codex expert agent: `plugins/<plugin>/agents/<name>.toml` (`name`, `description`, `model` tier + `model_reasoning_effort`, `sandbox_mode`, `nickname_candidates`, `developer_instructions`), the mandatory Agent Workflow section inside `developer_instructions`, and skill wiring via `[[skills.config]]`. It covers three flows -- creating a brand-new domain/framework expert, adapting an existing agent to a new stack, and updating an agent's skills or model tier -- each ending with `bun test scripts/lib/agent-toml.test.ts` and a `sniper` pass.

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.
</objective>

# 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

| Action | When to Use |
|--------|-------------|
| **New Agent** | New domain/framework expert needed |
| **Adapt** | Copy from similar agent (Next.js → React) |
| **Update** | Add skills, change model tier |

---

## 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](references/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](references/architecture.md) for details

---

## Reference Guide

### Concepts

| Topic | Reference | When to Consult |
|-------|-----------|-----------------|
| **Architecture** | [architecture.md](references/architecture.md) | Understanding agent structure |
| **Frontmatter / TOML fields** | [frontmatter.md](references/frontmatter.md) | `name`, `description`, `model`, `model_reasoning_effort`, `sandbox_mode`, `nickname_candidates`, `[[skills.config]]` |
| **Required Sections** | [required-sections.md](references/required-sections.md) | Mandatory `developer_instructions` content, incl. Inherited rules |
| **Hooks** | [hooks.md](references/hooks.md) | `plugins/<plugin>/hooks/hooks.json` Pre/Post tool validation |
| **Registration** | [registration.md](references/registration.md) | Adding a brand-new plugin to the marketplace — not a per-agent step, `agents/*.toml` is auto-discovered |

### Templates

| Template | When to Use |
|----------|-------------|
| [agent-template.md](references/templates/agent-template.md) | Creating a new agent (TOML format) |
| [agent-template-examples.md](references/templates/agent-template-examples.md) | Worked Codex TOML agent examples (Next.js, Laravel) — abbreviated from the real shipped files |
| [hook-scripts.md](references/templates/hook-scripts.md) | Porting check logic into `*.native.ts` hook entries — hooks.json only calls the Harness route |
| [hook-scripts-reference.md](references/templates/hook-scripts-reference.md) | Check-logic reference scripts (SOLID size/interface rules) to port into native-TS Codex hook entries |
| [hook-scripts-reference-2.md](references/templates/hook-scripts-reference-2.md) | Check-logic reference scripts (Swift SOLID, skill-read tracker) — continued from hook-scripts-reference.md |

---

## 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).

| Profile | Use for | Reasoning effort |
|---------|---------|-------------------|
| `gpt-5.6-terra` | The 12 framework/stack experts (astro, go, laravel, nextjs, php, react, rust, shadcn-ui, swift, tailwindcss, tanstack-start, typescript) + 3 volume read/search agents added 2026-09-02 (`explore-codebase`, `research-expert`, `websearch`) — 15 total | `medium` |
| `gpt-5.6-sol` | 15 orchestration/release/validation/prompt-design agents (brainstorming, solid-orchestrator, commit, changelog-watcher, lessons-compactor, seo-expert, seo-content, seo-geo, seo-local, seo-cluster, seo-technical, seo-schema, sniper, prompt-engineer, challenger) | `medium` |
| `gpt-5.6-sol` | Highest-judgment gates (`design-expert`, `security-expert`) | `high` |
| `gpt-5.6-luna` | Bounded, deterministic, mechanical work with a strict, verifiable contract (`sniper-faster`, `commit-detector`, `cartographer`, `seo-images`, `seo-sitemap`) | `max` |

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

```bash
# 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

```bash
# 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](references/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:

| Scenario | Action |
|----------|--------|
| New agent needs skills | Create skills with skill-creator first |
| Agent references skills | Ensure skills exist in skills/ |
| Adapting agent | Adapt related skills too |

---

## 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