How to Sync Claude Code Commands to Codex Skills with sync-codex-skills.py

Run python3 scripts/sync-codex-skills.py from the repository root to automatically convert Claude Code skill definitions into Codex-compatible skill packages.

The xbtlin/ai-berkshire repository maintains a dual workflow: human-readable Claude Code commands stored as Markdown in skills/, and machine-readable Codex skill packages. Keeping these in sync is handled by a single Python script that generates the Codex layer from the canonical source.

What the Script Does

The scripts/sync-codex-skills.py utility bridges the two ecosystems. It reads every *.md file in the skills/ directory, transforms the content into the format expected by Codex, and writes the output to codex-skills/<skill-name>/SKILL.md.

This ensures that any updates to Claude Code commands are immediately reflected for Codex users without manual copy-pasting.

Prerequisites

Before running the sync, ensure you have:

• Python 3.8+ installed
• The repository cloned locally
• (Optional) A virtual environment activated

git clone https://github.com/xbtlin/ai-berkshire.git
cd ai-berkshire
python3 -m venv .venv && source .venv/bin/activate

Syncing Commands to Skills

Basic Synchronization

To perform a full sync that updates all Codex skill packages:

python3 scripts/sync-codex-skills.py

The script walks through skills/, parses each Markdown file, and generates the corresponding directory structure under codex-skills/. If a skill already exists and the generated content matches, the file remains unchanged to avoid unnecessary diffs.

Verify Without Writing (--check)

For CI pipelines or pre-commit verification, use the dry-run flag:

python3 scripts/sync-codex-skills.py --check

This compares the current codex-skills/ content against the generated output. If any file is out of date, the script exits with a non-zero status code, failing the build.

Internal Workflow

The script executes a four-stage pipeline:

1. Discovery: Uses glob to collect all skills/*.md files.
2. Parsing: Extracts the command name from the filename and reads the description/body from the Markdown content.
3. Rendering: Formats the data into the Codex skill template, including metadata headers and usage examples.
4. Writing: Creates codex-skills/<skill-name>/ directories as needed and writes SKILL.md files.

Idempotency is preserved by comparing existing file contents before overwriting.

Related Automation

The repository includes a similar utility for slash prompts. While scripts/sync-codex-skills.py handles the primary skill definitions, you can also run scripts/sync-codex-prompts.py to synchronize prompt definitions if your workflow includes them.

Summary

• Primary script: scripts/sync-codex-skills.py converts Claude Code markdown to Codex packages.
• Source: skills/*.md files (canonical definitions).
• Output: codex-skills/<skill-name>/SKILL.md (generated artifacts).
• Dry-run: Use --check for CI verification without file modification.
• Idempotency: Unchanged files are skipped to keep diffs clean.

Frequently Asked Questions

What is the difference between skills in the skills/ and codex-skills/ directories?

The skills/ directory contains the canonical Markdown definitions used by Claude Code, written for human readability. The codex-skills/ directory contains auto-generated packages that Codex consumes as machine-readable skills. You should only edit files in skills/; the sync script handles the rest.

How do I know if my Codex skills are out of sync?

Run python3 scripts/sync-codex-skills.py --check. If the script reports any discrepancies or exits with a non-zero code, the generated files no longer match the source Markdown. Run the script without the flag to regenerate them.

Can I customize the output format of the generated skills?

Yes. The transformation logic resides in scripts/sync-codex-skills.py. Modify the rendering stage within the script to change the metadata headers, file structure, or content formatting. After editing the script, re-run it to apply your changes to all generated skills.

Should I commit the generated files in codex-skills/ to version control?

Yes. While these files are generated, the repository treats them as self-contained artifacts. Committing them ensures that Codex users can use the skills immediately after cloning, without needing to run the sync script themselves.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}