# Role Creator

Create and update Codex custom agents using standalone custom-agent TOML files.

- Repository: https://github.com/am-will/codex-skills (1040 stars)
- Category: AI and agents
- License: see repository
- Last updated: 2026-07-14
- Runs scripts: yes, review before use

## Install

Claude Code: `npx skills add am-will/codex-skills --skill role-creator -g -a claude-code -y`
Codex: `npx skills add am-will/codex-skills --skill role-creator -g -a codex -y`
Cursor: `npx skills add am-will/codex-skills --skill role-creator -g -a cursor -y`
Gemini CLI: `npx skills add am-will/codex-skills --skill role-creator -g -a gemini-cli -y`

## Description

Create and update Codex custom agents using standalone custom-agent TOML files.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Role Creator

## Overview

Use this skill to author, update, or troubleshoot custom Codex agents as standalone TOML files.

Current behavior:
- Each custom agent is defined by one file:
  - Global: `~/.codex/agents/<agent-name>.toml`
  - Project: `<project>/.codex/agents/<agent-name>.toml`
- The agent file is the role source of truth.
- `~/.codex/config.toml` is only for global/runtime settings (for example `[agents]` thread limits), not per-role registration.

## Non-Negotiable Inputs

Step 1 is required before writing files:

- `name` (role identifier used by `agent_type`)
- `description` (short, human-readable purpose)
- `developer_instructions`
- `model` (recommend `gpt-5.3-codex` unless requested)
- `model_reasoning_effort` (`none|minimal|low|medium|high|xhigh`)
- role scope (`global` or `project`)
- output TOML path (canonical absolute path preferred)
- whether to include `nickname_candidates` and exact values

Execution rule:
- Do not infer required values.
- Do not write until required inputs are explicitly confirmed.

## Role file contract (current)

From Codex custom agent docs (`/codex/subagents`):
- Required keys: `name`, `description`, `developer_instructions`.
- Optional keys: `nickname_candidates`, `model`, `model_reasoning_effort`, `sandbox_mode`, `web_search`, `mcp_servers`, `skills.config`, etc.
- `name` is the spawn identifier and source of truth.
- `description` + `developer_instructions` define behavior and usage boundaries.
- `nickname_candidates` is optional and used only for display.

`nickname_candidates` requirements:
- Must be a non-empty list of unique values when present.
- Allowed characters: ASCII letters, digits, spaces, hyphens, underscores.

## Default policy for optional settings

- Do not add sandboxing/MCP/web-search/model extras unless requested.
- Keep generated files minimal by default.
- If the user says "inherit defaults", omit optional keys instead of setting explicit values.

## Workflow

The rest: https://github.com/am-will/codex-skills/blob/HEAD/skills/role-creator/SKILL.md