Skip to content

CowboyLogic/ai-dev / skills/agent-creator-codex

agent-creator-codex

Verified

Guide for creating custom subagents for OpenAI Codex (standalone TOML files in .codex/agents/ or ~/.codex/agents/, each with name, description, and developer_instructions). Use this skill whenever a user wants to build, configure, review, or modify a Codex agent, choose fields (model, model_reasoning_effort, developer_instructions, and the other keys a role file can actually set), tune the [agents] table in config.toml (concurrency, default subagent model), or troubleshoot a Codex agent that is not found, never spawned, on the wrong model, or unexpectedly writing files or missing MCP servers. ALWAYS load this skill before writing or debugging Codex agent files.

FileKindSize
README.mdmarkdown4.1 KB
SKILL.mdskill md17.8 KB
references/agent-examples.mdmarkdown4.2 KB
references/config-reference.mdmarkdown7.7 KB
references/troubleshooting.mdmarkdown5.9 KB
scripts/validate-agent.pyscript7.8 KB

scripts/validate-agent.py

View on GitHub
#!/usr/bin/env python3
"""Validate Codex custom agent TOML files.

Usage:
    validate-agent.py <file-or-directory> [...] [--strict]

Checks that each file parses as TOML, has non-blank `name`, `description`, and
`developer_instructions`, uses known snake_case keys, and that names are unique across the
scanned set. Directories are scanned recursively, as Codex does. Warns on keys Codex accepts
but ignores in a role file. Uses only the standard library (Python 3.11+).
Exit status is 1 when any error is found (or any warning with --strict).

Field list and load rules verified October 2026 with `codex doctor` against test files on
codex-cli 0.163.0, plus https://developers.openai.com/codex/subagents.
"""

from __future__ import annotations

import argparse
import difflib
import re
import sys
from pathlib import Path

try:
    import tomllib
except ImportError:  # pragma: no cover
    sys.exit("Python 3.11+ is required (tomllib)")

REQUIRED = ("name", "description", "developer_instructions")
# Keys Codex applies from a role file (codex-rs/core/src/agent/role.rs, rust-v0.163.0).
APPLIED_KEYS = set(REQUIRED) | {
    "nickname_candidates", "model", "model_reasoning_effort", "model_reasoning_summary",
    "model_verbosity", "personality", "features", "skills",
}
# Valid config.toml keys that parse in a role file but are dropped when the role is applied:
# the child inherits the parent's sandbox, approvals, and MCP servers.
IGNORED_KEYS = {
    "sandbox_mode": "the child uses the parent session's sandbox; start the parent with --sandbox",
    "approval_policy": "the child uses the parent session's approval policy",
    "mcp_servers": "the child uses the parent's MCP servers; configure them in the parent config",
    "web_search": "not applied to roles; set it on the parent",
    "model_provider": "not applied to roles",
    "service_tier": "the child uses the root session's service tier; set it on the root session",
    "shell_environment_policy": "not applied to roles",
    "sandbox_workspace_write": "not applied to roles",
    "tools": None,  # handled below: a table is valid config, a list is a foreign field
}
KNOWN_KEYS = APPLIED_KEYS | set(IGNORED_KEYS)
# `memory_tool` is the legacy key for the feature `codex features list` shows as `memories`.
DISABLE_ONLY_FEATURES = {
    "shell_tool", "apps", "plugins", "memories", "memory_tool", "request_permissions_tool",
}
SANDBOX_MODES = {"read-only", "workspace-write", "danger-full-access"}
# Fields from other agent tools that Codex does not have.
FOREIGN = {
    "tools": "Codex has no tool allowlist; restrict tools on the parent session (--sandbox, MCP config), "
             "or disable features in the role with [features] shell_tool = false",
    "disallowedTools": "Claude Code field; Codex has no equivalent",
    "permissionMode": "Claude Code field; set the sandbox on the parent session (--sandbox)",
    "permission": "OpenCode field; set the sandbox on the parent session (--sandbox)",
    "mode": "OpenCode field",
    "temperature": "OpenCode field",
    "tools_list": "not a Codex field",
    "maxTurns": "Claude Code field",
    "disable-model-invocation": "Copilot field",
    "user-invocable": "Copilot field",
    "handoffs": "Copilot field",
}
NAME_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_-]*$")


class Result:
    def __init__(self) -> None:
        self.errors = 0
        self.warnings = 0

    def error(self, path: Path, msg: str) -> None:
        self.errors += 1
        print(f"ERROR   {path}: {msg}")

    def warn(self, path: Path, msg: str) -> None:
        self.warnings += 1
        print(f"WARNING {path}: {msg}")


