borghei/Claude-Skills / engineering/codex-cli-specialist
codex-cli-specialist
UnverifiedConverts Claude Code skills to OpenAI Codex format (agents/openai.yaml), checks dual-platform compatibility and builds a skills index. Use when porting or syncing skills to Codex, or setting up Codex CLI for a skill library.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 8.9 KB |
| assets/openai-yaml-template.yaml | config | 4.3 KB |
| references/best-practices-and-troubleshooting.md | markdown | 5.9 KB |
| references/codex-cli-guide.md | markdown | 12.0 KB |
| references/configuration-and-distribution.md | markdown | 6.2 KB |
| references/cross-platform-skills.md | markdown | 14.7 KB |
| references/workflows.md | markdown | 12.7 KB |
| scripts/codex_skill_converter.py | script | 14.9 KB |
| scripts/cross_platform_validator.py | script | 22.5 KB |
| scripts/skills_index_builder.py | script | 13.6 KB |
scripts/codex_skill_converter.py
View on GitHub#!/usr/bin/env python3
"""
Codex Skill Converter
Converts a Claude Code SKILL.md into Codex-compatible format by generating
an agents/openai.yaml configuration file alongside the existing skill.
Usage:
python codex_skill_converter.py path/to/SKILL.md
python codex_skill_converter.py path/to/SKILL.md --output-dir ./converted
python codex_skill_converter.py path/to/SKILL.md --json
"""
import argparse
import json
import os
import re
import shutil
import sys
from pathlib import Path
from typing import Any, Dict, List, Optional, Tuple
def parse_yaml_frontmatter(content: str) -> Tuple[Dict[str, Any], str]:
"""Parse YAML frontmatter from markdown content.
Returns a tuple of (frontmatter_dict, body_content).
Uses a simple parser to avoid external dependencies.
"""
frontmatter: Dict[str, Any] = {}
body = content
if not content.startswith("---"):
return frontmatter, body
lines = content.split("\n")
end_index = -1
for i in range(1, len(lines)):
if lines[i].strip() == "---":
end_index = i
break
if end_index == -1:
return frontmatter, body
fm_lines = lines[1:end_index]
body = "\n".join(lines[end_index + 1:]).lstrip("\n")
# Simple YAML key-value parser (handles flat keys and nested metadata)
current_key = None
current_indent = 0
for line in fm_lines:
stripped = line.strip()
if not stripped or stripped.startswith("#"):
continue
indent = len(line) - len(line.lstrip())
# Top-level key: value
match = re.match(r'^(\w[\w-]*)\s*:\s*(.*)', stripped)
if match and indent == 0:
key = match.group(1)
value = match.group(2).strip()
if value:
# Remove surrounding quotes if present
if (value.startswith('"') and value.endswith('"')) or \
(value.startswith("'") and value.endswith("'")):
value = value[1:-1]
frontmatter[key] = value
else:
frontmatter[key] = {}
current_key = key
current_indent = indent
continue
# Nested key: value (under metadata, codex, etc.)
if indent > 0 and current_key and isinstance(frontmatter.get(current_key), dict):
nested_match = re.match(r'^(\w[\w-]*)\s*:\s*(.*)', stripped)
if nested_match:
nkey = nested_match.group(1)
nval = nested_match.group(2).strip()
if (nval.startswith('"') and nval.endswith('"')) or \
(nval.startswith("'") and nval.endswith("'")):
nval = nval[1:-1]
frontmatter[current_key][nkey] = nval
continue
# Multi-line description continuation
if current_key == "description" and indent > 0 and isinstance(frontmatter.get("description"), str):
frontmatter["description"] += " " + stripped
return frontmatter, body
def extract_title(body: str) -> str:
"""Extract the first H1 title from markdown body."""
for line in body.split("\n"):
line = line.strip()
if line.startswith("# "):
return line[2:].strip()
return ""
def extract_scripts(skill_dir: Path) -> List[Dict[str, str]]:
"""Find Python scripts in the skill's scripts/ directory."""
scripts_dir = skill_dir / "scripts"
tools = []
if not scripts_dir.is_dir():
return tools
for script_path in sorted(scripts_dir.glob("*.py")):
name = script_path.stem
# Read first docstring for description
description = f"Runs {script_path.name}"
try:
with open(script_path, "r", encoding="utf-8") as f:
content = f.read()
# Extract module docstring
doc_match = re.search(r'^"""(.*?)"""', content, re.DOTALL)
if not doc_match:
doc_match = re.search(r"^'''(.*?)'''", content, re.DOTALL)
if doc_match:
doc_text = doc_match.group(1).strip()
# Take just the first line or sentence
first_line = doc_text.split("\n")[0].strip()
if first_line:
description = first_line
except (OSError, UnicodeDecodeError):
pass
tools.append({
"name": name,
"description": description,
"command": f"python scripts/{script_path.name}",
})
return tools
def build_instructions(frontmatter: Dict[str, Any], body: str, title: str) -> str:
"""Build Codex instructions from the skill's content."""
lines = []
lines.append(f"You are an expert {title.lower()} specialist.")
lines.append("")
# Extract description for context
desc = frontmatter.get("description", "")
if desc:
lines.append(f"## Purpose")
lines.append(desc)
lines.append("")
# Extract key sections from the body for instructions
sections = extract_key_sections(body)
if sections.get("workflows"):
lines.append("## Key Workflows")
for wf in sections["workflows"][:5]: # Limit to 5 workflows
lines.append(f"- {wf}")
lines.append("")
if sections.get("best_practices"):
lines.append("## Best Practices")
for bp in sections["best_practices"][:8]:
lines.append(f"- {bp}")
lines.append("")
lines.append("## Output Standards")
lines.append("- Provide clear, actionable guidance")
lines.append("- Show concrete examples when possible")
lines.append("- Reference available tools when relevant")
lines.append("- Use the scripts in the scripts/ directory for automation")
return "\n".join(lines)
def extract_key_sections(body: str) -> Dict[str, List[str]]:
"""Extract workflow names and best practices from markdown body."""
result: Dict[str, List[str]] = {"workflows": [], "best_practices": []}
lines = body.split("\n")
in_best_practices = False
for line in lines:
stripped = line.strip()
# Find workflow section headers (### Workflow N: Title)
wf_match = re.match(r'^###\s+(?:Workflow\s+\d+[:.]\s*)?(.+)', stripped)
if wf_match and "workflow" in stripped.lower():
result["workflows"].append(wf_match.group(1).strip())
# Detect best practices sections
if re.match(r'^#{1,3}\s+[Bb]est\s+[Pp]ractices', stripped):
in_best_practices = True
continue
# Next heading exits best practices
if in_best_practices and re.match(r'^#{1,3}\s+', stripped):
in_best_practices = False
continue
# Collect numbered or bulleted items in best practices
if in_best_practices:
bp_match = re.match(r'^[\d]+[.)]\s+\*\*(.+?)\*\*', stripped)
if bp_match:
result["best_practices"].append(bp_match.group(1).strip())
elif stripped.startswith("- ") or stripped.startswith("* "):
text = stripped.lstrip("-* ").strip()
if text and not text.startswith("```"):
result["best_practices"].append(text)
return result
def generate_openai_yaml(
name: str,
description: str,
instructions: str,
tools: List[Dict[str, str]],
version: str = "1.0.0",
model: Optional[str] = None,
) -> str:
"""Generate the agents/openai.yaml content."""
lines = []
lines.append(f"name: {name}")
lines.append("description: >")
# Wrap description at ~78 chars
desc_words = description.split()
current_line = " "
for word in desc_words:
if len(current_line) + len(word) + 1 > 78:
lines.append(current_line.rstrip())
current_line = " " + word
else:
current_line += (" " if len(current_line.strip()) > 0 else "") + word
if current_line.strip():
lines.append(current_line.rstrip())
lines.append("instructions: |")
for inst_line in instructions.split("\n"):
if inst_line:
lines.append(f" {inst_line}")
else:
lines.append("")
if tools:
lines.append("tools:")
for tool in tools:
lines.append(f" - name: {tool['name']}")
lines.append(f" description: >")
lines.append(f" {tool['description']}")
lines.append(f" command: {tool['command']}")
if model:
lines.append(f"model: {model}")
lines.append(f"version: {version}")
return "\n".join(lines) + "\n"
def convert_skill(
skill_md_path: str,
output_dir: Optional[str] = None,
) -> Dict[str, Any]:
"""Convert a Claude Code SKILL.md to Codex-compatible format.
Returns a result dict with status, warnings, and generated files.
"""
result: Dict[str, Any] = {
"status": "success",
"source": str(skill_md_path),
"output_dir": "",
"files_generated": [],
"files_copied": [],
"warnings": [],
"errors": [],
}
skill_md = Path(skill_md_path).resolve()
if not skill_md.is_file():
result["status"] = "error"
result["errors"].append(f"File not found: {skill_md}")
return result
if skill_md.name != "SKILL.md":
result["warnings"].append(
f"Expected filename 'SKILL.md', got '{skill_md.name}'. Proceeding anyway."
)
skill_dir = skill_md.parent
# Determine output directory
if output_dir:
out_path = Path(output_dir).resolve()
else:
out_path = skill_dir
result["output_dir"] = str(out_path)
# Read and parse SKILL.md
try:
with open(skill_md, "r", encoding="utf-8") as f:
content = f.read()
except (OSError, UnicodeDecodeError) as e:
result["status"] = "error"
result["errors"].append(f"Cannot read {skill_md}: {e}")
return result
frontmatter, body = parse_yaml_frontmatter(content)
if not frontmatter:
result["warnings"].append("No YAML frontmatter found. Using defaults.")
# Extract key fields
name = frontmatter.get("name", skill_dir.name)
description = frontmatter.get("description", "")
title = extract_title(body) or name
if not description:
description = f"Expert guidance for {title}."
result["warnings"].append("No description in frontmatter. Generated a default.")
# Extract metadata
metadata = frontmatter.get("metadata", {})
version = "1.0.0"
if isinstance(metadata, dict):
version = metadata.get("version", "1.0.0")
# Check for Codex-specific hints
codex_hints = frontmatter.get("codex", {})
model = None
if isinstance(codex_hints, dict):
model = codex_hints.get("model")
# Find scripts
tools = extract_scripts(skill_dir)
# Build instructions
instructions = build_instructions(frontmatter, body, title)
# Generate openai.yaml
yaml_content = generate_openai_yaml(
name=name,
description=description,
instructions=instructions,
tools=tools,
version=version,
model=model,
)
# Create output directory structure
try:
agents_dir = out_path / "agents"
agents_dir.mkdir(parents=True, exist_ok=True)
yaml_path = agents_dir / "openai.yaml"
with open(yaml_path, "w", encoding="utf-8") as f:
f.write(yaml_content)
result["files_generated"].append(str(yaml_path))
except OSError as e:
result["status"] = "error"
result["errors"].append(f"Cannot write output: {e}")
return result
# If output dir differs from source, copy other files
if out_path != skill_dir:
for subdir in ["scripts", "references", "assets"]:
src = skill_dir / subdir
dst = out_path / subdir
if src.is_dir():
try:
if dst.exists():
shutil.rmtree(dst)
shutil.copytree(src, dst)
result["files_copied"].append(str(dst))
except OSError as e:
result["warnings"].append(f"Could not copy {subdir}/: {e}")
# Copy SKILL.md
dst_skill = out_path / "SKILL.md"
try:
shutil.copy2(skill_md, dst_skill)
result["files_copied"].append(str(dst_skill))
except OSError as e:
result["warnings"].append(f"Could not copy SKILL.md: {e}")
# Check for existing openai.yaml that was overwritten
if (skill_dir / "agents" / "openai.yaml").is_file() and out_path == skill_dir:
result["warnings"].append(
"Overwrote existing agents/openai.yaml. Previous version not backed up."
)
return result
def format_human_output(result: Dict[str, Any]) -> str:
"""Format result as human-readable text."""
lines = []
lines.append("Codex Skill Converter")
lines.append("=" * 40)
lines.append("")
lines.append(f"Source: {result['source']}")
lines.append(f"Output: {result['output_dir']}")
lines.append(f"Status: {result['status'].upper()}")
lines.append("")
if result["files_generated"]:
lines.append("Files Generated:")
for f in result["files_generated"]:
lines.append(f" + {f}")
lines.append("")
if result["files_copied"]:
lines.append("Files Copied:")
for f in result["files_copied"]:
lines.append(f" > {f}")
lines.append("")
if result["warnings"]:
lines.append("Warnings:")
for w in result["warnings"]:
lines.append(f" ! {w}")
lines.append("")
if result["errors"]:
lines.append("Errors:")
for e in result["errors"]:
lines.append(f" X {e}")
lines.append("")
if result["status"] == "success":
lines.append("Conversion complete. Review agents/openai.yaml before deploying.")
else:
lines.append("Conversion failed. See errors above.")
return "\n".join(lines)
def main() -> None:
parser = argparse.ArgumentParser(
description="Convert a Claude Code SKILL.md into Codex-compatible format.",
epilog="Example: python codex_skill_converter.py path/to/SKILL.md --output-dir ./converted",
)
parser.add_argument(
"skill_md",
help="Path to the Claude Code SKILL.md file to convert",
)
parser.add_argument(
"--output-dir",
default=None,
help="Output directory for the converted skill (default: same as source)",
)
parser.add_argument(
"--json",
action="store_true",
help="Output results in JSON format",
)
args = parser.parse_args()
if not os.path.isfile(args.skill_md):
print(f"Error: SKILL.md not found: {args.skill_md}", file=sys.stderr)
sys.exit(2)
result = convert_skill(args.skill_md, args.output_dir)
if args.json:
print(json.dumps(result, indent=2))
else:
print(format_human_output(result))
if result["status"] != "success":
sys.exit(1)
if __name__ == "__main__":
main()
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 470k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |