AI Berkshire Architecture: The Three-Layer Entry-Point System Explained

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, 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, 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, these files bridge the gap for users who prefer the Codex slash-prompt interaction style. As documented in 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 to regenerate the Codex-Skill Layer and 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:

/investment-team

1. The Skill Layer resolves the command via skills/investment-team.md
2. Codex environments access the same logic through codex-skills/investment-team/SKILL.md
3. Slash-prompt users interact via codex-prompts/investment-team.md

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 and 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, 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 generates Codex skill packages from the Skill Layer, while 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, serving as the single source of truth from which both the Codex-Skill Layer and Codex-Prompt Layer are generated.

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