Codex CLI Specialist Skill

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.yaml and 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.json manifest 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.json for 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.py vs cross_platform_validator.py vs skills_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 --strict and 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.yaml structure, 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 |

Agent Skills: Codex CLI Specialist

Install this agent skill to your local

Skill Files