# AI-Berkshire Project Structure: A Three-Layer Framework for Financial Analysis

> Explore the AI-Berkshire project structure. Discover its three-layer framework for financial analysis, separating Skills, orchestration, and Tools for efficient development.

- Repository: [Xbt Lin/ai-berkshire](https://github.com/xbtlin/ai-berkshire)
- Tags: architecture
- Published: 2026-07-08

---

**The ai-berkshire project is organized as a three-layer framework that separates user-facing Skills, multi-agent orchestration, and Python-based financial calculation Tools across distinct directories.**

The `xbtlin/ai-berkshire` repository implements a modular architecture for AI-powered investment research. Understanding the ai-berkshire project structure reveals how it cleanly separates command definitions from execution logic and agent coordination while maintaining precision in financial calculations.

## Top-Level Directory Layout

The repository root organizes content into functional directories that support the three-layer design:

- **`skills/`** – Contains canonical markdown definitions of 19 public **Skills** (Claude Code commands). Each file describes a specific financial analysis operation, its parameters, and expected outputs.
- **`codex-skills/`** – Stores auto-generated Codex skill packages ([`SKILL.md`](https://github.com/xbtlin/ai-berkshire/blob/main/SKILL.md)) derived from the canonical files in `skills/`. These are produced by [`scripts/sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-skills.py).
- **`codex-prompts/`** – Optional slash-prompt wrappers that make Codex commands discoverable via the `/` menu interface.
- **`tools/`** – Python utilities implementing **precise financial calculations**, data cross-validation, and low-level operations consumed by the Skills layer.
- **`scripts/`** – Helper scripts including installation utilities ([`install-claude-commands.sh`](https://github.com/xbtlin/ai-berkshire/blob/main/install-claude-commands.sh), [`install-codex-skills.sh`](https://github.com/xbtlin/ai-berkshire/blob/main/install-codex-skills.sh)) and the synchronization script ([`sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/sync-codex-skills.py)).
- **`assets/`** – SVG and PNG graphics including the architecture diagram (`architecture.svg`) and team structure visuals.
- **`data/`** – Sample datasets including watchlists, fundamentals, and cross-asset CSVs used by the tool layer.
- **`reports/`** – Real-world research outputs generated by the framework, such as industry funnel reports.
- **`docs/`** – Conceptual documentation and roadmap markdown files.
- **[`AGENTS.md`](https://github.com/xbtlin/ai-berkshire/blob/main/AGENTS.md)** – Detailed compatibility rules between Claude Code and Codex agents.
- **[`README.md`](https://github.com/xbtlin/ai-berkshire/blob/main/README.md)** – Entry point explaining the overall architecture and quick-start guide.

## Three-Layer Architecture Design

The ai-berkshire project structure implements a strict separation of concerns across three functional layers, as documented in [`README.md`](https://github.com/xbtlin/ai-berkshire/blob/main/README.md) and visualized in `assets/architecture.svg`.

### Skill Layer

The **Skill layer** declares *what* operation the user wants to perform. These are pure markdown command definitions stored in `skills/` that define 19 public operations including:

- `/investment-research` – Deep fundamental analysis (defined in [`skills/investment-research.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/investment-research.md))
- `/quality-screen` – Quantitative screening (defined in [`skills/quality-screen.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/quality-screen.md))
- `/investment-checklist` – Multi-security validation

These files serve as the canonical source of truth for both Claude Code and Codex implementations.

### Agent Layer

The **Agent layer** handles *how* multiple AI agents collaborate. Located in `skills/` (for team definitions like [`skills/investment-team.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/investment-team.md) and [`skills/earnings-team.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/earnings-team.md)), this layer implements a "Team Lead" pattern where:

- A Team Lead spawns four independent master-vision agents based on four investment masters
- These agents run in parallel to analyze different aspects of a security
- Results are synthesized into a final consolidated report

This architecture enables parallel processing of complex research tasks while maintaining coherent output.

### Tool Layer

The **Tool layer** supplies the concrete implementation of *how* analysis is performed. Located in `tools/`, this layer contains Python modules like [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py) that implement:

- Exact decimal mathematics for financial calculations
- Market-cap verification algorithms
- Three-scenario valuation models
- Benford's law statistical checks
- Data cross-validation functions

These utilities provide the precise financial rigor required by the Skills and Agents above.

## Execution Flow

A typical request flows through the ai-berkshire project structure as follows:

1. **User invokes a Skill** (e.g., `/investment-research 腾讯` or `/investment-team 腾讯`).
2. The **Skill parser** (Claude Code or Codex) reads the corresponding markdown file in `skills/`.
3. For Agent-layer skills, the **Team Lead** spawns four master-vision agents.
4. Each agent calls **Tool layer** utilities (e.g., [`financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/financial_rigor.py) functions) for market-cap checks, valuation calculations, and data retrieval.
5. Each agent returns structured JSON fragments; the Team Lead merges these into a final report.
6. The final report is stored under `reports/` for future reference.

## Installation and Usage

The framework provides installation scripts to deploy skills into the respective client runtime directories:

```bash

# Clone the repository

git clone https://github.com/xbtlin/ai-berkshire.git
cd ai-berkshire

# Install Codex skills (auto-generates codex-skills/* via sync-codex-skills.py)

./scripts/install-codex-skills.sh

# Install Claude Code commands

./scripts/install-claude-commands.sh

```

### Command Examples

After installation, invoke skills through the respective clients:

```bash

# Lightweight financial data fetch

codex /financial-data AAPL 2024Q1

# Multi-agent research team

codex /investment-team 腾讯

# Screening checklist

codex /investment-checklist 茅台,英伟达,苹果

```

For Claude Code users:

```bash
claude /investment-research SpaceX
claude /news-pulse 腾讯

```

Both clients ultimately reference the same canonical **Skill markdown** files in `skills/`, which invoke Python tools under `tools/`.

## Summary

- The ai-berkshire project structure follows a **three-layer framework**: Skills (definitions), Agents (orchestration), and Tools (calculations).
- **Canonical definitions** live in `skills/` and feed auto-generated artifacts in `codex-skills/` via [`scripts/sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-skills.py).
- **Financial rigor** is implemented in Python modules like [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py), providing exact decimal math and cross-validation.
- **Multi-agent coordination** uses a Team Lead pattern spawning four master-vision agents defined in team skills like [`skills/investment-team.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/investment-team.md).
- **Installation scripts** ([`install-codex-skills.sh`](https://github.com/xbtlin/ai-berkshire/blob/main/install-codex-skills.sh), [`install-claude-commands.sh`](https://github.com/xbtlin/ai-berkshire/blob/main/install-claude-commands.sh)) bridge the gap between repository files and runtime command availability.

## Frequently Asked Questions

### What is the difference between the `skills/` and `codex-skills/` directories?

The `skills/` directory contains the **canonical markdown definitions** of commands (e.g., [`skills/investment-research.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/investment-research.md)), while `codex-skills/` contains **auto-generated packages** specifically formatted for OpenAI Codex consumption. The [`scripts/sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-skills.py) utility transforms the canonical files into Codex-compatible [`SKILL.md`](https://github.com/xbtlin/ai-berkshire/blob/main/SKILL.md) packages.

### How do the three layers interact during a research request?

The **Skill layer** parses the user command, the **Agent layer** (if invoked) orchestrates parallel analysis by four master-vision agents, and the **Tool layer** ([`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py)) provides precise calculations. Each layer is independent, allowing the Tool layer to be tested and verified separately from the AI orchestration logic.

### Where are the financial calculation utilities located?

Core financial mathematics and validation logic reside in [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py). This module handles market-cap verification, three-scenario valuation, Benford's law checks, and cross-validation functions that ensure analytical precision across all Skills.

### What is the purpose of the [`AGENTS.md`](https://github.com/xbtlin/ai-berkshire/blob/main/AGENTS.md) file?

[`AGENTS.md`](https://github.com/xbtlin/ai-berkshire/blob/main/AGENTS.md) documents the **compatibility rules** between Claude Code and Codex agents, explaining how the canonical skill definitions map to different AI client implementations and detailing the generation process managed by [`scripts/sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-skills.py).