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

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)
• /investment-team – Multi-agent parallel research team execution (skills/investment-team.md)
• /industry-funnel – Funnel-style stock-screening pipeline (skills/industry-funnel.md)
• /quality-screen – Hard-filter applying seven rules to eliminate weak stocks (skills/quality-screen.md)
• /news-pulse – 10-minute price-movement attribution analysis (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 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 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)
• 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 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:

# Install skill set (Skill layer registration)

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

# 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

# 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 – 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 – Core financial calculation and validation utilities
• tools/report_audit.py – Report integrity verification used by the Team Lead Agent
• 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 and 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 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, skills/industry-funnel.md). These are automatically synchronized to the codex-skills/ directory via scripts/sync-codex-skills.py, making them available as executable commands within the Codex or Claude Code environment.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}