How to Sync Codex Skills After Modifying AI Berkshire Skills Files

Run python3 scripts/sync-codex-skills.py after editing any file in the skills/ directory to regenerate the Codex-compatible skill packages in codex-skills/*/.

AI Berkshire maintains its canonical Claude-Code workflows in the skills/ directory of the xbtlin/ai-berkshire repository. When you modify these markdown source files, you must sync the generated Codex artifacts to keep both interfaces aligned. The repository provides a lightweight Python script that renders the updated markdown into Codex-compatible SKILL.md files.

Why Syncing is Required

AI Berkshire uses a single-source-of-truth architecture. The skills/ directory contains the canonical markdown definitions used by Claude-Code. To support Codex, the repository generates compatible skill packages using scripts/sync-codex-skills.py. According to the project's AGENTS.md file, you must run this script after any modification to skills/*.md files to regenerate the derived artifacts in codex-skills/*/SKILL.md.

Step-by-Step Sync Workflow

1. Edit the Source Skill File

Modify the desired file under skills/, such as skills/investment-research.md.

nano skills/investment-research.md

2. Run the Sync Script

Execute the Python script to regenerate the Codex skill packages.

python3 scripts/sync-codex-skills.py

This reads the updated markdown and writes to codex-skills/<skill-name>/SKILL.md. The script is idempotent, so running it multiple times produces the same result.

3. Verify with the Check Flag

Use the --check flag to confirm everything is synchronized without applying changes.

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

If the output reports All Codex skill files are up-to-date, the sync is complete.

4. Sync Prompt Files (Optional)

If you use the slash-prompt compatibility layer, run the prompt sync script.

python3 scripts/sync-codex-prompts.py

This keeps codex-prompts/ aligned with the new skill definitions.

5. Commit the Changes

Stage both the edited source files and the regenerated artifacts.

git add skills/investment-research.md codex-skills/investment-research/SKILL.md
git commit -m "Update investment-research skill and refresh Codex artifact"
git push

Key Files and Scripts

• skills/*.md – Canonical Claude-Code skill definitions (e.g., skills/investment-research.md).
• scripts/sync-codex-skills.py – Generates Codex-compatible SKILL.md files from the source markdown.
• scripts/sync-codex-prompts.py – (Optional) Generates slash-prompt wrappers for Codex.
• AGENTS.md – Documents the compatibility contract requiring the sync step.
• codex-skills/ – Output directory containing generated Codex skill packages.

Summary

• Modify files in skills/ as the source of truth for AI Berkshire.
• Run python3 scripts/sync-codex-skills.py to regenerate Codex artifacts.
• Use --check to verify sync status without writing files.
• Commit both the source markdown and generated codex-skills/* files to maintain repository consistency.

Frequently Asked Questions

What happens if I forget to run the sync script after editing a skill?

If you commit changes to skills/*.md without running scripts/sync-codex-skills.py, the Codex skill packages will remain out of sync with the Claude-Code source. The AGENTS.md file explicitly warns that this desynchronization can cause Codex to use outdated logic or miss new commands defined in the updated markdown.

Is the sync script safe to run multiple times?

Yes. The scripts/sync-codex-skills.py script is idempotent, meaning you can run it repeatedly without side effects. It will only update files in codex-skills/ if the source markdown has actually changed.

Do I need to install any dependencies to run the sync scripts?

The sync scripts are designed to be lightweight and typically run with standard Python 3. However, you should review the specific imports in scripts/sync-codex-skills.py for any non-standard requirements. The repository also provides scripts/install-codex-skills.sh (and .bat for Windows) as convenience wrappers that handle the sync step.

How do I know if the sync succeeded?

After running the script, check for output lines indicating updated files, such as ✔ Updated codex-skills/investment-research/SKILL.md. You can also run python3 scripts/sync-codex-skills.py --check immediately after; if it reports that all files are up-to-date, the sync was successful.

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