role-creator — Skillopedia

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: - Project: - The agent file is the role source of truth. - is only for global/runtime settings (for example thread limits), not per-role registration. Non-Negotiable Inputs Step 1 is required before writing files: - (role identifier used by ) - (short, human-readable purpose) - - (recommend unless requested) - ( ) - role scope ( or ) - output TOML path (canonical absolute path preferred) - whether to inclu…

| .sandbox_mode = $SANDBOX_MODE'\nfi\n\nif [[ -n \"$network_access\" ]]; then\n expr+=

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.

| .sandbox_workspace_write.network_access = ($NETWORK_ACCESS == \"true\")'\nfi\n\nif [[ -n \"$writable_roots_csv\" ]]; then\n writable_roots_json=\"$(printf '%s' \"$writable_roots_csv\" | jq -Rc 'split(\",\") | map(gsub(\"^\\\\s+|\\\\s+$\"; \"\")) | map(select(length > 0))')\"\n expr+=

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.

| .sandbox_workspace_write.writable_roots = ($WRITABLE_ROOTS_JSON | fromjson)'\nfi\n\nif [[ -n \"$web_search\" ]]; then\n expr+=

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.

| .web_search = $WEB_SEARCH'\nfi\n\nif [[ \"$mcp_clear\" == \"true\" ]]; then\n expr+=

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.

| .mcp_servers = {}'\nfi\n\nif [[ -n \"$mcp_enable_csv\" ]]; then\n IFS=',' read -r -a mcp_enable_arr \u003c\u003c\u003c \"$mcp_enable_csv\"\n for name in \"${mcp_enable_arr[@]}\"; do\n trimmed=\"$(printf '%s' \"$name\" | xargs)\"\n if [[ -n \"$trimmed\" ]]; then\n expr+=\" | .mcp_servers[\\\"$trimmed\\\"].enabled = true\"\n fi\n done\nfi\n\nif [[ -n \"$mcp_disable_csv\" ]]; then\n IFS=',' read -r -a mcp_disable_arr \u003c\u003c\u003c \"$mcp_disable_csv\"\n for name in \"${mcp_disable_arr[@]}\"; do\n trimmed=\"$(printf '%s' \"$name\" | xargs)\"\n if [[ -n \"$trimmed\" ]]; then\n expr+=\" | .mcp_servers[\\\"$trimmed\\\"].enabled = false\"\n fi\n done\nfi\n\nif [[ -n \"$nickname_candidates_csv\" ]]; then\n expr+=

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.

| .nickname_candidates = ($NICKNAME_JSON | fromjson)'\nfi\n\ntomlq -n -t \\\n --arg ROLE_NAME \"$role_name\" \\\n --arg DESCRIPTION \"$role_description\" \\\n --arg MODEL \"$model\" \\\n --arg REASONING \"$reasoning\" \\\n --arg DEVELOPER_INSTRUCTIONS \"$developer_instructions\" \\\n --arg SANDBOX_MODE \"$sandbox_mode\" \\\n --arg NETWORK_ACCESS \"$network_access\" \\\n --arg WRITABLE_ROOTS_JSON \"$writable_roots_json\" \\\n --arg WEB_SEARCH \"$web_search\" \\\n --arg NICKNAME_JSON \"$nickname_json\" \\\n \"$expr\" > \"$output_path\"\n\necho \"Wrote role config to $output_path\"\n","content_type":"application/x-sh; charset=utf-8","language":"bash","size":6194,"content_sha256":"c789787e5246b6ec76c168a105845b97ddfc9dcc7b9811061cb8122296e17deb"},{"filename":"templates/frontend-architecture-role.toml","content":"# Example role that explicitly calls a skill.\n\nmodel = \"gpt-5.3-codex\"\nmodel_reasoning_effort = \"high\"\nmodel_reasoning_summary = \"detailed\"\n\ndeveloper_instructions = \"\"\"\nUse the $frontend-design skill for UI/UX work.\nBuild with a mobile-first approach.\nBuild production-grade, responsive interfaces with clear visual direction.\nPrioritize accessibility, performance, and maintainable component structure.\n\"\"\"\n","content_type":"text/plain; charset=utf-8","language":"toml","size":409,"content_sha256":"1be914b443beed464d7c033633947db60fc1d9b948040acb893be0e72305f0ad"},{"filename":"templates/full-role-config.toml","content":"# Full-surface example. Demonstrates advanced knobs.\n# Do not apply wholesale unless the user asks for each category.\n\nmodel = \"gpt-5.3-codex\"\nmodel_reasoning_effort = \"high\"\nmodel_reasoning_summary = \"detailed\"\nmodel_verbosity = \"high\"\npersonality = \"pragmatic\"\ndeveloper_instructions = \"\"\"\nYou are a senior Product Analyst focused on turning ambiguous goals into\nexecutable requirements and acceptance criteria.\n\"\"\"\n\nsandbox_mode = \"workspace-write\"\nweb_search = \"cached\"\n\n[sandbox_workspace_write]\nnetwork_access = true\nwritable_roots = [\"/path/to/repo\"]\n\n[features]\nmemory_tool = false\nshell_tool = true\n\n[mcp_servers.linear]\ncommand = \"npx\"\nargs = [\"-y\", \"@modelcontextprotocol/server-linear\"]\nenv_vars = [\"LINEAR_API_KEY\"]\nenabled = true\nrequired = false\n\n[apps.notion]\nenabled = true\n\n[apps.monday]\nenabled = false\n","content_type":"text/plain; charset=utf-8","language":"toml","size":822,"content_sha256":"60134bdada604108df20b19f569c875c6754cdc428a7231555f26adf8f97f88b"},{"filename":"templates/minimal-role-config.toml","content":"# Minimal role config (recommended default).\n# Omitted keys inherit from parent config.\n\nmodel = \"gpt-5.3-codex\"\nmodel_reasoning_effort = \"medium\"\ndeveloper_instructions = \"\"\"\nYou are a focused implementation assistant.\nWork only in requested files, validate changes, and report exact evidence.\n\"\"\"\n","content_type":"text/plain; charset=utf-8","language":"toml","size":299,"content_sha256":"7e3373b1ee32edaae8e1b6a40ac0702addca4964e94bd24b289c503d4610c4db"},{"filename":"templates/restricted-role-config.toml","content":"# Constrained role profile. Use only when user explicitly requests restrictions.\n\nmodel = \"gpt-5.3-codex\"\nmodel_reasoning_effort = \"medium\"\ndeveloper_instructions = \"\"\"\nYou are a read-focused analyst.\nDo not modify files. Return concise findings with file:line evidence.\n\"\"\"\n\nsandbox_mode = \"workspace-write\"\nweb_search = \"disabled\"\n\n[sandbox_workspace_write]\nnetwork_access = false\nwritable_roots = [\"/path/to/repo\"]\n\n[features]\nmemory_tool = false\nshell_tool = true\n","content_type":"text/plain; charset=utf-8","language":"toml","size":468,"content_sha256":"6ccbd9fb0e49e8baa26c8c4328947af7445d441d96ea6523d5c7407bcc030710"}],"content_json":{"type":"doc","content":[{"type":"heading","attrs":{"level":1},"content":[{"text":"Role Creator","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Overview","type":"text"}]},{"type":"paragraph","content":[{"text":"Use this skill to author, update, or troubleshoot custom Codex agents as standalone TOML files.","type":"text"}]},{"type":"paragraph","content":[{"text":"Current behavior:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Each custom agent is defined by one file:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Global: ","type":"text"},{"text":"~/.codex/agents/\u003cagent-name>.toml","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Project: ","type":"text"},{"text":"\u003cproject>/.codex/agents/\u003cagent-name>.toml","type":"text","marks":[{"type":"code_inline"}]}]}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"The agent file is the role source of truth.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"~/.codex/config.toml","type":"text","marks":[{"type":"code_inline"}]},{"text":" is only for global/runtime settings (for example ","type":"text"},{"text":"[agents]","type":"text","marks":[{"type":"code_inline"}]},{"text":" thread limits), not per-role registration.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Non-Negotiable Inputs","type":"text"}]},{"type":"paragraph","content":[{"text":"Step 1 is required before writing files:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"name","type":"text","marks":[{"type":"code_inline"}]},{"text":" (role identifier used by ","type":"text"},{"text":"agent_type","type":"text","marks":[{"type":"code_inline"}]},{"text":")","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"description","type":"text","marks":[{"type":"code_inline"}]},{"text":" (short, human-readable purpose)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"developer_instructions","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"model","type":"text","marks":[{"type":"code_inline"}]},{"text":" (recommend ","type":"text"},{"text":"gpt-5.3-codex","type":"text","marks":[{"type":"code_inline"}]},{"text":" unless requested)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"model_reasoning_effort","type":"text","marks":[{"type":"code_inline"}]},{"text":" (","type":"text"},{"text":"none|minimal|low|medium|high|xhigh","type":"text","marks":[{"type":"code_inline"}]},{"text":")","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"role scope (","type":"text"},{"text":"global","type":"text","marks":[{"type":"code_inline"}]},{"text":" or ","type":"text"},{"text":"project","type":"text","marks":[{"type":"code_inline"}]},{"text":")","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"output TOML path (canonical absolute path preferred)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"whether to include ","type":"text"},{"text":"nickname_candidates","type":"text","marks":[{"type":"code_inline"}]},{"text":" and exact values","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Execution rule:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Do not infer required values.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Do not write until required inputs are explicitly confirmed.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Role file contract (current)","type":"text"}]},{"type":"paragraph","content":[{"text":"From Codex custom agent docs (","type":"text"},{"text":"/codex/subagents","type":"text","marks":[{"type":"code_inline"}]},{"text":"):","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Required keys: ","type":"text"},{"text":"name","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"description","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"developer_instructions","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Optional keys: ","type":"text"},{"text":"nickname_candidates","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"model","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"model_reasoning_effort","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"sandbox_mode","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"web_search","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"mcp_servers","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"skills.config","type":"text","marks":[{"type":"code_inline"}]},{"text":", etc.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"name","type":"text","marks":[{"type":"code_inline"}]},{"text":" is the spawn identifier and source of truth.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"description","type":"text","marks":[{"type":"code_inline"}]},{"text":" + ","type":"text"},{"text":"developer_instructions","type":"text","marks":[{"type":"code_inline"}]},{"text":" define behavior and usage boundaries.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"nickname_candidates","type":"text","marks":[{"type":"code_inline"}]},{"text":" is optional and used only for display.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"nickname_candidates","type":"text","marks":[{"type":"code_inline"}]},{"text":" requirements:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Must be a non-empty list of unique values when present.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Allowed characters: ASCII letters, digits, spaces, hyphens, underscores.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Default policy for optional settings","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Do not add sandboxing/MCP/web-search/model extras unless requested.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Keep generated files minimal by default.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"If the user says \"inherit defaults\", omit optional keys instead of setting explicit values.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Workflow","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Collect and confirm required inputs.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Resolve output path:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"global","type":"text","marks":[{"type":"code_inline"}]},{"text":" → ","type":"text"},{"text":"~/.codex/agents/\u003cname>.toml","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"project","type":"text","marks":[{"type":"code_inline"}]},{"text":" → ","type":"text"},{"text":"\u003cproject>/.codex/agents/\u003cname>.toml","type":"text","marks":[{"type":"code_inline"}]}]}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Create or update the file directly with required keys.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Validate TOML parse and required keys.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Return a ready-to-run example call:","type":"text"}]}]}]},{"type":"code_block","attrs":{"wrap":false,"language":"json"},"content":[{"text":"{\"agent_type\":\"\u003cname>\",\"message\":\"\u003ctask>\"}","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Commands","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"# 1) Write a standalone custom-agent file\n/home/willr/Applications/skills/skills/role-creator/scripts/write_role_config.sh \\\n --output ~/.codex/agents/reviewer.toml \\\n --role-name reviewer \\\n --description \"PR reviewer focused on correctness, security, and risk.\" \\\n --model gpt-5.4 \\\n --reasoning high \\\n --developer-instructions \"Review code like an owner. Lead with concrete findings and residual risks.\"\n\n# Optional: include nickname candidates for display\n/home/willr/Applications/skills/skills/role-creator/scripts/write_role_config.sh \\\n --output ~/.codex/agents/reviewer.toml \\\n --role-name reviewer \\\n --description \"PR reviewer focused on correctness, security, and risk.\" \\\n --model gpt-5.4 \\\n --reasoning high \\\n --developer-instructions \"Review code like an owner. Lead with concrete findings and residual risks.\" \\\n --nickname-candidates \"Atlas,Delta,Echo\" \\\n --sandbox-mode read-only \\\n --web-search disabled","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Guardrails","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"If runtime returns ","type":"text"},{"text":"unknown agent_type","type":"text","marks":[{"type":"code_inline"}]},{"text":", verify the active scope and confirm the file exists at the expected path.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Check syntax first with ","type":"text"},{"text":"tomlq","type":"text","marks":[{"type":"code_inline"}]},{"text":" or ","type":"text"},{"text":"tomlq -C","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Keep role instructions operational and narrowly scoped to avoid drift.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"References","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Codex subagents docs: ","type":"text"},{"text":"https://developers.openai.com/codex/subagents","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Display nicknames: ","type":"text"},{"text":"https://developers.openai.com/codex/subagents#display-nicknames","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Reusable templates: ","type":"text"},{"text":"templates/","type":"text","marks":[{"type":"code_inline"}]}]}]}]}]},"metadata":{"date":"2026-11-02","name":"role-creator","author":"@skillopedia","source":{"stars":1041,"repo_name":"codex-skills","origin_url":"https://github.com/am-will/codex-skills/blob/HEAD/skills/role-creator/SKILL.md","repo_owner":"am-will","body_sha256":"2ab043fb9526aa1f9d5afda47789ba7ae3bc3a75b7baa280a2a5a8a7690c88f0","cluster_key":"0d5a343e86f21a23bbba8ecd3f30c55da9260b374139b76f61c6bb5809315e28","clean_bundle":{"format":"clean-skill-bundle-v1","source":"am-will/codex-skills/skills/role-creator/SKILL.md","text_bytes":16193,"source_commit":"9f954c3b63fda0d1875252009c196bf15072c1ca","skills_sh_rank":11728,"attachment_count":8,"text_attachments":8,"attachment_storage":"skill_attachments","binary_attachments":0},"cluster_size":1,"skill_md_path":"skills/role-creator/SKILL.md","import_metadata":{"date":"2026-11-02","author":"@skillopedia","version":"v1","category":"general","category_label":"General"},"exact_dupes_collapsed_into_this":0},"version":"v1","category":"general","import_tag":"skills-sh-top20k-2026-11","description":"Create and update Codex custom agents using standalone custom-agent TOML files."}},"renderedAt":1793671531343}

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.