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

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, 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, 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, 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):

# Single-workflow analysis without agent orchestration

/investment-research 腾讯

Multi-agent team execution (Agent layer orchestration):

# Team Lead spawns four master agents in parallel

/investment-team 美团

Direct tool verification (Tool layer precision):

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

# 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 – Contains the overall architecture overview and the "三层设计哲学" design philosophy
• skills/investment-research.md – Defines the deep-research skill specifications (Skill layer)
• skills/investment-team.md – Specifies multi-agent team workflows (Agent layer)
• tools/financial_rigor.py – Implements precise financial calculation utilities (Tool layer)
• 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 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, 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, 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 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 for Agent layer orchestration, and tools/financial_rigor.py for Tool layer utilities, with high-level design patterns described in AGENTS.md.

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