# AI Berkshire Architecture: The Three-Layer Entry-Point System Explained > Explore the AI Berkshire architecture and its three-layer entry-point system. Understand how Claude Code, Codex skills, and slash-prompts enable cross-platform AI agent execution. - Repository: [Xbt Lin/ai-berkshire](https://github.com/xbtlin/ai-berkshire) - Tags: architecture - Published: 2026-07-29 --- **AI Berkshire employs a three-tier entry-point architecture that separates human-written Claude Code commands, auto-generated Codex skill packages, and optional slash-prompt compatibility layers to enable cross-platform AI agent execution.** The `xbtlin/ai-berkshire` repository implements a modular **AI Berkshire architecture** designed to support multiple AI platforms through a standardized three-layer system. This design separates source command definitions from platform-specific implementations, allowing seamless operation across both Claude Code and OpenAI Codex environments while maintaining a single source of truth for all skill definitions. ## The Three Layers of AI Berkshire Architecture ### 1. Skill Layer (Source Commands) The **Skill Layer** serves as the canonical source for all user-facing commands. Located in `skills/*.md`, this layer contains human-written markdown files that define slash-commands such as `/investment-team` and `/earnings-team`. According to the repository's [`README_EN.md`](https://github.com/xbtlin/ai-berkshire/blob/main/README_EN.md), each file in this directory represents the ground truth for command behavior, parameters, and execution logic for Claude Code environments. ### 2. Codex-Skill Layer (Generated Packages) The **Codex-Skill Layer** contains auto-generated skill packages located in `codex-skills/*/SKILL.md`. These files are programmatically produced by [`scripts/sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-skills.py), which transforms the canonical Skill Layer definitions into Codex-compatible packages. This layer enables the Codex side of the system to execute the same commands defined in the Skill Layer, ensuring behavioral parity across different AI platforms without manual duplication of logic. ### 3. Codex-Prompt Layer (Compatibility Interface) The **Codex-Prompt Layer** provides optional slash-prompt compatibility through files stored in `codex-prompts/*.md`. Generated by [`scripts/sync-codex-prompts.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-prompts.py), these files bridge the gap for users who prefer the Codex slash-prompt interaction style. As documented in [`README_EN.md`](https://github.com/xbtlin/ai-berkshire/blob/main/README_EN.md), this layer acts as an alternative entry point, offering the same functionality as the Skill Layer but formatted specifically for Codex-specific prompt conventions. ## Layer Synchronization and Build Process The architecture maintains consistency across layers through automated synchronization scripts. When skill definitions change in the `skills/` directory, the build process triggers [`scripts/sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-skills.py) to regenerate the Codex-Skill Layer and [`scripts/sync-codex-prompts.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-prompts.py) to update the Codex-Prompt Layer. This pipeline ensures that modifications to source commands propagate automatically to all platform-specific implementations, preventing drift between the human-readable sources and generated artifacts. ## The Agent Layer (Runtime Execution) Beyond the three entry-point layers, AI Berkshire implements an **Agent Layer** where team-level skills launch multiple "master-perspective" agents in parallel. As implemented in the source code, commands like `/investment-team` initialize a Team Lead that coordinates independent search, judgment, and synthesis operations before producing final output. This runtime layer operates on top of the three-tier architecture, utilizing the skill definitions to orchestrate complex multi-agent workflows. ## Practical Example: Command Resolution When a user invokes the `/investment-team` command, the system resolves the request through all three layers: ```markdown /investment-team ``` 1. The **Skill Layer** resolves the command via [`skills/investment-team.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/investment-team.md) 2. Codex environments access the same logic through [`codex-skills/investment-team/SKILL.md`](https://github.com/xbtlin/ai-berkshire/blob/main/codex-skills/investment-team/SKILL.md) 3. Slash-prompt users interact via [`codex-prompts/investment-team.md`](https://github.com/xbtlin/ai-berkshire/blob/main/codex-prompts/investment-team.md) ```text skills/investment-team.md # Source (Skill Layer) └──> codex-skills/investment-team/SKILL.md # Generated (Codex-Skill Layer) └──> codex-prompts/investment-team.md # Generated (Codex-Prompt Layer) ``` ## Summary - AI Berkshire architecture separates concerns into three distinct entry-point layers: **Skill Layer**, **Codex-Skill Layer**, and **Codex-Prompt Layer**. - Source commands reside in `skills/*.md` as human-written markdown files that serve as the single source of truth. - Automated scripts ([`scripts/sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-skills.py) and [`scripts/sync-codex-prompts.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-prompts.py)) generate platform-specific implementations from the canonical sources. - The **Agent Layer** provides runtime orchestration for multi-agent team commands like `/investment-team` and `/earnings-team`. - This three-tier design ensures cross-platform compatibility while eliminating manual duplication of command logic. ## Frequently Asked Questions ### What is the difference between the Skill Layer and Codex-Skill Layer? The **Skill Layer** contains the original human-written markdown command definitions in `skills/*.md`, serving as the canonical source. The **Codex-Skill Layer** contains machine-generated packages in `codex-skills/*/SKILL.md` created by [`scripts/sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-skills.py), specifically formatted for OpenAI Codex execution environments while maintaining functional equivalence to the source skills. ### How are the three layers synchronized? Synchronization occurs through Python scripts in the `scripts/` directory. [`scripts/sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-skills.py) generates Codex skill packages from the Skill Layer, while [`scripts/sync-codex-prompts.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-prompts.py) creates compatibility prompts for the Codex-Prompt Layer. These automation scripts ensure that updates to source skills automatically propagate to all dependent layers without manual intervention. ### What is the Agent Layer in AI Berkshire? The **Agent Layer** is a runtime execution environment that operates above the three entry-point layers. It manages team-level skills by launching parallel "master-perspective" agents under a Team Lead coordinator, enabling independent search and synthesis operations for complex commands. This layer implements the actual execution logic defined in the skill files. ### Where are the skill definitions stored? Skill definitions are stored in the `skills/` directory as markdown files (`*.md`). These files define slash-commands and their behavior according to the repository's [`README_EN.md`](https://github.com/xbtlin/ai-berkshire/blob/main/README_EN.md), serving as the single source of truth from which both the Codex-Skill Layer and Codex-Prompt Layer are generated.