Codex CLI Bridge Skill

Purpose

This skill creates a comprehensive bridge between Claude Code and OpenAI's Codex CLI, enabling seamless interoperability through:

• Documentation Translation: Converts CLAUDE.md → AGENTS.md (reference-based, no file duplication)

• Execution Helpers: Python wrappers for Codex CLI commands (always uses codex exec )

• Skill Documentation: Makes Claude Skills accessible to Codex CLI users

Key Capabilities

1. CLAUDE.md → AGENTS.md Generation

• Parses CLAUDE.md and project structure

• Scans .claude/skills/ , .claude/agents/ , documentation/ folders

• Generates comprehensive AGENTS.md with file path references

• Reference-based: No file duplication, only links to existing files

• Documents Skills with most relevant usage method (bash scripts vs prompt references)

2. Safety Mechanism

• Auto-checks Codex CLI installation (codex --version )

• Auto-runs /init if CLAUDE.md missing (with user notification)

• Validates authentication and environment

• User-friendly error messages

3. Codex CLI Execution Helpers

• exec_analysis()

• Read-only analysis tasks (gpt-5, read-only sandbox)

• exec_edit()

• Code editing tasks (gpt-5-codex, workspace-write)

• exec_with_search()

• Web search-enabled tasks

• resume_session()

• Continue last Codex session

• Always uses codex exec (never plain codex

• critical for Claude Code)

4. Skill Documentation for Codex CLI

• Prompt-only skills: Show how to reference in Codex prompts

• Functional skills: Show how to execute Python scripts directly

• Complex skills: Show both methods

• Includes proper codex exec command syntax

• Model selection guidance (gpt-5 vs gpt-5-codex)

Input Requirements

For AGENTS.md Generation

{ "action": "generate-agents-md", "project_root": "/path/to/project", "options": { "validate_codex": true, "auto_init": true, "include_mcp": true, "skill_detail_level": "relevant" } }

For Codex Execution

{ "action": "codex-exec", "task_type": "analysis|edit|search", "prompt": "Your task description", "model": "gpt-5|gpt-5-codex", "sandbox": "read-only|workspace-write|danger-full-access" }

Output Formats

AGENTS.md Structure

AGENTS.md

Project Overview

[From CLAUDE.md]

Available Skills

Skill Name

Location: path/to/skill/ Using from Codex CLI: [Most relevant method]

Workflow Patterns

[Slash commands → Codex equivalents]

MCP Integration

[MCP server references]

Command Reference

Execution Helper Output

{ "status": "success|error", "output": "Command output", "session_id": "uuid", "model_used": "gpt-5|gpt-5-codex", "command": "codex exec ..." }

Python Scripts

safety_mechanism.py

• Check Codex CLI installation

• Validate CLAUDE.md exists (auto-run /init if missing)

• Environment validation

• User notifications

claude_parser.py

• Parse CLAUDE.md sections

• Scan skills, agents, commands

• Extract quality gates and MCP configuration

• Return file paths only (no content duplication)

project_analyzer.py

• Auto-detect project structure

• Discover all Claude Code assets

• Generate project metadata

• Build reference map

agents_md_generator.py

• Template-based AGENTS.md generation

• File path references (no duplication)

• Skill documentation (most relevant method)

• Workflow translation (Claude → Codex)

skill_documenter.py

• Document skills for Codex CLI users

• Determine most relevant usage method per skill type

• Generate bash examples for Python scripts

• Create Codex prompt templates

codex_executor.py

• Python wrappers for Codex CLI commands

• Intelligent model selection (gpt-5 vs gpt-5-codex)

• Sandbox mode helpers

• Session management

• Always uses codex exec

Usage Examples

Example 1: Generate AGENTS.md

User prompt:

Generate AGENTS.md for this project

What happens:

• Safety mechanism checks Codex CLI installed

• Checks CLAUDE.md exists (auto-runs /init if missing)

