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

> Easily sync Claude Code skill definitions to Codex format using the sync-codex-skills.py script. Automate conversions and streamline your AI development workflow.

- Repository: [Xbt Lin/ai-berkshire](https://github.com/xbtlin/ai-berkshire)
- Tags: how-to-guide
- Published: 2026-07-11

---

**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`](https://github.com/xbtlin/ai-berkshire/blob/main/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

```bash
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:

```bash
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:

```bash
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`](https://github.com/xbtlin/ai-berkshire/blob/main/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`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-skills.py) handles the primary skill definitions, you can also run [`scripts/sync-codex-prompts.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-prompts.py) to synchronize prompt definitions if your workflow includes them.

## Summary

- **Primary script**: [`scripts/sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/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`](https://github.com/xbtlin/ai-berkshire/blob/main/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.