# Architectural Design of the Three-Layer AI System (Skills → Agents → Tools) in AI Berkshire

> Explore AI Berkshire's three-layer architectural design: Skills for user intent, Agents for orchestration, and Tools for computation, enabling reproducible financial analysis.

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

---

**AI Berkshire's three-layer AI system separates user intent (Skills), orchestration logic (Agents), and precise computation (Tools) to deliver reproducible, multi-perspective financial analysis.**

The **xbtlin/ai-berkshire** repository implements a modular three-layer AI architecture that structures complex investment research into discrete, auditable components. By separating declarative user commands from parallel agent orchestration and rigorous financial utilities, the system ensures that every analysis remains both accessible to users and mathematically precise under the hood.

## Overview of the Three-Layer Architecture

The architecture follows a strict separation of concerns across three distinct layers. Each layer handles a specific aspect of the research pipeline, allowing the system to scale from simple queries to complex multi-agent workflows without sacrificing clarity or accuracy.

The layers are:

- **Skill Layer** – declarative entry points that describe *what* analysis is required
- **Agent Layer** – orchestration logic that determines *how* to execute the analysis through parallel specialist agents
- **Tool Layer** – concrete utilities that perform *precise calculations* and data validation

This design guarantees that user-facing interfaces remain simple while the underlying agents perform rigorous, auditable work.

## The Skill Layer: Declarative User Entry Points

The **Skill Layer** serves as the user-facing interface, implemented as markdown command files in the `skills/` directory. These files define 20 curated entry points that map directly to Claude Code commands or Codex skills.

Each skill describes the *intent* of the analysis without specifying implementation details. For example:

- `/investment-research` – triggers deep company research
- `/industry-funnel` – initiates sector-wide screening
- `/quality-screen` – executes fundamental quality filters

According to the repository's README documentation, these markdown files act as the canonical interface description. The [`scripts/sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-skills.py) utility ensures that any changes to these skill definitions propagate automatically to Codex artifacts, maintaining consistency across the system.

## The Agent Layer: Parallel Orchestration and Synthesis

The **Agent Layer** transforms a Skill into an executable multi-agent workflow. When a user invokes a skill like `/investment-research`, the system launches an **Agent Team** rather than executing a single linear process.

The architecture uses a **Team Lead Agent** pattern implemented in files like [`skills/investment-team.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/investment-team.md) and [`skills/earnings-team.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/earnings-team.md). The Team Lead dispatches four specialist agents—referred to in the codebase as the "four masters" (段永平, 巴菲特, 芒格, 李录)—to work in parallel on different analytical perspectives.

Each specialist agent independently queries financial data and returns its own rating. The Team Lead then aggregates these outputs into a unified recommendation. This parallel processing model ensures comprehensive coverage while the aggregation logic maintains decision coherence.

## The Tool Layer: Precise Financial Computation

The **Tool Layer** contains low-level Python modules that guarantee mathematical accuracy and data integrity. Located in the `tools/` directory, these modules handle all heavy computation using `decimal.Decimal` for exact arithmetic, eliminating floating-point errors critical in financial analysis.

Key components include:

- **[`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py)** – Core validation logic for market-cap calculations, valuation metrics, and cross-source verification
- **[`tools/ashare_data.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/ashare_data.py)** – Data retrieval and validation for A-share markets
- **[`tools/twstock_data.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/twstock_data.py)** – Taiwan stock exchange data utilities

These tools enforce that every numeric output meets strict error thresholds (≤0.1 % for market-cap calculations) and remains fully reproducible. By isolating calculation logic here, the Skills and Agents remain declarative and focused on workflow rather than arithmetic precision.

## Execution Flow: How the Three Layers Interact

When a user executes a research command, the layers interact through a strict delegation chain:

1. The **Skill Layer** receives the command (e.g., `/investment-research 腾讯`)
2. The **Agent Layer** launches the investment team, spawning four parallel master agents
3. Each **Agent** invokes the **Tool Layer** for data collection and validation via [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py)
4. The Team Lead aggregates results and returns structured output to the user

You can also bypass the agent orchestration for lightweight tasks by calling tools directly:

```python
from tools.financial_rigor import verify_market_cap

# Validate market cap with precise decimal arithmetic

result = verify_market_cap(
    price=510,
    shares=9.11e9,
    reported=4.65e12,
    currency='HKD'
)

# Returns boolean: True if calculated cap matches reported within 0.1%

```

For CLI usage, the skill commands provide immediate access:

```bash

# Trigger full three-layer pipeline

/investment-research 腾讯

```

Or verify calculations directly:

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

```

## Summary

- **Skills** in `skills/*.md` provide 20 declarative entry points that define *what* analysis to perform without implementation details.
- **Agents** orchestrate parallel workflows through Team Lead patterns in [`skills/investment-team.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/investment-team.md), dispatching four specialist masters to analyze different perspectives simultaneously.
- **Tools** in [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py) enforce rigorous financial logic using `decimal.Decimal` for exact arithmetic and reproducible calculations.
- The [`scripts/sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-skills.py) build script maintains synchronization between the canonical Skill definitions and Codex artifacts.
- This three-layer separation ensures the system remains accessible to users while delivering auditable, precise financial analysis.

## Frequently Asked Questions

### How does the Skill Layer differ from traditional command-line interfaces?

The Skill Layer uses markdown files rather than code to define commands, making the interface self-documenting and version-controllable. Each file in `skills/` describes the analytical intent (the "what") while remaining agnostic to implementation, allowing the underlying Agent and Tool layers to evolve without changing the user interface.

### Why does the Agent Layer use four specific "master" agents?

The four masters (段永平, 巴菲特, 芒格, 李录) represent distinct investment philosophies that analyze targets in parallel. This design ensures comprehensive coverage of value, quality, and growth perspectives. The Team Lead Agent then synthesizes these independent viewpoints into a consensus recommendation, reducing single-perspective bias while maintaining analytical depth.

### What makes the Tool Layer's calculations auditable?

The Tool Layer implements all financial arithmetic using Python's `decimal.Decimal` class instead of floating-point numbers, eliminating rounding errors. Functions like `verify_market_cap` in [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py) perform cross-source verification and return boolean validation results, creating a paper trail where every numeric assertion can be traced back to specific input parameters and calculation logic.

### Can I use the Tool Layer without invoking the full Agent workflow?

Yes, the Tool Layer is designed for independent use. You can import functions directly from [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py) or execute them via CLI arguments. This modularity allows advanced users to perform quick validations or build custom workflows while still leveraging the same rigorous calculation logic used by the full three-layer pipeline.