# Claude Code vs Codex Usage in AI Berkshire: Key Differences Explained > Discover the key differences between Claude Code and Codex usage in AI Berkshire. Understand how they manage skills from Markdown source files vs sync scripts. - Repository: [Xbt Lin/ai-berkshire](https://github.com/xbtlin/ai-berkshire) - Tags: deep-dive - Published: 2026-07-10 --- **AI Berkshire supports two distinct AI-assisted authoring workflows: Claude Code reads skills directly from Markdown source files, while Codex requires generated artifacts maintained through sync scripts.** The `xbtlin/ai-berkshire` repository implements a dual-environment architecture that accommodates both **Claude Code** and **Codex** usage patterns. Understanding the difference between these two workflows ensures proper skill maintenance and prevents synchronization errors. The repository's [`AGENTS.md`](https://github.com/xbtlin/ai-berkshire/blob/main/AGENTS.md) file serves as the canonical reference for these compatibility rules. ## Source of Truth and File Structure The fundamental distinction lies in how each environment accesses skill definitions. ### Claude Code Direct Access **Claude Code** operates directly against the canonical source files located in the `skills/` directory. These Markdown files (e.g., [`skills/wechat-article.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/wechat-article.md)) serve as the single source of truth, requiring no intermediate build steps or generated artifacts. When you invoke a skill, Claude Code reads the Markdown directly from this directory. ### Codex Generated Artifacts **Codex** usage relies on derived artifacts stored in `codex-skills/` and `codex-prompts/`. The `codex-skills/` directory contains generated packages (such as `codex-skills/*/SKILL.md`) derived from the source `skills/` files. Similarly, `codex-prompts/` houses generated slash-prompt compatibility files. These directories are **not** source files—they are build outputs that must be regenerated after any change to the `skills/` directory. ## Workflow and Compatibility Process The operational workflows differ significantly between the two environments. ### Claude Code Workflow No additional steps are required to use Claude Code. After editing any file in `skills/`, the changes are immediately available. You can invoke skills directly without running synchronization scripts. ### Codex Synchronization Requirements Codex requires explicit synchronization through Python scripts located in `scripts/`: 1. Run `python3 scripts/sync-codex-skills.py` to regenerate the `codex-skills/` directory from the source `skills/` files. 2. Optionally run `python3 scripts/sync-codex-prompts.py` to update the slash-prompt compatibility layer in `codex-prompts/`. Failure to execute these scripts after editing `skills/` files results in Codex using outdated skill definitions. ## Editing Guidelines and Version Control Understanding where to make edits prevents accidental overwrites of generated content. ### Where to Edit Always edit the original Markdown files in `skills/` regardless of which environment you target. The `codex-skills/` and `codex-prompts/` directories contain generated files that are overwritten during synchronization. Only modify generated files under `codex-skills/` if you deliberately intend to create a Codex-only custom skill, which must be clearly marked as such. ### Version Control Strategy Commit the `skills/` directory as the primary version-controlled source. For Codex usage, commit the generated `codex-skills/` and `codex-prompts/` directories only after running the sync scripts, ensuring they reflect the latest changes from the `skills/` source. ## Practical Usage Examples ### Running Claude Code Skills Invoke skills directly without build steps: ```bash # Directly invoke a Claude Code skill claude-code run wechat-article --input "Write a summary of the latest AI news." ``` ### Running Codex Skills First synchronize, then execute: ```bash # Sync after editing skills/wechat-article.md python3 scripts/sync-codex-skills.py # Then invoke the Codex version codex run wechat-article --input "Write a summary of the latest AI news." ``` ### Full Synchronization Workflow For complete compatibility including slash-prompts: ```bash python3 scripts/sync-codex-skills.py python3 scripts/sync-codex-prompts.py ``` ## Summary - **Claude Code** reads directly from `skills/*.md` with no build step required. - **Codex** depends on generated artifacts in `codex-skills/` and `codex-prompts/` that require running [`scripts/sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-skills.py) after any source change. - Always edit files in `skills/`; never edit generated files in `codex-skills/` unless creating a Codex-only custom skill. - Version control the `skills/` directory as the source of truth, and commit generated directories only after synchronization. ## Frequently Asked Questions ### Do I need to run sync scripts for Claude Code? No. Claude Code reads the canonical Markdown files directly from the `skills/` directory. You only need to run `python3 scripts/sync-codex-skills.py` and `python3 scripts/sync-codex-prompts.py` when updating Codex artifacts. ### What happens if I edit files in codex-skills/ directly? Manual edits to `codex-skills/*/SKILL.md` or other generated files will be overwritten the next time you run [`scripts/sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-skills.py). The script regenerates these files from the `skills/` source, so persistence requires editing the source files instead. ### Where is the compatibility documentation located? The [`AGENTS.md`](https://github.com/xbtlin/ai-berkshire/blob/main/AGENTS.md) file in the repository root contains the complete compatibility rules and project layout documentation. It specifies the workflow differences and synchronization requirements for both Claude Code and Codex environments as implemented in `xbtlin/ai-berkshire`. ### Can I create a skill that only works with Codex? Yes, but you must clearly mark it as a Codex-only custom skill. However, the standard workflow encourages maintaining all skills in `skills/` and using the sync scripts to generate Codex-compatible versions, ensuring consistency across both environments.