# How the Codex-Skills Sync Script Generates SKILL.md from Skill Files > Learn how the codex-skills sync script transforms Claude Command markdown files into Codex SKILL.md artifacts. Discover the process of parsing YAML, injecting metadata, and mapping constructs for seamless integration. - Repository: [Xbt Lin/ai-berkshire](https://github.com/xbtlin/ai-berkshire) - Tags: how-to-guide - Published: 2026-07-26 --- **The [`scripts/sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-skills.py) tool in the ai-berkshire repository transforms Claude Command markdown files in `skills/*.md` into Codex-compatible [`SKILL.md`](https://github.com/xbtlin/ai-berkshire/blob/main/SKILL.md) artifacts by parsing YAML front-matter, injecting adapter metadata, and prepending a conversion note that maps Claude-specific constructs to Codex capabilities.** The **codex-skills sync script** maintains consistency between the repository's Claude-focused workflow documentation and its Codex variants. By treating files in `skills/*.md` as the canonical source, the script ensures that updates to Claude commands automatically propagate to the `codex-skills//SKILL.md` targets without manual duplication. ## Five-Stage Transformation Pipeline The generation process implemented in [`scripts/sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-skills.py) follows a deterministic pipeline, with each stage handled by a specialized helper function. ### Stage 1: Splitting Front-Matter from Body The `split_frontmatter` function (lines 16-22) detects YAML front-matter blocks delimited by `---\n` markers. It returns the header content separately from the document body, handling cases where no front-matter exists by returning `None` for the header. This allows the script to process both annotated and bare markdown sources uniformly. ### Stage 2: Deriving Human-Readable Titles To ensure every skill carries a meaningful identifier, the `first_heading` function (lines 25-30) scans the markdown body for the first level-one heading (`# …`). If the document lacks an H1, the script falls back to the file stem (e.g., `my-skill` from [`my-skill.md`](https://github.com/xbtlin/ai-berkshire/blob/main/my-skill.md)), guaranteeing consistent title extraction regardless of authoring style. ### Stage 3: Building or Preserving Metadata The `metadata_for` function (lines 37-61) constructs the YAML header through a merge strategy: - **Existing front-matter**: Preserved intact, with automatic injection of missing `name` and `description` fields - **New files**: Creates a metadata block containing the file stem as `name` and a synthesized description referencing the original skill title This approach ensures backward compatibility while enforcing that all Codex skills include the required identification fields consumed by the platform. ### Stage 4: Assembling the Codex-Specific Body The `codex_body` function (lines 64-90) prepares the document content by prefixing the original body (minus its front-matter) with a static "## Codex adapter note" section. This note explains how Claude-only concepts such as `Task`, `Agent`, and `WebSearch` map to Codex-compatible actions, referencing guidelines in [`AGENTS.md`](https://github.com/xbtlin/ai-berkshire/blob/main/AGENTS.md) to provide platform-specific context. ### Stage 5: Writing or Verifying Output The `main` function (lines 92-133) orchestrates file operations across two modes: - **Generation mode**: Creates the `codex-skills//` directory and writes the assembled [`SKILL.md`](https://github.com/xbtlin/ai-berkshire/blob/main/SKILL.md) file - **Check mode**: When invoked with `--check`, compares generated content against existing files without writing, exiting with status 1 if stale This dual-mode architecture supports both one-time generation and CI enforcement of documentation freshness. ## Execution Flow in Practice The script iterates over source files using a glob pattern and processes each through the transformation pipeline: ```python # Core iteration logic from scripts/sync-codex-skills.py for source in sorted(CLAUDE_SKILLS.glob("*.md")): source_text = source.read_text() name = source.stem target_dir = CODEX_SKILLS / name # Generate components metadata = metadata_for(name, source.name, source_text) body = codex_body(name, source.name, source_text) content = metadata + body # Write or verify based on mode if args.check: verify_unchanged(target_dir / "SKILL.md", content) else: target_dir.mkdir(parents=True, exist_ok=True) (target_dir / "SKILL.md").write_text(content) ``` Each output path follows the deterministic structure `codex-skills//SKILL.md`, containing the generated YAML header, the adapter explanation, and the original workflow instructions. ## Command-Line Usage Regenerate all Codex skills from the repository root: ```bash python3 scripts/sync-codex-skills.py ``` Validate that generated files match their sources (useful for CI): ```bash python3 scripts/sync-codex-skills.py --check ``` The check mode ensures that any edit to `skills/*.md` without a corresponding regeneration of the Codex variant triggers a build failure, preventing documentation drift. ## Summary - **Single source of truth**: Authors edit only `skills/*.md`; the **codex-skills sync script** automatically derives Codex variants - **Metadata preservation**: The `metadata_for` function maintains existing YAML while injecting required `name` and `description` fields - **Platform bridging**: Static adapter notes generated by `codex_body` clarify Claude-to-Codex conceptual mappings and reference [`AGENTS.md`](https://github.com/xbtlin/ai-berkshire/blob/main/AGENTS.md) - **CI integration**: The `--check` flag supports automated verification, exiting with status 1 when [`SKILL.md`](https://github.com/xbtlin/ai-berkshire/blob/main/SKILL.md) files are stale - **Deterministic output**: Generated files always land in `codex-skills//SKILL.md` with predictable structure derived from the source basename ## Frequently Asked Questions ### What happens if my skill file lacks YAML front-matter? The script handles bare markdown gracefully. The `split_frontmatter` function returns `None` for the header, triggering `metadata_for` to generate a fresh YAML block containing the filename stem as the skill `name` and a default description referencing the document title. Your original content remains intact while gaining the required Codex metadata structure. ### Can I customize the generated SKILL.md files? Direct customization of files in `codex-skills/` is discouraged because the sync script overwrites them on each execution. Instead, modify the source file in `skills/*.md` or update the transformation logic—specifically the `codex_body` function (lines 64-90) if you need to adjust the adapter note template or the `metadata_for` function (lines 37-61) to change YAML field generation. ### How does the --check flag function in CI pipelines? When invoked with `--check`, the script generates the expected content for each skill but performs a read-only comparison against the existing `codex-skills//SKILL.md` file. If the generated text differs from the stored version, the script reports the specific file and exits with status 1. This enables GitHub Actions or similar platforms to fail builds when developers commit changes to `skills/*.md` without synchronizing the Codex outputs. ### Where does the adapter note content originate? The "## Codex adapter note" section comes from static text defined within the `codex_body` function (lines 64-90) of [`scripts/sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-skills.py). This content explains Claude-to-Codex capability mapping and references [`AGENTS.md`](https://github.com/xbtlin/ai-berkshire/blob/main/AGENTS.md) for quality standards. To update the note across all generated skills, modify this function and rerun the sync script to propagate changes to every [`SKILL.md`](https://github.com/xbtlin/ai-berkshire/blob/main/SKILL.md) target.