• Parses CLAUDE.md and project structure

• Generates AGENTS.md with file references

• Documents all skills with most relevant usage method

Output: Complete AGENTS.md file in project root

Example 2: Execute Codex Analysis Task

User prompt:

Use Codex to analyze this codebase for security vulnerabilities

What happens:

from codex_executor import CodexExecutor

executor = CodexExecutor() result = executor.exec_analysis( "Analyze this codebase for security vulnerabilities", model="gpt-5" )

Executes:

codex exec -m gpt-5 -s read-only
-c model_reasoning_effort=high
"Analyze this codebase for security vulnerabilities"

Example 3: Execute Codex Code Editing

User prompt:

Use Codex to refactor main.py for better async patterns

What happens:

executor = CodexExecutor() result = executor.exec_edit( "Refactor main.py for better async patterns", model="gpt-5-codex" )

Executes:

codex exec -m gpt-5-codex -s workspace-write
-c model_reasoning_effort=high
"Refactor main.py for better async patterns"

Example 4: Resume Codex Session

User prompt:

Continue the previous Codex session

What happens:

executor = CodexExecutor() result = executor.resume_session()

Executes:

codex exec resume --last

Best Practices

For AGENTS.md Generation

• Always run on projects with CLAUDE.md (or let auto-init create it)

• Validate Codex CLI installed first

• Keep skills documented with most relevant method (bash vs prompt)

• Use reference-based approach (no file duplication)

For Codex Execution

• Use codex exec always (never plain codex in Claude Code)

• Choose correct model:

• gpt-5 : General reasoning, architecture, analysis

• gpt-5-codex : Code editing, specialized coding tasks

• Choose correct sandbox:

• read-only : Safe analysis (default)

• workspace-write : File modifications

• danger-full-access : Network access (rarely needed)

• Enable search when needed (--search flag)

For Skill Documentation

• Prompt-only skills: Reference in Codex prompts

• Functional skills: Execute Python scripts directly

• Complex skills: Show both methods

• Always provide working examples

Command Integration

This skill integrates with existing Claude Code commands:

• /init : Auto-generates AGENTS.md after CLAUDE.md creation

• /update-claude : Regenerates AGENTS.md when CLAUDE.md changes

• /check-docs : Validates AGENTS.md exists and is in sync

• /sync-agents-md : Manual AGENTS.md regeneration

• /codex-exec <task> : Wrapper using codex_executor.py

Installation

Prerequisites

Codex CLI installed:

codex --version # Should show v0.48.0 or higher

Codex authenticated:

codex login

Claude Code v1.0+

Install Skill

Option 1: Copy to project

cp -r generated-skills/codex-cli-bridge ~/.claude/skills/

Option 2: Use from this repository

Skill auto-discovered when Claude Code loads this project

Troubleshooting

Error: "Codex CLI not found"

Solution: Install Codex CLI and ensure it's in PATH

which codex # Should return path codex --version # Should work

Error: "CLAUDE.md not found"

Solution: Skill auto-runs /init with notification. If it fails:

Manually run /init

/init

Error: "stdout is not a terminal"

Solution: Always use codex exec , never plain codex

❌ codex -m gpt-5 "task" ✅ codex exec -m gpt-5 "task"

AGENTS.md Out of Sync

Solution: Regenerate manually

/sync-agents-md

References

• Codex CLI Docs: openai-codex-cli-instructions.md

• Claude Skills Docs: claude-skills-instructions.md

• Example Skills: claude-skills-examples/codex-cli-skill.md

• AGENTS.md Spec: https://agents.md/

Version

v1.0.0 - Initial release (2025-10-30)

License

Apache 2.0

Created by: Claude Code Skills Factory Maintained for: Cross-tool team collaboration (Claude Code ↔ Codex CLI) Sync Status: Reference-based bridge (one-way sync: CLAUDE.md → AGENTS.md)