How Skill Layer Prompts Are Structured for Claude Code and Codex Compatibility

AI Berkshire implements a three-layer prompt architecture that maintains a single source of truth in skills/*.md while generating compatibility wrappers for Codex in codex-skills/*/SKILL.md and entry-point prompts in codex-prompts/*.md, synchronized via scripts/sync-codex-skills.py.

The AI Berkshire repository (xbtlin/ai-berkshire) solves cross-platform AI workflow compatibility by structuring Skill Layer prompts into a maintainable, three-tier system. This design allows identical agent workflows to run natively in Claude Code through direct markdown interpretation while simultaneously supporting Codex via auto-generated wrappers, eliminating content duplication and configuration drift between environments.

The Three-Layer Skill Architecture

The repository organizes every skill into distinct layers that separate canonical logic from platform-specific packaging.

Layer 1: Canonical Skill Definitions (skills/*.md)

The foundation resides in the skills/ directory, containing the full descriptive prompts that define agent behavior. Each file represents a complete, standalone workflow.

For example, the WeChat article skill is defined in skills/wechat-article.md. This file contains:

• A descriptive heading and brief summary
• The argument placeholder $ARGUMENTS for dynamic input
• Detailed multi-step workflows specifying research, author, editor, and reader agent orchestration

Claude Code reads these files directly, interpreting the markdown as slash-command definitions without additional processing.

Layer 2: Generated Codex Wrappers (codex-skills/*/SKILL.md)

Codex requires a specific packaging format that the canonical files do not satisfy. The codex-skills/ directory contains thin wrappers automatically regenerated from the canonical sources.

The wrapper at codex-skills/wechat-article/SKILL.md references the original skill file (skills/wechat-article.md) and includes the metadata Codex needs to expose the skill as a loadable command. This layer acts as a bridge, importing the canonical workflow while satisfying Codex's structural requirements.

These wrappers are generated by scripts/sync-codex-skills.py, which copies the canonical markdown into the appropriate format while preserving content integrity.

Layer 3: Slash-Command Entry Points (codex-prompts/*.md)

The final layer provides one-line entry points for Codex slash commands. Files in codex-prompts/ contain minimal YAML frontmatter and a short body that loads the generated skill package.

The entry point at codex-prompts/wechat-article.md uses this structure:

---
description: "AI Berkshire slash entry for 微信公众号文章：作者-编辑-读者三Agent协作."
argument-hint: $ARGUMENTS
---
Use the installed AI Berkshire Codex skill `wechat-article` for this request.
If the skill is not already loaded, read and follow `~/ai-berkshire/codex-skills/wechat-article/SKILL.md`.
User arguments:
$ARGUMENTS

This tells Codex to load the Layer 2 skill wrapper and pass raw arguments through unchanged.

Synchronization and Maintenance

The repository maintains strict consistency rules documented in AGENTS.md. After editing any file in skills/*.md, developers must regenerate the Codex compatibility layers by running:

python3 scripts/sync-codex-skills.py

Optionally, developers can also run python3 scripts/sync-codex-prompts.py to ensure slash-prompt compatibility remains synchronized.

This two-step generation exists because Claude Code can interpret the raw markdown skill definitions directly, while Codex requires the lightweight wrapper structure to load and execute the same logic. The synchronization scripts ensure the single source of truth in skills/ propagates correctly to both target environments.

Runtime Execution Flow

When invoked, the same skill follows different resolution paths depending on the environment.

Claude Code calls the skill directly using the canonical file:

/cl wechat-article 大模型OPD技术解读

Codex resolves through the generated layers:

ai-berkshire wechat-article "大模型OPD技术解读"

Internally, Codex resolves the command to codex-prompts/wechat-article.md (Layer 3), which loads codex-skills/wechat-article/SKILL.md (Layer 2), which then executes the full prompt defined in skills/wechat-article.md (Layer 1).

Summary

• Single source of truth: Canonical skill definitions live in skills/*.md and contain the complete agent workflows.
• Claude Code compatibility: Reads markdown files directly from the skills/ directory without intermediate processing.
• Codex compatibility: Requires generated wrappers in codex-skills/*/SKILL.md and entry points in codex-prompts/*.md.
• Synchronization: scripts/sync-codex-skills.py propagates changes from canonical files to Codex wrappers.
• Governance: AGENTS.md documents the workflow and mandates sync script execution after any skill modification.

Frequently Asked Questions

Why does AI Berkshire use a three-layer structure instead of a single shared file?

Claude Code and Codex interpret prompt files differently. Claude Code can execute raw markdown workflows containing complex agent instructions directly, while Codex requires specific metadata wrappers and entry-point formats. The three-layer structure maintains one canonical definition while automatically generating the platform-specific packaging Codex needs, preventing content duplication.

How do I add a new skill to the repository?

Create the full workflow definition in skills/your-skill-name.md, including the $ARGUMENTS placeholder for user input. Then run python3 scripts/sync-codex-skills.py to generate the Codex wrapper in codex-skills/your-skill-name/SKILL.md. Finally, run python3 scripts/sync-codex-prompts.py to create the entry point in codex-prompts/your-skill-name.md.

What happens if I edit a skill but forget to run the sync script?

The Codex version of the skill will execute stale logic from the previously generated wrapper, while Claude Code will use the updated canonical file. This creates a dangerous drift where the same command behaves differently across platforms. The AGENTS.md file explicitly mandates running the sync scripts after any edits to prevent this inconsistency.

Is the $ARGUMENTS placeholder required in all skill definitions?

Yes. Both Claude Code and the Codex compatibility layers rely on the $ARGUMENTS placeholder to forward user input from the slash command into the skill workflow. The placeholder appears in the canonical skill files and is referenced in the Codex entry-point frontmatter as argument-hint: $ARGUMENTS to ensure proper argument passing.

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