codex-cli-specialist

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.

Table of Contents

• [Quick Start](#quick-start)
• [Tools Overview](#tools-overview)
• [Core Workflows](#core-workflows)
• [Codex CLI Configuration Deep Dive](#codex-cli-configuration-deep-dive)
• [Cross-Platform Skill Patterns](#cross-platform-skill-patterns)
• [Skill Installation and Management](#skill-installation-and-management)
• [Integration Points](#integration-points)
• [Best Practices](#best-practices)
• [Reference Documentation](#reference-documentation)
• [Common Patterns Quick Reference](#common-patterns-quick-reference)

Quick Start

# Install Codex CLI
npm install -g @openai/codex

# Verify installation
codex --version

# Convert an existing Claude Code skill to Codex format
python scripts/codex_skill_converter.py path/to/SKILL.md --output-dir ./converted

# Validate a skill works on both Claude Code and Codex
python scripts/cross_platform_validator.py path/to/skill-dir

# Build a skills index from a directory of skills
python scripts/skills_index_builder.py /path/to/skills --output skills-index.json

Tools Overview

1. Codex Skill Converter

Converts a Claude Code SKILL.md into Codex-compatible format by generating an agents/openai.yaml configuration and restructuring metadata.

Input: Path to a Claude Code SKILL.md file Output: Codex-compatible skill directory with agents/openai.yaml

Usage:

# Convert a single skill
python scripts/codex_skill_converter.py my-skill/SKILL.md

# Specify output directory
python scripts/codex_skill_converter.py my-skill/SKILL.md --output-dir ./codex-skills/my-skill

# JSON output for automation
python scripts/codex_skill_converter.py my-skill/SKILL.md --json

What it does:

• Parses YAML frontmatter from SKILL.md
• Extracts name, description, and metadata
• Generates agents/openai.yaml with proper schema
• Copies scripts, references, and assets
• Reports conversion status and any warnings

2. Cross-Platform Validator

Validates that a skill directory is compatible with both Claude Code and Codex CLI environments.

Input: Path to a skill directory Output: Validation report with pass/fail status and recommendations

Usage:

# Validate a skill directory
python scripts/cross_platform_validator.py my-skill/

# Strict mode - treat warnings as errors
python scripts/cross_platform_validator.py my-skill/ --strict

# JSON output
python scripts/cross_platform_validator.py my-skill/ --json

Checks performed:

• SKILL.md exists and has valid YAML frontmatter
• Required frontmatter fields present (name, description)
• Description uses third-person format for auto-discovery
• agents/openai.yaml exists and is valid YAML
• scripts/ directory contains executable Python files
• No external dependencies beyond standard library
• File structure matches expected patterns

3. Skills Index Builder

Builds a skills-index.json manifest from a directory of skills, useful for skill registries and discovery systems.

Input: Path to a directory containing skill subdirectories Output: JSON manifest with skill metadata

Usage:

# Build index from skills directory
python scripts/skills_index_builder.py /path/to/skills

# Custom output file
python scripts/skills_index_builder.py /path/to/skills --output my-index.json

# Human-readable output
python scripts/skills_index_builder.py /path/to/skills --format human

# Include only specific categories
python scripts/skills_index_builder.py /path/to/skills --category engineering

Output includes:

• Skill name, description, version
• Available scripts and tools
• Category and domain classification
• File counts and sizes
• Platform compatibility flags

Core Workflows

Workflow 1: Install and Configure Codex CLI

Step 1: Install Codex CLI

# Install globally via npm
npm install -g @openai/codex

# Verify installation
codex --version
codex --help

Step 2: Configure API access

# Set your OpenAI API key
export OPENAI_API_KEY="sk-..."

# Or configure via the CLI
codex configure

Step 3: Choose an approval mode and run

# suggest (default) - you approve each change
codex --approval-mode suggest "refactor the auth module"

# auto-edit - auto-applies file edits, asks before shell commands
codex --approval-mode auto-edit "add input validation"

# full-auto - fully autonomous (use in sandboxed environments)
codex --approval-mode full-auto "set up test infrastructure"

Workflow 2: Author a Codex Skill from Scratch

Step 1: Create directory structure

mkdir -p my-skill/agents
mkdir -p my-skill/scripts
mkdir -p my-skill/references
mkdir -p my-skill/assets

Step 2: Write SKILL.md with compatible frontmatter

---
name: my-skill
description: This skill should be used when the user asks to "do X",
  "perform Y", or "analyze Z". Use for domain expertise, automation,
  and best practice enforcement.
license: MIT + Commons Clause
metadata:
  version: 1.0.0
  category: engineering
  domain: development-tools
---

# My Skill

Description and workflows here...

Step 3: Create agents/openai.yaml

# Use the template from assets/openai-yaml-template.yaml
name: my-skill
description: >
  Expert guidance for X, Y, and Z.
instructions: |
  You are an expert at X. When the user asks about Y,
  follow these steps...
tools:
  - name: my_tool
    description: Runs the my_tool.py script
    command: python scripts/my_tool.py

Step 4: Add Python tools

# Create your script
touch my-skill/scripts/my_tool.py
chmod +x my-skill/scripts/my_tool.py

Step 5: Validate the skill

python cross_platform_validator.py my-skill/

Workflow 3: Convert Claude Code Skills to Codex

Step 1: Identify skills to convert

# List all skills in a directory
find engineering/ -name "SKILL.md" -type f

Step 2: Run the converter

# Convert a single skill
python scripts/codex_skill_converter.py engineering/code-reviewer/SKILL.md \
  --output-dir ./codex-ready/code-reviewer

# Batch convert (shell loop)
for skill_md in engineering/*/SKILL.md; do
  skill_name=$(basename $(dirname "$skill_md"))
  python scripts/codex_skill_converter.py "$skill_md" \
    --output-dir "./codex-ready/$skill_name"
done

Step 3: Review and adjust generated openai.yaml

The converter generates a baseline agents/openai.yaml. Review it for:

• Accuracy of the instructions field
• Completeness of the tools list
• Correct command paths for scripts

Step 4: Validate the converted skill

python scripts/cross_platform_validator.py ./codex-ready/code-reviewer

Workflow 4: Validate Cross-Platform Compatibility

# Run validator on a skill (outputs PASS/WARN/FAIL for each check)
python scripts/cross_platform_validator.py my-skill/

# Strict mode (warnings become errors)
python scripts/cross_platform_validator.py my-skill/ --strict --json

The validator checks both Claude Code compatibility (SKILL.md, frontmatter, scripts) and Codex CLI compatibility (agents/openai.yaml, tool references), plus cross-platform checks (UTF-8 encoding, skill size, name consistency).

Workflow 5: Build and Publish a Skills Index

# Build index from a directory of skills
python scripts/skills_index_builder.py ./engineering --output skills-index.json

# Human-readable summary
python scripts/skills_index_builder.py ./engineering --format human

Codex CLI Configuration Deep Dive

agents/openai.yaml Structure

The agents/openai.yaml file is the primary configuration for Codex C