def suggest(key: str) -> str:
    snake = re.sub(r"(?<!^)(?=[A-Z])", "_", key).replace("-", "_").lower()
    if snake in KNOWN_KEYS and snake != key:
        return f" (did you mean `{snake}`?)"
    close = difflib.get_close_matches(key, KNOWN_KEYS, n=1, cutoff=0.75)
    return f" (did you mean `{close[0]}`?)" if close else ""


def check_string(res: Result, path: Path, data: dict, key: str) -> None:
    if key not in data:
        res.error(path, f"missing required `{key}`")
    elif not isinstance(data[key], str):
        res.error(path, f"`{key}` must be a string")
    elif not data[key].strip():
        res.error(path, f"`{key}` must not be blank")


def validate_file(path: Path, names: dict[str, Path], res: Result) -> None:
    try:
        data = tomllib.loads(path.read_text(encoding="utf-8"))
    except tomllib.TOMLDecodeError as exc:
        res.error(path, f"TOML does not parse: {exc}")
        return
    except OSError as exc:
        res.error(path, f"cannot read: {exc}")
        return

    for key in REQUIRED:
        check_string(res, path, data, key)

    name = data.get("name")
    if isinstance(name, str) and name.strip():
        if not NAME_RE.match(name):
            res.warn(path, f"name `{name}` has characters other than letters, digits, `_`, `-`")
        if name in names:
            res.error(path, f"duplicate name `{name}` (also in {names[name]})")
        else:
            names[name] = path
        if path.stem != name:
            res.warn(path, f"filename `{path.stem}` does not match name `{name}`")

    for key in data:
        if key == "tools" and not isinstance(data[key], dict):
            res.error(path, f"`tools`: {FOREIGN['tools']}")
            continue
        if IGNORED_KEYS.get(key):
            res.warn(path, f"`{key}` is ignored in a role file: {IGNORED_KEYS[key]}")
            continue
        if key in KNOWN_KEYS:
            continue
        if key in FOREIGN:
            res.error(path, f"`{key}`: {FOREIGN[key]}")
        else:
            res.warn(path, f"unknown key `{key}`{suggest(key)}")

    sandbox = data.get("sandbox_mode")
    if sandbox is not None and sandbox not in SANDBOX_MODES:
        res.error(path, f"sandbox_mode `{sandbox}` not one of {sorted(SANDBOX_MODES)}")

    features = data.get("features")
    if isinstance(features, dict):
        for fname, on in features.items():
            if fname in DISABLE_ONLY_FEATURES and not isinstance(on, bool):
                res.error(path, f"features.{fname} must be a boolean, not {type(on).__name__}; "
                                "Codex ignores the whole file with `expected a boolean`")
            elif on is True or fname not in DISABLE_ONLY_FEATURES:
                res.warn(path, f"features.{fname} = {str(on).lower()} has no effect in a role file; "
                               f"roles can only disable {sorted(DISABLE_ONLY_FEATURES)}")

    nick = data.get("nickname_candidates")
    if nick is not None and not (isinstance(nick, list) and all(isinstance(n, str) for n in nick)):
        res.error(path, "nickname_candidates must be an array of strings")

    body = data.get("developer_instructions")
    if isinstance(body, str) and 0 < len(body.strip()) < 40:
        res.warn(path, "developer_instructions is very short; state role, scope, and return format")


def collect(target: Path) -> list[Path]:
    if target.is_dir():
        return sorted(target.rglob("*.toml"))
    return [target]


def main() -> int:
    ap = argparse.ArgumentParser(description=__doc__.splitlines()[0])
    ap.add_argument("paths", nargs="+", type=Path)
    ap.add_argument("--strict", action="store_true", help="treat warnings as failures")
    args = ap.parse_args()

    res = Result()
    names: dict[str, Path] = {}
    files: list[Path] = []
    for p in args.paths:
        if not p.exists():
            res.error(p, "path does not exist")
            continue
        files.extend(collect(p))
    if not files and not res.errors:
        print("No .toml files found")
        return 1
    for f in files:
        validate_file(f, names, res)

    print(f"\n{len(files)} file(s), {res.errors} error(s), {res.warnings} warning(s)")
    return 1 if res.errors or (args.strict and res.warnings) else 0


if __name__ == "__main__":
    sys.exit(main())
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 469kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 321kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 321kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 321kUpdated Claude CodeCodexVerifiedInstall