Relationship Between `skills/*.md` and `codex-skills/*/SKILL.md` in AI-Berkshire

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 utility automatically transforms these canonical definitions into the codex-skills/<skill-name>/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 (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 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 begins with a YAML frontmatter block that explicitly references its origin. For example, the wechat-article skill generates:

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

vim skills/wechat-article.md

2. Run the synchronization script to regenerate the Codex adapter:

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:

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.
• 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, 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 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 (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.

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