Codex CLI Specialist
The agent converts Claude Code skills to Codex-compatible format, validates cross-platform compatibility, and builds skill registry manifests. It generates agents/openai.yaml configurations from SKILL.md frontmatter, runs 17 compatibility checks across both platforms, and produces skills-index.json for discovery systems.
Core Capabilities
- Skill conversion — turn a Claude Code SKILL.md into a Codex-compatible skill by generating
agents/openai.yamland copying scripts/references/assets. - Cross-platform validation — run 17 checks across Claude Code, Codex CLI, and shared categories (frontmatter, openai.yaml, encoding, naming, size).
- Index building — scan skill directories and emit a
skills-index.jsonmanifest for registries, discovery, and version pinning. - Codex CLI setup & operation — install, configure API access, and run with the right approval mode (suggest / auto-edit / full-auto).
- Dual-target authoring — write skills that work on both platforms from one shared
scripts/,references/,assets/tree. - Distribution & sync — keep Claude Code and Codex in sync via shared repo, CI/CD conversion, or git hooks; publish via GitHub releases.
When to Use
- Setting up or operating OpenAI Codex CLI.
- Converting or syncing skills between Claude Code and Codex.
- Configuring or reviewing
agents/openai.yaml. - Validating a skill for dual-platform compatibility.
- Building a
skills-index.jsonfor a skill library.
Clarify First
Before converting or building, confirm these inputs. If any is unknown or vague, ASK — do not assume:
- Task — convert a skill, validate cross-platform compatibility, or build a skills index (selects
codex_skill_converter.pyvscross_platform_validator.pyvsskills_index_builder.py) - Source path — the SKILL.md or skill directory to operate on (the input the scripts read)
- Strictness — strict validation mode and whether to fail on warnings (sets
--strictand the pass/fail gate)
Stop rule: ask only the 2-3 that most change the output. If the user says "just draft it," proceed and list your assumptions at the top of the artifact.
Tools
| Tool | Purpose | Command |
|---|---|---|
codex_skill_converter.py | Convert a Claude Code SKILL.md into Codex format (agents/openai.yaml) | python scripts/codex_skill_converter.py <skill_md> [--output-dir DIR] [--json] |
cross_platform_validator.py | Run 17 Claude Code + Codex + cross-platform compatibility checks on a skill dir | python scripts/cross_platform_validator.py <skill_dir> [--strict] [--json] |
skills_index_builder.py | Build a skills-index.json manifest from a directory of skills | python scripts/skills_index_builder.py <skills_dir> [--output FILE] [--format json|human] [--category CAT] |
References
Load the reference that matches the task — keep this file lean and pull detail on demand:
- references/workflows.md — Quick Start, Tools Overview, the 5 core workflows (install, author, convert, validate, build index), Common Patterns, and deep per-tool parameter/output reference. Read when running a workflow or needing exact tool arguments.
- references/configuration-and-distribution.md —
agents/openai.yamlstructure, discovery/locations, invocation patterns, cross-platform patterns, frontmatter compatibility, install/versioning, and sync/CI/CD/GitHub distribution. Read when configuring openai.yaml or distributing a library. - references/best-practices-and-troubleshooting.md — best practices (authoring, Codex usage, cross-platform, performance), anti-patterns, troubleshooting table, and success criteria. Read before shipping or when a tool misbehaves.
- references/codex-cli-guide.md — full Codex CLI reference: installation, configuration, approval modes, skill system, invocation, built-in features, environment variables.
- references/cross-platform-skills.md — writing skills for multiple agents (Claude Code, Codex, Cursor, Copilot, Goose): platform comparison, universal structure, per-platform config files, template.
- assets/openai-yaml-template.yaml — production-grade Codex config template (instructions, tools, model selection, versioning).
Scope & Limitations
This skill covers:
- Installing, configuring, and operating OpenAI Codex CLI
- Converting Claude Code SKILL.md files into Codex-compatible format with
agents/openai.yaml - Validating skill directories for dual-platform (Claude Code + Codex CLI) compatibility
- Building skill registry manifests (
skills-index.json) for discovery and distribution
This skill does NOT cover:
- Writing the actual domain logic inside Python tool scripts (see senior-fullstack, code-reviewer, or the relevant domain skill)
- Cursor, Windsurf, Cline, or Aider platform-specific configuration (see standards/ and root-level dotfiles like
.cursorrules,.windsurfrules) - OpenAI API key management, billing, or rate-limit troubleshooting (out of scope -- refer to OpenAI documentation)
- Automated testing or CI/CD pipeline authoring beyond skill validation (see senior-devops and templates/)
Integration Points
| Skill | Integration | Data Flow |
|---|---|---|
| code-reviewer | Convert code-reviewer's SKILL.md to Codex format so it can run in Codex CLI | codex_skill_converter.py reads code-reviewer's SKILL.md and generates agents/openai.yaml |
| senior-fullstack | Validate fullstack skill's cross-platform compatibility after adding Codex support | cross_platform_validator.py checks both SKILL.md frontmatter and openai.yaml structure |
| senior-devops | Embed skill validation and index building into CI/CD pipelines | DevOps workflows call cross_platform_validator.py --strict --json and skills_index_builder.py as pipeline steps |
| tech-stack-evaluator | Evaluate whether Codex CLI fits a project's AI tooling stack | Tech stack evaluator references Codex CLI capabilities and configuration patterns from this skill |
| senior-architect | Architect multi-agent skill systems that span Claude Code and Codex CLI | Architect uses cross-platform skill patterns and index manifests to plan skill distribution |