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

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)
• /investment-team – Multi-agent parallel research team (skills/investment-team.md)
• /industry-funnel – Funnel-style stock-screening pipeline (skills/industry-funnel.md)
• /quality-screen – Quick 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)

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)
• 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 – 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:

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

codex /investment-team 美团

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

Invoke Tool layer utilities directly for standalone verification:

# 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	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	Core financial calculation utilities (Tool layer)
tools/report_audit.py	Report integrity checker used by agents
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 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 and 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 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 utility keeps your local Codex skills synchronized with any updates to the source markdown files.

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