How to Install and Sync Skills Between Claude Code and Codex

To install and sync skills between Claude Code and Codex, treat the Markdown files under skills/ as your single source of truth, then run the repository's installation scripts to generate compatible packages for both agents.

The xbtlin/ai-berkshire repository maintains a unified workflow system that keeps Claude Code and Codex aligned through synchronized skill definitions. This architecture ensures that workflow updates made for Claude automatically propagate to Codex via automated generation scripts that handle format conversion.

Understanding the Skill Architecture

The repository implements a single source of truth pattern where all canonical workflow definitions reside in the skills/ directory. These files use Claude Code's native slash-command format.

Canonical Source Files

The skills/*.md files contain the master definitions for all workflows. According to the project's Compatibility Rules defined in AGENTS.md, you must treat these files as the canonical source. Any modifications to workflows should occur here first, never in the generated codex-skills/ directory.

Generated Codex Packages

The codex-skills/<skill>/SKILL.md files are auto-generated artifacts created by scripts/sync-codex-skills.py. These files include additional front-matter (name and description) and a Codex adapter note that preserves the original Claude semantics while adding required metadata for Codex compatibility.

Step-by-Step Installation and Sync Process

Follow these three stages to install skills for both agents and maintain synchronization.

1. Install Claude Code Commands: Copy the original skill definitions into Claude's command directory by running:

   bash ./scripts/install-claude-commands.sh

   This script copies the Markdown files from skills/ to $HOME/.claude/commands, making the slash commands available immediately in Claude Code.

2. Generate Codex Skills: Transform the Claude skills into Codex-compatible packages using:

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

   This script reads each file in skills/, injects required front-matter, appends the Codex adapter note, and writes the output to codex-skills/<skill-name>/SKILL.md. The script enforces research-quality policies by preserving references to shared tooling in tools/.

3. Install Codex Skills: Deploy the generated skills to Codex's skill store:

   bash ./scripts/install-codex-skills.sh

   This copies the generated codex-skills/ directories to $HOME/.codex/skills. If you also need slash-command prompts, run ./scripts/install-codex-prompts.sh additionally.

Maintaining Synchronization After Changes

After editing any file in skills/, you must regenerate the Codex packages to prevent drift. Run the sync script again:

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

Then reinstall:

bash ./scripts/install-codex-skills.sh

Verify Sync Status

To check whether the generated files match the current source without overwriting them, use the check mode:

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

This verifies that codex-skills/ is up-to-date with skills/ and reports which files are stale without modifying them.

Summary

• Single source of truth: All edits must happen in skills/*.md, never in generated files.
• Three-stage process: Install Claude commands, generate Codex skills with scripts/sync-codex-skills.py, then install to $HOME/.codex/skills.
• Automated adaptation: The sync script handles front-matter injection and adds Codex adapter notes referencing the original Claude semantics.
• Validation available: Use --check mode to verify synchronization status without regenerating files.

Frequently Asked Questions

What is the canonical source for skill definitions?

The skills/*.md files serve as the single source of truth for workflow definitions. According to the compatibility rules in AGENTS.md, you must edit these files directly when modifying workflows. The codex-skills/ directory contains generated artifacts that get overwritten during the sync process.

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

Run python3 scripts/sync-codex-skills.py --check to validate that the generated Codex packages match the current Claude source files. This mode reports discrepancies without modifying files, allowing you to verify state before regenerating.

What does the sync script add to the Codex skills?

The scripts/sync-codex-skills.py script injects required YAML front-matter containing the skill name and description, plus a Codex adapter note that preserves the original Claude Code semantics and references shared tooling in tools/. These additions ensure Codex can parse the skills while maintaining compatibility with the repository's research-quality standards.

Where are the skills installed on my system?

Claude Code skills install to $HOME/.claude/commands, while Codex skills install to $HOME/.codex/skills. The installation scripts install-claude-commands.sh and install-codex-skills.sh handle these paths automatically, copying from the repository's skills/ and codex-skills/ directories respectively.

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