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

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 defines the full-company deep dive workflow, while 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, 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 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:

# 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:

# 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:

# 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:

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 – 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, industry-funnel.md, and quality-screen.md
• tools/financial_rigor.py – Core financial calculation utilities with verify-market-cap and cross-validate functions
• tools/report_audit.py – Report integrity validation
• assets/architecture.mmd – Mermaid source for the architecture visualization
• 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 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 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 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/.

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