# How to Install and Sync Skills Between Claude Code and Codex > Learn to install and sync skills between Claude Code and Codex. Use Markdown files as your source of truth and run installation scripts for seamless agent integration. - Repository: [Xbt Lin/ai-berkshire](https://github.com/xbtlin/ai-berkshire) - Tags: how-to-guide - Published: 2026-07-03 --- **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`](https://github.com/xbtlin/ai-berkshire/blob/main/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.md` files are auto-generated artifacts created by [`scripts/sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/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 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: ```bash 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.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 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`](https://github.com/xbtlin/ai-berkshire/blob/main/./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: ```bash python3 ./scripts/sync-codex-skills.py ``` Then reinstall: ```bash 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: ```bash 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`](https://github.com/xbtlin/ai-berkshire/blob/main/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`](https://github.com/xbtlin/ai-berkshire/blob/main/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`](https://github.com/xbtlin/ai-berkshire/blob/main/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`](https://github.com/xbtlin/ai-berkshire/blob/main/install-claude-commands.sh) and [`install-codex-skills.sh`](https://github.com/xbtlin/ai-berkshire/blob/main/install-codex-skills.sh) handle these paths automatically, copying from the repository's `skills/` and `codex-skills/` directories respectively.