Index of every page on this site: llms.txt
All skills
am-will avatar

/role-creator

@9f954c3
by am.willam-will/codex-skills1k stars
60
Run it yourself

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

Use this Skill: https://skilld.dev/gh/am-will/codex-skills/role-creator

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈23 tokens for metadata: the name and description. ≈941 when used: this file. ≈1.3k more on demand in 5 files.

Description uses 1.2% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈94 characters, or 1.2%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

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

  1. Collect and confirm required inputs.
  2. Resolve output path:
    • global → ~/.codex/agents/<name>.toml
    • project → <project>/.codex/agents/<name>.toml
  3. Create or update the file directly with required keys.
  4. Validate TOML parse and required keys.
  5. Return a ready-to-run example call:
{"agent_type":"<name>","message":"<task>"}

Commands

# 1) Write a standalone custom-agent file
/home/willr/Applications/skills/skills/role-creator/scripts/write_role_config.sh \
  --output ~/.codex/agents/reviewer.toml \
  --role-name reviewer \
  --description "PR reviewer focused on correctness, security, and risk." \
  --model gpt-5.4 \
  --reasoning high \
  --developer-instructions "Review code like an owner. Lead with concrete findings and residual risks."

# Optional: include nickname candidates for display
/home/willr/Applications/skills/skills/role-creator/scripts/write_role_config.sh \
  --output ~/.codex/agents/reviewer.toml \
  --role-name reviewer \
  --description "PR reviewer focused on correctness, security, and risk." \
  --model gpt-5.4 \
  --reasoning high \
  --developer-instructions "Review code like an owner. Lead with concrete findings and residual risks." \
  --nickname-candidates "Atlas,Delta,Echo" \
  --sandbox-mode read-only \
  --web-search disabled

Guardrails

  • If runtime returns unknown agent_type, verify the active scope and confirm the file exists at the expected path.
  • Check syntax first with tomlq or tomlq -C.
  • Keep role instructions operational and narrowly scoped to avoid drift.

References

  • Codex subagents docs: https://developers.openai.com/codex/subagents
  • Display nicknames: https://developers.openai.com/codex/subagents#display-nicknames
  • Reusable templates: templates/

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

1 alert2mo5 checks · Risk HIGH
  • Gen Agent Trust Hub2mo

    The skill contains a critical security flaw in its configuration script that allows for filter injection, potentially granting unauthorized access or disabling security features. Additionally, it provides a mechanism to read sensitive system files, which could lead to data theft.

  • Socket2mo

    1 alert: gptAnomaly

  • Snyk2mo

    Risk: LOW · No issues

  • Runlayer9mo

    9/9 files flagged

  • ZeroLeaks7mo

    Score: 93/100 · 2 sections analyzed

Signed by skilld at 9f954c3. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub last month.

Steadyupdated 8 months ago
  • codex
  • toml
  • agents
  • custom-agents
  • role-definition
  • configuration

README badge

README badge for am-will/codex-skills/role-creator

Manages creation and updates of Codex custom agents via standalone TOML configuration files in ~/.codex/agents/ or project/.codex/agents/. Collects required inputs (name, description, developer_instructions, model, reasoning_effort), validates them before writing, and generates ready-to-run agent spawn commands.

Generated from the current SKILL.md.

What scope should I use — global or project?
Global agents live in ~/.codex/agents/ and are available across all projects. Project agents live in <project>/.codex/agents/ and are scoped to that project only.
Do I need to register the agent in ~/.codex/config.toml?
No. The agent TOML file is the source of truth. config.toml is only for global runtime settings like thread limits, not per-role registration.
What model should I specify?
The skill recommends gpt-5.3-codex unless you have a specific request. You must explicitly provide the model name — it will not be inferred.
Can I add optional settings like sandbox_mode or web_search later?
Yes. The skill creates a minimal file with only required keys by default. You can edit the TOML to add optional settings like sandbox_mode, web_search, mcp_servers, or model_reasoning_effort after creation.
What characters are allowed in nickname_candidates?
Only ASCII letters, digits, spaces, hyphens, and underscores. Values must be unique and non-empty if the field is included.

Generated from the current SKILL.md. These answers refresh after source changes.