# Relationship Between `skills/*.md` and `codex-skills/*/SKILL.md` in AI-Berkshire > Understand the relationship between skills/*.md and codex-skills/*/SKILL.md in AI-Berkshire. Learn how canonical workflows translate to OpenAI Codex adapters for seamless integration. - Repository: [Xbt Lin/ai-berkshire](https://github.com/xbtlin/ai-berkshire) - Tags: internals - Published: 2026-07-03 --- **The `skills/*.md` files serve as the canonical source of truth for agent workflows, while `codex-skills/*/SKILL.md` files are auto-generated adapters that translate these definitions for OpenAI Codex compatibility.** The **AI-Berkshire** repository maintains a strict single-source-of-truth architecture where Markdown files in the `skills/` directory define complete agent-based workflows. When the project is built for Codex users, the [`scripts/sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-skills.py) utility automatically transforms these canonical definitions into the `codex-skills//SKILL.md` format. ## Understanding the Single Source of Truth Architecture In `xbtlin/ai-berkshire`, the **Canonical Skill Definitions** reside in `skills/*.md`. These files contain the complete workflow specifications—including prompts, phases, and parameters—that power Claude-Code slash commands. The **Codex Compatibility Layer** exists in `codex-skills/*/SKILL.md`. According to the repository's compatibility rules documented in [`AGENTS.md`](https://github.com/xbtlin/ai-berkshire/blob/main/AGENTS.md) (lines 24-34), these files are strictly auto-generated and should never be edited manually. When you modify any file in `skills/`, you must run the synchronization script to propagate changes to the Codex-compatible directory. This ensures that both Claude-Code and Codex users interact with identical workflow logic. ## How the Sync Script Transforms Skill Definitions The [`scripts/sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-skills.py) script handles the conversion from canonical to Codex format. During generation, it performs several key transformations: - **Adds adapter metadata** that wraps the original skill definition - **Implements `$ARGUMENTS` handling** for Codex-specific parameter passing - **Injects provenance headers** that cite the source file path Each generated [`SKILL.md`](https://github.com/xbtlin/ai-berkshire/blob/main/SKILL.md) begins with a YAML frontmatter block that explicitly references its origin. For example, the **wechat-article** skill generates: ```markdown --- name: wechat-article description: "AI Berkshire skill: 微信公众号文章：作者-编辑-读者三Agent协作. Source: skills/wechat-article.md." --- ``` This header makes the file's auto-generated status immediately visible to developers browsing the `codex-skills/` directory. ## Editing Workflow and File Regeneration To modify a skill and update its Codex counterpart, follow this three-step workflow: 1. **Edit the canonical source file** in the `skills/` directory: ```bash vim skills/wechat-article.md ``` 2. **Run the synchronization script** to regenerate the Codex adapter: ```bash python3 scripts/sync-codex-skills.py ``` 3. **Verify the output** appears at the correct path: ``` codex-skills/wechat-article/SKILL.md ``` ### Checking Sync Status Without Regenerating To determine whether your generated files have drifted from their sources without writing changes, use the `--check` flag: ```bash python3 scripts/sync-codex-skills.py --check ``` If any `skills/*.md` file differs from its generated counterpart in `codex-skills/`, the script reports the specific mismatches without modifying files. ## Key Differences: Source vs. Generated Files Understanding the distinction between these file sets prevents accidental edits that would be overwritten on the next sync: - **`skills/*.md` (Canonical Source)**: Hand-written by developers containing the full Claude-Code prompt syntax and workflow definitions. These files provide the slash-command interface and maintain the authoritative business logic. - **`codex-skills/*/SKILL.md` (Auto-Generated)**: Produced by the sync script to provide Codex-compatible formatting. These files include adapter notes and modified argument handling, but any manual modifications are destroyed when the script runs. - **Update Trigger**: Changes to `skills/*.md` require explicit script execution, while `codex-skills/*/SKILL.md` updates happen only through automation. ## Summary - The `skills/*.md` files in `xbtlin/ai-berkshire` serve as the **single source of truth** for all agent workflows. - The `codex-skills/*/SKILL.md` files are **auto-generated adapters** created by [`scripts/sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-skills.py). - Always edit files in `skills/`; never modify files in `codex-skills/` directly. - Run `python3 scripts/sync-codex-skills.py` after any skill modification to regenerate Codex-compatible versions. - Use the `--check` flag to verify synchronization status without writing files. - Generated files contain provenance headers citing their source (e.g., `"Source: skills/wechat-article.md"`). ## Frequently Asked Questions ### Can I edit `codex-skills/*/SKILL.md` files directly? No. According to the compatibility rules in [`AGENTS.md`](https://github.com/xbtlin/ai-berkshire/blob/main/AGENTS.md), these files are auto-generated artifacts. Any manual changes you make to `codex-skills/*/SKILL.md` will be overwritten the next time [`scripts/sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-skills.py) executes. Always modify the corresponding file in `skills/` instead. ### How do I know if my generated skills are out of sync? Run `python3 scripts/sync-codex-skills.py --check`. This command compares the checksums and content of all `skills/*.md` files against their `codex-skills/*/SKILL.md` counterparts. If discrepancies exist, the script lists the specific files that need regeneration without modifying anything on disk. ### What happens if I forget to run the sync script? If you modify `skills/*.md` but don't run the sync script, Codex users will continue using the stale version of the skill stored in `codex-skills/*/SKILL.md`. Claude-Code users will see your changes immediately since they reference the canonical source directly, creating a divergence between the two user experiences until synchronization occurs. ### Where are the compatibility rules documented? The formal contract defining the relationship between these file sets is documented in [`AGENTS.md`](https://github.com/xbtlin/ai-berkshire/blob/main/AGENTS.md) (lines 24-34) in the repository root. This file specifies that `skills/*.md` is the canonical workflow source and mandates running the sync script after any changes to the skills directory.