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

> Explore the AI Berkshire architecture a robust three-layer system for investment research. Understand its Skills Agents and Tools components to enhance your financial analysis.

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

---

**The AI Berkshire architecture is a three-layer system that separates user research intents (Skills), parallel AI agents (Agents), and financial validation utilities (Tools).**

The **xbtlin/ai-berkshire** repository implements this architecture as a declarative framework for investment research, emulating a multi-analyst team that mirrors the decision-making processes of world-class investors. Each layer operates independently while contributing to a reproducible, auditable research pipeline.

## Three-Layer Architecture Overview

The architecture divides responsibilities into distinct layers: **Skill**, **Agent**, and **Tool**. This separation ensures that user commands remain declarative, analysis remains parallel and multi-perspective, and all numerical outputs meet rigorous financial standards.

The interaction flow begins when a user invokes a Skill, which spawns four parallel Agents, each utilizing specific Tool utilities to validate data before aggregating findings into a final report.

## Skill Layer: Declarative Research Entry Points

The Skill layer defines **18 markdown-based research primitives** that map natural language requests to concrete workflows. These skills serve as the primary interface between users and the system.

### 18 Predefined Research Skills

Each skill is implemented as a markdown file in the `skills/` directory and registered as a Codex-compatible command:

- **`/investment-research`** – Full-company deep dive 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 execution ([`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`** – 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))

Additional skills cover portfolio analysis, thesis tracking, earnings review, private company research, and full-industry chain scans. The complete list is documented in [`README.md`](https://github.com/xbtlin/ai-berkshire/blob/main/README.md) at lines 571-580.

## Agent Layer: Parallel Multi-Perspective Analysis

When a Skill is invoked, the system instantiates **four parallel agents** that simultaneously research the target from distinct master-investor viewpoints.

### Four Master-Investor Perspectives

Each agent adopts a specific investment philosophy:

1. **段永平 (Duan Yongping)** – Focuses on business models and competitive advantages
2. **巴菲特 (Buffett)** – Emphasizes moats and margin of safety
3. **芒格 (Munger)** – Applies inverse thinking and mental models
4. **李录 (Li Lu)** – Analyzes civilization-level trends and macro patterns

These agents execute **independent web searches**, **cross-validate sources**, and **challenge each other's conclusions** before the Team Lead Agent aggregates their outputs into a unified "四维评分总表" (four-dimensional scoring table). This orchestration is documented in [`README.md`](https://github.com/xbtlin/ai-berkshire/blob/main/README.md) at lines 631-645.

## Tool Layer: Financial Rigor and Data Integrity

The Tool layer provides **reproducible Python utilities** that guarantee numerical accuracy and data quality. All financial calculations use `decimal.Decimal` for exact arithmetic to prevent floating-point errors.

### Core Validation Utilities

Located in the `tools/` directory, these scripts perform specific verification tasks:

- **`verify-market-cap`** – Calculates price × shares and compares against reported market capitalization with tolerance checking (implemented in [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py))
- **`cross-validate`** – Compares data points across multiple sources, raising alarms when deviations exceed configured thresholds
- **`three-scenario`** – Generates optimistic, base-case, and pessimistic valuation targets for sensitivity analysis
- **`benford`** – Applies Benford's Law statistical tests to financial tables to detect potential anomalies

The [`tools/report_audit.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/report_audit.py) utility performs automated integrity checks on generated reports, ensuring all numerical claims are traceable to source data.

## How the Layers Interact: A Practical Example

The following command-line workflow demonstrates how the three layers coordinate during a research task:

```bash

# Install skill set (Skill layer registration)

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

```

```bash

# Execute deep research (triggers Agent and Tool layers)

codex /investment-research 腾讯

# Spawns four agents, each verifying data via financial_rigor.py

# Returns structured report with market-cap verification

```

```bash

# Direct Tool layer usage for specific validation

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

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

```

## Key Files and Repository Structure

Understanding the architecture requires familiarity with these specific paths:

- **[`README.md`](https://github.com/xbtlin/ai-berkshire/blob/main/README.md)** – Architecture diagram and high-level documentation (lines 35-46 describe the Tool layer guarantees)
- **`assets/architecture.mmd`** – Mermaid source for the three-layer diagram
- **`skills/`** – Directory containing all 18 markdown skill definitions
- **[`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py)** – Core financial calculation and validation utilities
- **[`tools/report_audit.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/report_audit.py)** – Report integrity verification used by the Team Lead Agent
- **[`scripts/sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-skills.py)** – Synchronization script that keeps `codex-skills/` directory updated from source markdown

## Summary

- **AI Berkshire architecture** separates concerns into three distinct layers: Skills (declarative interface), Agents (parallel analysis), and Tools (validation utilities).
- The **Skill layer** provides 18 markdown-defined research primitives stored in `skills/`, including `/investment-research` and `/industry-funnel`.
- The **Agent layer** runs four simultaneous researchers emulating Duan Yongping, Buffett, Munger, and Li Lu, coordinated by a Team Lead that aggregates outputs.
- The **Tool layer** ensures reproducibility through [`financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/financial_rigor.py) and [`report_audit.py`](https://github.com/xbtlin/ai-berkshire/blob/main/report_audit.py), using `decimal.Decimal` for exact arithmetic and providing utilities like `verify-market-cap` and `benford` analysis.
- All components are traceable in the repository at specific paths, with the architecture visualized in `assets/architecture.mmd`.

## Frequently Asked Questions

### What makes AI Berkshire's three-layer architecture unique?

The architecture explicitly separates **what** the user wants (Skills) from **how** the analysis is performed (Agents) and **how accuracy is guaranteed** (Tools). Unlike monolithic AI systems, this structure allows independent updates to research methodologies, investor personas, and validation algorithms without affecting other layers.

### Which master-investor perspectives do the agents emulate?

The four agents adopt the frameworks of **段永平** (business model focus), **巴菲特** (moat and margin of safety), **芒格** (inverse thinking), and **李录** (civilization-level trends). As implemented in [`README.md`](https://github.com/xbtlin/ai-berkshire/blob/main/README.md) lines 631-645, each agent conducts independent research before the Team Lead synthesizes their findings into a cohesive report.

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

The Tool layer implements **reproducible verification** through Python scripts in `tools/`. Key mechanisms include `verify-market-cap` for sanity-checking valuations, `cross-validate` for multi-source confirmation, and `benford` for statistical anomaly detection. All calculations use `decimal.Decimal` rather than floating-point numbers to prevent precision errors in financial calculations.

### Where are the skill definitions stored in the repository?

Skill definitions reside in the **`skills/`** directory as markdown files (e.g., [`skills/investment-research.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/investment-research.md), [`skills/industry-funnel.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/industry-funnel.md)). These are automatically synchronized to the `codex-skills/` directory via [`scripts/sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-skills.py), making them available as executable commands within the Codex or Claude Code environment.