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

> Explore the AI Berkshire architecture, a three-layer system for investment research separating skills, agents, and financial tools for reproducible analysis.

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

---

**AI Berkshire implements a three-layer architecture that separates declarative skills, parallel AI agents, and rigorous financial tools to ensure reproducible, auditable investment analysis.**

AI Berkshire is an open-source investment research system designed to emulate a multi-analyst team. The **ai-berkshire architecture** organizes functionality into three distinct layers—Skills, Agents, and Tools—that transform natural language requests into data-driven reports. This design ensures that every research workflow is reproducible, cross-validated, and financially rigorous.

## The Three-Layer Architecture

The repository structures its capabilities into a clean separation of concerns, visualized in `assets/architecture.mmd` and `assets/architecture.png`.

### Skill Layer: Declarative Research Entry Points

The Skill layer defines *what* research task to perform. It exposes **18 markdown-defined skills** that serve as declarative entry points, mapping user requests to concrete research workflows. Each skill is implemented as a markdown file in the `skills/` directory.

Key skills include:

- `/investment-research` – Full-company deep dives using the four-master framework ([`skills/investment-research.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/investment-research.md))
- `/investment-team` – Multi-agent parallel research team ([`skills/investment-team.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/investment-team.md))
- `/industry-funnel` – Funnel-style stock-screening pipeline ([`skills/industry-funnel.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/industry-funnel.md))
- `/quality-screen` – Quick hard-filter applying seven rules to eliminate weak stocks ([`skills/quality-screen.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/quality-screen.md))
- `/news-pulse` – 10-minute price-movement attribution analysis ([`skills/news-pulse.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/news-pulse.md))

These skills act as the user-facing API, allowing researchers to invoke complex workflows through simple commands.

### Agent Layer: Parallel Viewpoint-Driven Analysis

The Agent layer determines *how* the research is performed. When a skill is invoked, the system spawns **four parallel agents**, each adopting the perspective of a different master investor: **段永平** (business model focus), **巴菲特** (moat and margin of safety), **芒格** (inverse thinking), and **李录** (civilization trends).

Each agent conducts independent web searches, validates sources, and challenges the others' conclusions. A "Team Lead" Agent aggregates these parallel outputs into a single structured report containing a "四维评分总表" (four-dimensional scoring table). This multi-agent approach is documented in the README and ensures comprehensive coverage of investment theses.

### Tool Layer: Financial Rigor and Data Integrity

The Tool layer provides the utilities that guarantee numerical accuracy and data integrity. Implemented as Python scripts under `tools/`, these utilities use `decimal.Decimal` for exact arithmetic to avoid floating-point errors.

Core utilities include:

- `verify-market-cap` – Validates price × shares calculations against reported values ([`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py))
- `cross-validate` – Compares data across multiple sources and raises alerts when deviations exceed tolerance
- `three-scenario` – Generates optimistic, base-case, and pessimistic valuation targets
- `benford` – Analyzes financial tables for statistical anomalies indicating data quality issues
- [`report_audit.py`](https://github.com/xbtlin/ai-berkshire/blob/main/report_audit.py) – Verifies report integrity and completeness before final output

These tools are automatically invoked by agents during research, ensuring every calculation is **reproducible and auditable**.

## How the Layers Interact in Practice

The architecture activates when users invoke skills through the Codex client. The Skill layer triggers the Agent layer, which automatically utilizes the Tool layer for verification.

Install the skill set and run a deep research workflow:

```bash

# Clone and install skills (once)

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

# Run single-skill research (triggers all three layers)

codex /investment-research 腾讯

# → Spawns four agents and outputs a structured report with market-cap verification

```

Run parallel team research for comprehensive coverage:

```bash
codex /investment-team 美团

# → Four agents execute simultaneously; Team Lead aggregates into final report

```

Invoke Tool layer utilities directly for standalone verification:

```python

# Verify market cap calculations

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

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

```

## Key Files and Implementation Details

| Path | Role |
|------|------|
| [`README.md`](https://github.com/xbtlin/ai-berkshire/blob/main/README.md) | High-level documentation and architecture diagrams |
| `assets/architecture.mmd` | Mermaid source for the three-layer architecture graphic |
| `skills/` | 18 markdown skill definitions (Skill layer) |
| [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py) | Core financial calculation utilities (Tool layer) |
| [`tools/report_audit.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/report_audit.py) | Report integrity checker used by agents |
| [`scripts/sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-skills.py) | Syncs Codex skill packages with source markdown |
| `codex-skills/` | Generated Codex-compatible skill packages |

The [`scripts/sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-skills.py) utility ensures that changes to markdown skill definitions are automatically propagated to the Codex client, maintaining consistency between source documentation and executable skills.

## Summary

- **AI Berkshire architecture** separates concerns into three distinct layers: Skills (declarative entry points), Agents (parallel research execution), and Tools (financial rigor).
- The **Skill layer** provides 18 markdown-defined research primitives, from investment research to industry funnel screening.
- The **Agent layer** deploys four master-investor perspectives simultaneously, with a Team Lead aggregating divergent viewpoints into unified reports.
- The **Tool layer** guarantees data integrity through exact arithmetic (`decimal.Decimal`), cross-validation, and statistical anomaly detection.
- All three layers are visualized in `assets/architecture.mmd` and interact through the Codex CLI, ensuring reproducible, auditable investment analysis.

## Frequently Asked Questions

### What are the three layers in ai-berkshire architecture?

The ai-berkshire architecture consists of the **Skill layer** (declarative research entry points), the **Agent layer** (parallel AI researchers), and the **Tool layer** (financial calculation utilities). This separation ensures that user intent is cleanly translated into executable research workflows, executed by multiple validating agents, and backed by rigorous numerical verification.

### How do the four master-investor agents work together?

When a skill is invoked, four agents activate simultaneously, each adopting the investment philosophy of a specific master: **段永平** (business model quality), **巴菲特** (economic moats and margin of safety), **芒格** (inverse thinking and mental models), and **李录** (civilization-level trends). They independently research and cross-validate data, then a "Team Lead" Agent synthesizes their findings into a structured report with a four-dimensional scoring matrix.

### What tools ensure data accuracy 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) and [`tools/report_audit.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/report_audit.py) that enforce exact arithmetic using `decimal.Decimal`. Key functions include `verify-market-cap` for sanity-checking valuations, `cross-validate` for multi-source verification, and `benford` for detecting statistical anomalies in financial tables. These tools run automatically during agent research.

### How do I install and run the ai-berkshire skills?

Clone the repository and execute [`./scripts/install-codex-skills.sh`](https://github.com/xbtlin/ai-berkshire/blob/main/./scripts/install-codex-skills.sh) to register all 18 markdown skills with the Codex client. Once installed, invoke any skill via the command line (e.g., `codex /investment-research 腾讯`) to trigger the full three-layer architecture. The [`scripts/sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-skills.py) utility keeps your local Codex skills synchronized with any updates to the source markdown files.