# AI Berkshire Architecture Explained: A Three-Layer System for Investment Research

> Discover the three-layer AI Berkshire architecture for investment research. It separates skills, AI agents emulating investors, and financial calculations for reproducible results.

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

---

**AI Berkshire implements a three-layer architecture separating declarative research skills, parallel AI agents that emulate master investors, and rigorous financial calculation tools to ensure reproducible investment research.**

The xbtlin/ai-berkshire repository provides an open-source framework for AI-driven investment research built on a clean architectural separation of concerns. This **AI Berkshire architecture** divides the system into distinct layers that handle user intent, intelligent analysis, and data validation, enabling sophisticated financial research workflows that combine multiple expert perspectives with mathematical rigor.

## The Three-Layer Architecture of AI Berkshire

The AI Berkshire architecture is organized as a vertically integrated stack where each layer has a specific responsibility: defining what to research, performing the analysis through multiple viewpoints, and ensuring numerical accuracy.

### Skill Layer – Declarative Research Entry Points

The **Skill layer** provides 18 markdown-defined research primitives that map user requests to concrete workflows. Located in the `skills/` directory, these declarative entry points include `/investment-research` for full-company deep dives, `/industry-funnel` for stock-screening pipelines, and `/news-pulse` for rapid price-movement attribution.

Each skill is implemented as a standalone markdown file. For example, [`skills/investment-research.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/investment-research.md) defines the full-company deep dive workflow, while [`skills/quality-screen.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/quality-screen.md) implements a seven-rule hard filter for eliminating weak stocks quickly. These skills serve as the primary interface between users and the underlying agent infrastructure.

### Agent Layer – Parallel Master-Investor Perspectives

The **Agent layer** executes research by spawning four parallel agents that simultaneously analyze targets from different master-investor viewpoints. When a skill is invoked, the system instantiates agents representing 段永平 (business model focus), 巴菲特 (moat and margin of safety), 芒格 (inverse thinking), and 李录 (civilization trends).

Each agent performs independent web searches, cross-validates data sources, and challenges assumptions. The `investment-team` skill coordinates these parallel researchers, aggregating their outputs through a "Team Lead" agent that produces a unified structured report containing a "四维评分总表" (four-dimensional scoring table). This multi-agent approach is documented in the README at lines 631-645, which describes how the agents challenge each other to surface blind spots.

### Tool Layer – Financial Rigor and Data Integrity

The **Tool layer** provides precise, reproducible utilities implemented as Python scripts under `tools/`. These utilities guarantee that every calculation meets financial auditing standards by using `decimal.Decimal` for exact arithmetic and implementing cross-source verification.

Key tools include [`financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/financial_rigor.py), which contains `verify-market-cap` for sanity-checking price-times-shares calculations, and `cross-validate` for comparing data points across multiple sources with configurable tolerance thresholds. The [`report_audit.py`](https://github.com/xbtlin/ai-berkshire/blob/main/report_audit.py) utility performs integrity checks on final outputs, while functions like `three-scenario` generate optimistic, base-case, and pessimistic valuation targets, and `benford` analyzes financial tables for statistical anomalies.

## How the Layers Interact in Practice

The interaction between layers follows a clear execution pipeline: the Skill layer receives the user command, the Agent layer performs parallel research utilizing the Tool layer for verification, and the Tool layer ensures all numerical outputs are auditable.

To install and run the system:

```bash

# Clone the repository and install skills

git clone https://github.com/xbtlin/ai-berkshire.git
cd ai-berkshire
./scripts/install-codex-skills.sh

```

Running a single skill launches the full three-layer stack:

```bash

# Execute investment research (triggers agents and tools automatically)

codex /investment-research 腾讯

# Agents verify market cap via financial_rigor before finalizing report

```

For team-based parallel research:

```bash

# Run four simultaneous master-investor analyses

codex /investment-team 美团

# Output includes aggregated findings from all four viewpoints

```

Direct tool usage bypasses the agent layer for specific calculations:

```bash
python3 tools/financial_rigor.py verify-market-cap \
    --price 510 --shares 9.11e9 --reported 4.65e12 --currency HKD

# Returns: ✅ 验证通过, 偏差仅 0.08%

```

## Key Implementation Files

The following source files define the AI Berkshire architecture:

- [`README.md`](https://github.com/xbtlin/ai-berkshire/blob/main/README.md) – High-level documentation and architecture diagrams (lines 571-580 for skills, 631-645 for agent workflow)
- `skills/` – Directory containing 18 markdown skill definitions including [`investment-research.md`](https://github.com/xbtlin/ai-berkshire/blob/main/investment-research.md), [`industry-funnel.md`](https://github.com/xbtlin/ai-berkshire/blob/main/industry-funnel.md), and [`quality-screen.md`](https://github.com/xbtlin/ai-berkshire/blob/main/quality-screen.md)
- [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py) – Core financial calculation utilities with `verify-market-cap` and `cross-validate` functions
- [`tools/report_audit.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/report_audit.py) – Report integrity validation
- `assets/architecture.mmd` – Mermaid source for the architecture visualization
- [`scripts/sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-skills.py) – Synchronization script that generates Codex-compatible packages from markdown sources

## Summary

- AI Berkshire uses a **three-layer architecture**: Skills (declarative interface), Agents (parallel analysis), and Tools (numerical validation).
- The **Skill layer** provides 18 research primitives defined in markdown files under `skills/`.
- The **Agent layer** runs four simultaneous master-investor perspectives (段永平, 巴菲特, 芒格, 李录) coordinated by a Team Lead aggregator.
- The **Tool layer** ensures reproducibility through `decimal.Decimal` calculations in [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py) and automated verification scripts.
- All layers are visualized in `assets/architecture.mmd` and interact through the Codex CLI interface.

## Frequently Asked Questions

### What is the AI Berkshire architecture?

The AI Berkshire architecture is a three-layer system designed for AI-driven investment research. It separates declarative user intents (Skills) from analytical execution (Agents) and numerical validation (Tools), enabling rigorous, reproducible financial analysis that emulates a team of master investors working in parallel.

### How do the four agents in AI Berkshire work?

When a skill is invoked, the system spawns four parallel agents, each adopting the perspective of a different investment master: 段永平 focuses on business models, 巴菲特 on moats and safety margins, 芒格 on inverse thinking, and 李录 on civilization trends. Each agent conducts independent research and challenges the others' findings, with a Team Lead agent synthesizing the results into a unified report.

### What tools ensure data quality in AI Berkshire?

The Tool layer provides Python utilities in [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py) that use `decimal.Decimal` for exact arithmetic. Key functions include `verify-market-cap` for sanity-checking valuations, `cross-validate` for multi-source data verification, and `benford` for detecting statistical anomalies in financial statements, ensuring every report meets audit-grade standards.

### How do I install and run AI Berkshire skills?

Clone the repository from `xbtlin/ai-berkshire`, run [`./scripts/install-codex-skills.sh`](https://github.com/xbtlin/ai-berkshire/blob/main/./scripts/install-codex-skills.sh) to register the 18 markdown skills, then invoke any skill via the Codex CLI using commands like `codex /investment-research <company>` or `codex /investment-team <company>`. The install script automatically syncs the markdown definitions to the Codex-compatible format stored in `codex-skills/`.