Claude Code vs Codex Usage in AI Berkshire: Key Differences Explained

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 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) 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:

# 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:

# 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:

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 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. 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 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.

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