codex-cli-specialist

name: codex-cli-specialistdescription: >  OpenAI Codex CLI and cross-platform skill authoring. Use when setting up Codex CLI,  converting or syncing skills between Claude Code and Codex, configuring agents/openai.yaml,  or validating cross-platform skill compatibility.license: MIT + Commons Clausemetadata:   version: 1.1.0  author: borghei  category: engineering  domain: development-tools  updated: 2026-06-17  tags: [openai-codex, cross-platform, skill-conversion, cli]

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, settle the inputs below. When one is missing or vague and would change the result, ask about it; when it wouldn't, use a sensible default and say which one you used.

• 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).

Ask about the two or three inputs that matter most for this request, not the whole list. If the user wants a result straight away, produce it and state your assumptions at the top.

Tools

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