role-creator_skill

Overview

This skill creates, installs, and validates Codex custom agent roles by writing a role config file and registering the role in a target config.toml. It enforces the supported declaration keys and follows a strict-minimal default: only model, model_reasoning_effort, and developer_instructions are set unless you ask for more. Install scope can be global (~/.codex/config.toml) or project-scoped, and every write is gated behind explicit input confirmation. The skill produces a runnable spawn example and runs schema validation before reporting success.

How this skill works

Step 1 collects and confirms required inputs (model, model_reasoning_effort, developer_instructions, install scope, role_name, description, role_config_file). After confirmation, the skill validates environment and schema presence, writes the role-specific config file using the provided script, installs the role declaration into the chosen config.toml using an installer script, and runs validation against codex-rs/core/config.schema.json. Optional controls are only added when explicitly requested; otherwise keys are omitted so they inherit parent defaults.

When to use it

• You need a new custom agent role installed globally or in a specific project
• You want to update a role config file and register the role without breaking other config entries
• You want minimal, auditable role configs that only set required fields by default
• You need to validate that a role declaration uses only supported keys
• You want an example spawn payload to run the role after installation

Best practices

• Always complete the non-negotiable input gate before any write: model, reasoning, developer_instructions, scope, role_name, description, role_config_file
• Accept explicit defaults only when you intentionally want them; do not let the skill infer missing required values
• Keep role configs minimal; add sandboxing, web_search, MCP, or features only when explicitly requested
• Install globally for reusable roles and project-scoped for repo-specific roles to avoid cross-project leakage
• Rely on provided templates for advanced edits and run validation after manual changes

Example use cases

• Create a research-only agent role that uses gpt-5.3-codex with medium reasoning and read-only guidance
• Install a project-scoped role for a single repo to restrict web_search and workspace write access
• Update an existing role description and re-install with --update-existing after editing the role config file
• Troubleshoot a runtime error by validating that the role declaration only contains description and config_file
• Generate a spawnable JSON example so other tools can call the new role immediately