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

> Discover the AI-Berkshire three-layer architecture, separating investor research workflows, AI agents, and financial verification tools for master investor research.

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

---

**AI-Berkshire implements a three-layer architecture that cleanly separates declarative research workflows (Skills), parallel AI agents emulating master investors (Agents), and rigorous financial verification utilities (Tools).**

The `xbtlin/ai-berkshire` repository structures investment research as a reproducible, multi-agent system inspired by the analytical frameworks of Warren Buffett, Charlie Munger, and other value investing masters. This architecture ensures that every research request flows through specialized layers, from high-level intent definition to data verification and final report synthesis.


## The Three-Layer Architecture

At its core, AI-Berkshire is organized into **three distinct layers** that handle *what* the user wants (Skills), *how* the analysis is performed (Agents), and *how* data integrity is guaranteed (Tools). This separation allows for parallel execution, viewpoint diversification, and mathematical rigor in financial calculations.

### Skill Layer: Declarative Research Primitives

The **Skill layer** defines 18 concrete research workflows that act as entry points for user requests. Each skill is implemented as a markdown file in the `skills/` directory, mapping natural language commands to structured research pipelines.

Key skills include:

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

Additional skills cover portfolio analysis, thesis tracking, earnings reviews, industry chain scans, and private company research. According to the repository's README, these skills register as commands in AI coding assistants like Codex or Claude Code.

### Agent Layer: Parallel Master-Investor Viewpoints

When a skill is invoked, the **Agent layer** spawns four parallel "researchers" that independently gather data, validate sources, and produce partial conclusions. Each agent adopts a distinct master-investor perspective:

1. **段永平 (Duan Yongping)** – Focuses on business model quality and moat durability
2. **巴菲特 (Buffett)** – Emphasizes economic moats and margin of safety
3. **芒格 (Munger)** – Applies inverse thinking and mental models
4. **李录 (Li Lu)** – Analyzes through the lens of civilization-level trends

These agents execute **independent web searches**, **cross-validate data** against multiple sources, and **challenge each other's assumptions**. A "Team Lead" Agent then aggregates their outputs into a unified structured report containing a "四维评分总表" (four-dimensional scoring matrix) summarizing each viewpoint.

This parallel architecture is visualized in `assets/architecture.mmd` (Mermaid source) and rendered in `assets/architecture.png`.

### Tool Layer: Financial Rigor and Data Integrity

The **Tool layer** provides precise, reproducible Python utilities that perform financial calculations and data-quality checks. Implemented as scripts under `tools/`, these utilities guarantee that all numerical work is auditable and exact.

Core utilities in [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py) include:

- **`verify-market-cap`** – Sanity-checks market capitalization using price × shares outstanding, with tolerance thresholds
- **`cross-validate`** – Compares a datum across multiple sources and raises alerts if deviation exceeds defined limits
- **`three-scenario`** – Generates optimistic, base-case, and pessimistic valuation targets
- **`benford`** – Applies Benford's Law to detect statistical anomalies in financial tables

All calculations use Python's `decimal.Decimal` to prevent floating-point errors. Additional integrity checkers reside in [`tools/report_audit.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/report_audit.py) and data fetchers in [`tools/ashare_data.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/ashare_data.py).

## How the Layers Interact in Practice

The architecture comes together through command-line interfaces that route user requests through the three layers. Below are practical examples showing the system flow:

Install the skill set (once):

```bash
git clone https://github.com/xbtlin/ai-berkshire.git
cd ai-berkshire
./scripts/install-codex-skills.sh   # registers all markdown skills as Codex skills

```

Run a single-skill deep research (Skill + Agent + Tool layers):

```bash
codex /investment-research 腾讯

# → launches four agents simultaneously

# → includes market-cap verification via financial_rigor.py

# → outputs structured report with Team Lead synthesis

```

Run parallel-team research:

```bash
codex /investment-team 美团

# → four agents execute simultaneously

# → final output contains "四维评分总表" (four-dimensional scoring table)

```

Use the Tool layer directly for verification:

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

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

```

## Key Implementation Files

| Path | Purpose |
|------|---------|
| `skills/` | Directory containing all 18 skill definitions (markdown sources) |
| [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py) | Core financial calculation utilities with Decimal precision |
| [`tools/report_audit.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/report_audit.py) | Report integrity checker automatically invoked by agents |
| `assets/architecture.mmd` | Mermaid source diagram showing layer interactions |
| [`scripts/sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-skills.py) | Synchronization script maintaining `codex-skills/` packages |
| `codex-skills/` | Generated directory containing Codex-compatible skill packages |


## Summary

- **AI-Berkshire architecture** separates concerns into three layers: Skills (declarative workflows), Agents (parallel master-investor viewpoints), and Tools (financial verification).
- **18 markdown-defined skills** in `skills/` provide research primitives ranging from deep-dive analysis to quick quality screens.
- **Four parallel agents** emulate Duan Yongping, Buffett, Munger, and Li Lu, with a Team Lead synthesizing their outputs into unified reports.
- **Python utilities** in [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py) ensure reproducibility using `decimal.Decimal` for exact arithmetic, cross-validation, and statistical anomaly detection.
- The system is designed for integration with AI coding assistants like Codex, with skills auto-generated from markdown sources via [`scripts/sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-skills.py).


## Frequently Asked Questions

### What makes AI-Berkshire different from other investment AI systems?

Unlike monolithic AI tools, AI-Berkshire implements a **multi-agent architecture** where four specialized agents operate independently using distinct investment philosophies. This parallel structure, combined with mandatory tool-layer verification via [`financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/financial_rigor.py), ensures that conclusions are cross-validated and mathematically sound rather than relying on single-model outputs.

### How does the Tool layer ensure data accuracy?

The Tool layer mandates **exact arithmetic** using Python's `decimal.Decimal` instead of floating-point math. Utilities like `verify-market-cap` and `cross-validate` automatically check calculations against source data with configurable tolerance thresholds. The `benford` function provides statistical validation to detect potential data anomalies in financial statements.

### Can I use AI-Berkshire without the Codex client?

While the repository provides `codex-skills/` packages and [`scripts/install-codex-skills.sh`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/install-codex-skills.sh) for Codex integration, the underlying markdown skill definitions in `skills/` and Python tools in `tools/` are platform-agnostic. You can invoke the Python utilities directly or adapt the markdown workflows for Claude Code or other AI assistants that support skill definitions.

### Which file should I modify to add a new investment skill?

Create a new markdown file in the `skills/` directory following the existing structure (see [`skills/investment-research.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/investment-research.md) as a template). After editing, run [`scripts/sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-skills.py) to regenerate the Codex-compatible packages in `codex-skills/`. The architecture automatically picks up new skills from the `skills/` directory during the synchronization process.