Role Creator

This walks you through creating standalone TOML files for Codex custom agents, either globally in ~/.codex/agents or per-project. It won't let you proceed until you've confirmed the required fields like name, description, developer_instructions, and model settings. The workflow is deliberately rigid: it collects inputs, writes the file, validates the TOML, and hands you back a ready-to-run agent_type call. Good for setting up reviewers, specialists, or any role you want reproducible across projects. The main value is the guardrails around required fields and the bash script that handles the actual file writing, so you don't have to remember the schema or debug malformed configs manually.

skills.sh installs: 1.2K
GitHub stars: 1K
last updated: Aug 21, 2026

View on GitHub

Install

$ npx -y skills add am-will/codex-skills --skill role-creator --agent claude-code

Installs into .claude/skills of the current project.

Files

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.