# AI Berkshire Core Architecture: Understanding the Three-Layer Design (Skill, Agent, Tool)

> Explore the AI Berkshire core architecture with its three layers Skill Agent Tool. Discover how this design generates decision-ready investment research instead of generic AI summaries.

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

---

**AI Berkshire implements a three-layer architecture that separates user-facing skills, multi-agent orchestration, and precision calculation tools to generate decision-ready investment research instead of generic AI summaries.**

The **xbtlin/ai-berkshire** repository structures its investment analysis system as a three-layer architecture documented in the README under **整体架构** and enumerated in the **三层设计哲学** section. This design philosophy cleanly separates what the system does, how it does it, and the utilities it relies on to ensure reproducible, numerically rigorous financial analysis.

## The Three-Layer Architecture of AI Berkshire

### Skill Layer: Entry Points and User Intent

The **Skill layer** abstracts user intent into 19 markdown-defined commands that define *what* analysis the user wants. Located in the `skills/` directory, each skill is a self-contained workflow that can be invoked directly via Claude Code or Codex.

Key skills include:
- `/investment-research` – Deep fundamental analysis of individual stocks
- `/news-pulse` – Real-time sentiment and event monitoring
- `/investment-team` – Multi-agent team orchestration
- `/earnings-team` – Earnings-specific analysis workflows

According to the repository's [`skills/investment-research.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/investment-research.md), these skills act as the primary entry points, presenting a fixed interface that hides the complexity of the underlying agent and tool layers.

### Agent Layer: Team Orchestration and Parallel Processing

The **Agent layer** handles *how* the system executes complex research tasks. When users invoke team-based skills like `/investment-team` or `/earnings-team`, the system instantiates a **Team Lead** that spawns four independent "master-view" agents—representing the four investment masters—each operating in parallel.

As specified in [`skills/investment-team.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/investment-team.md), each agent performs its own data gathering and judgment before the Team Lead aggregates results. This parallelism multiplies research depth and data coverage, ensuring comprehensive analysis from multiple investment perspectives simultaneously.

### Tool Layer: Precision Utilities and Numerical Rigor

The **Tool layer** provides the deterministic infrastructure that guarantees numerical accuracy. Located in [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py), these low-level Python utilities deliver exact arithmetic, cross-source validation, and scenario modeling to avoid "LLM 心算" (mental calculation) errors.

These tools provide:
- Decimal-accurate financial calculations
- Market cap verification across data sources
- PE ratio validation and screening
- Scenario modeling primitives

The tool layer ensures that every numerical claim in the final report is verified against precise calculations rather than generated approximations.

## How the Layers Interact in Practice

The architecture allows users to execute commands at different layers depending on their needs:

**Direct skill invocation** (Skill layer only):

```bash

# Single-workflow analysis without agent orchestration

/investment-research 腾讯

```

**Multi-agent team execution** (Agent layer orchestration):

```bash

# Team Lead spawns four master agents in parallel

/investment-team 美团

```

**Direct tool verification** (Tool layer precision):

```bash

# Verify calculations independently of LLM inference

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

```

**Integrated workflow** (All three layers):

```bash

# Quality-screen skill uses Agent layer for research 

# and Tool layer for precise PE validation

/quality-screen 恒生指数成分股

```

## Key Implementation Files

The three-layer architecture is implemented across these specific files:

- **[`README.md`](https://github.com/xbtlin/ai-berkshire/blob/main/README.md)** – Contains the overall architecture overview and the "三层设计哲学" design philosophy
- **[`skills/investment-research.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/investment-research.md)** – Defines the deep-research skill specifications (Skill layer)
- **[`skills/investment-team.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/investment-team.md)** – Specifies multi-agent team workflows (Agent layer)
- **[`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py)** – Implements precise financial calculation utilities (Tool layer)
- **[`AGENTS.md`](https://github.com/xbtlin/ai-berkshire/blob/main/AGENTS.md)** – Documents the high-level interaction patterns between layers

## Summary

- **AI Berkshire** organizes its codebase into three distinct layers: Skill, Agent, and Tool.
- The **Skill layer** provides 19 markdown-defined entry points that abstract user intent into concrete commands like `/investment-research`.
- The **Agent layer** implements parallel multi-agent workflows where a Team Lead coordinates four independent master agents to multiply research depth.
- The **Tool layer** supplies deterministic Python utilities in [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py) to guarantee decimal-accurate calculations and eliminate LLM numerical hallucinations.
- Together, these layers enable a single command to generate comprehensive, decision-ready investment reports with verified numerical accuracy.

## Frequently Asked Questions

### What is the Skill layer in AI Berkshire?

The Skill layer is the user-facing interface consisting of 19 markdown-defined skills in the `skills/` directory. Each skill, such as `/investment-research` or `/news-pulse`, represents a self-contained workflow that abstracts user intent into a specific analysis task, allowing direct invocation without requiring knowledge of the underlying agent or tool implementations.

### How does the Agent layer handle parallel processing?

According to [`skills/investment-team.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/investment-team.md), the Agent layer activates when invoking team-based skills. The Team Lead spawns four independent "master-view" agents simultaneously, each performing independent data gathering and analysis. The lead then aggregates these parallel results into a unified report, effectively multiplying research coverage while maintaining coordination.

### Why does AI Berkshire separate tools into a dedicated layer?

The Tool layer exists to prevent "LLM 心算" or mental calculation errors common in generative AI systems. By isolating precision utilities like [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py), the system ensures that all financial calculations—including market cap verification, PE ratio checks, and scenario modeling—use deterministic Python arithmetic rather than probabilistic LLM outputs, guaranteeing decimal accuracy in every report.

### Where can I find the implementation of the three-layer architecture?

The architecture is documented in the repository's [`README.md`](https://github.com/xbtlin/ai-berkshire/blob/main/README.md) under the **整体架构** section, with detailed enumeration in the **三层设计哲学** bullet list. Implementation details for each layer reside in `skills/` for the Skill layer, [`skills/investment-team.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/investment-team.md) for Agent layer orchestration, and [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py) for Tool layer utilities, with high-level design patterns described in [`AGENTS.md`](https://github.com/xbtlin/ai-berkshire/blob/main/AGENTS.md).