Agent skill · software engineering · aiskillstore
role-creator
Create and update Codex custom agents using standalone custom-agent TOML files.
Why this skill is useful
Adds a script for creating and updating Codex custom agents with specific TOML configurations that aren't widely documented.
What it needs
Requires tomlq installed locally. About 2k tokens when loaded. Last updated 2026-08-07. 405 stars on the source repository.
What this skill does
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 agenttype) description (short, human-readable purpose) developerinstructions model (recommend gpt-5.3-codex unless requested) modelreasoningeffort (none minimal low medium high xhigh) role scope (global or project) output TOML path (canonical absolute path preferred) whether to include nicknamecandidates 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, developerinstructions. Optional keys: nicknamecandidates, model, modelreasoningeffort, sandboxmode, websearch, mcpservers, skills.config, etc. name is the spawn identifier and source of truth. description + developerinstructions define behavior and usage boundaries. nicknamecandidates is optional and used only for display. nicknamecandidates 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 1. Collect and confirm required inputs. 2. Resolve output path: global → ~/.codex/agents/<name>.toml project → <project>/.codex/agents/<name>.toml 3. …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills aiskillstore/role-creator