AI-Berkshire Project Structure: A Three-Layer Framework for Financial Analysis

The ai-berkshire project is organized as a three-layer framework that separates user-facing Skills, multi-agent orchestration, and Python-based financial calculation Tools across distinct directories.

The xbtlin/ai-berkshire repository implements a modular architecture for AI-powered investment research. Understanding the ai-berkshire project structure reveals how it cleanly separates command definitions from execution logic and agent coordination while maintaining precision in financial calculations.

Top-Level Directory Layout

The repository root organizes content into functional directories that support the three-layer design:

• skills/ – Contains canonical markdown definitions of 19 public Skills (Claude Code commands). Each file describes a specific financial analysis operation, its parameters, and expected outputs.
• codex-skills/ – Stores auto-generated Codex skill packages (SKILL.md) derived from the canonical files in skills/. These are produced by scripts/sync-codex-skills.py.
• codex-prompts/ – Optional slash-prompt wrappers that make Codex commands discoverable via the / menu interface.
• tools/ – Python utilities implementing precise financial calculations, data cross-validation, and low-level operations consumed by the Skills layer.
• scripts/ – Helper scripts including installation utilities (install-claude-commands.sh, install-codex-skills.sh) and the synchronization script (sync-codex-skills.py).
• assets/ – SVG and PNG graphics including the architecture diagram (architecture.svg) and team structure visuals.
• data/ – Sample datasets including watchlists, fundamentals, and cross-asset CSVs used by the tool layer.
• reports/ – Real-world research outputs generated by the framework, such as industry funnel reports.
• docs/ – Conceptual documentation and roadmap markdown files.
• AGENTS.md – Detailed compatibility rules between Claude Code and Codex agents.
• README.md – Entry point explaining the overall architecture and quick-start guide.

Three-Layer Architecture Design

The ai-berkshire project structure implements a strict separation of concerns across three functional layers, as documented in README.md and visualized in assets/architecture.svg.

Skill Layer

The Skill layer declares what operation the user wants to perform. These are pure markdown command definitions stored in skills/ that define 19 public operations including:

• /investment-research – Deep fundamental analysis (defined in skills/investment-research.md)
• /quality-screen – Quantitative screening (defined in skills/quality-screen.md)
• /investment-checklist – Multi-security validation

These files serve as the canonical source of truth for both Claude Code and Codex implementations.

Agent Layer

The Agent layer handles how multiple AI agents collaborate. Located in skills/ (for team definitions like skills/investment-team.md and skills/earnings-team.md), this layer implements a "Team Lead" pattern where:

• A Team Lead spawns four independent master-vision agents based on four investment masters
• These agents run in parallel to analyze different aspects of a security
• Results are synthesized into a final consolidated report

This architecture enables parallel processing of complex research tasks while maintaining coherent output.

Tool Layer

The Tool layer supplies the concrete implementation of how analysis is performed. Located in tools/, this layer contains Python modules like tools/financial_rigor.py that implement:

• Exact decimal mathematics for financial calculations
• Market-cap verification algorithms
• Three-scenario valuation models
• Benford's law statistical checks
• Data cross-validation functions

These utilities provide the precise financial rigor required by the Skills and Agents above.

Execution Flow

A typical request flows through the ai-berkshire project structure as follows:

1. User invokes a Skill (e.g., /investment-research 腾讯 or /investment-team 腾讯).
2. The Skill parser (Claude Code or Codex) reads the corresponding markdown file in skills/.
3. For Agent-layer skills, the Team Lead spawns four master-vision agents.
4. Each agent calls Tool layer utilities (e.g., financial_rigor.py functions) for market-cap checks, valuation calculations, and data retrieval.
5. Each agent returns structured JSON fragments; the Team Lead merges these into a final report.
6. The final report is stored under reports/ for future reference.

Installation and Usage

The framework provides installation scripts to deploy skills into the respective client runtime directories:

# Clone the repository

git clone https://github.com/xbtlin/ai-berkshire.git
cd ai-berkshire

# Install Codex skills (auto-generates codex-skills/* via sync-codex-skills.py)

./scripts/install-codex-skills.sh

# Install Claude Code commands

./scripts/install-claude-commands.sh

Command Examples

After installation, invoke skills through the respective clients:

# Lightweight financial data fetch

codex /financial-data AAPL 2024Q1

# Multi-agent research team

codex /investment-team 腾讯

# Screening checklist

codex /investment-checklist 茅台,英伟达,苹果

For Claude Code users:

claude /investment-research SpaceX
claude /news-pulse 腾讯

Both clients ultimately reference the same canonical Skill markdown files in skills/, which invoke Python tools under tools/.

Summary

• The ai-berkshire project structure follows a three-layer framework: Skills (definitions), Agents (orchestration), and Tools (calculations).
• Canonical definitions live in skills/ and feed auto-generated artifacts in codex-skills/ via scripts/sync-codex-skills.py.
• Financial rigor is implemented in Python modules like tools/financial_rigor.py, providing exact decimal math and cross-validation.
• Multi-agent coordination uses a Team Lead pattern spawning four master-vision agents defined in team skills like skills/investment-team.md.
• Installation scripts (install-codex-skills.sh, install-claude-commands.sh) bridge the gap between repository files and runtime command availability.

Frequently Asked Questions

What is the difference between the skills/ and codex-skills/ directories?

The skills/ directory contains the canonical markdown definitions of commands (e.g., skills/investment-research.md), while codex-skills/ contains auto-generated packages specifically formatted for OpenAI Codex consumption. The scripts/sync-codex-skills.py utility transforms the canonical files into Codex-compatible SKILL.md packages.

How do the three layers interact during a research request?

The Skill layer parses the user command, the Agent layer (if invoked) orchestrates parallel analysis by four master-vision agents, and the Tool layer (tools/financial_rigor.py) provides precise calculations. Each layer is independent, allowing the Tool layer to be tested and verified separately from the AI orchestration logic.

Where are the financial calculation utilities located?

Core financial mathematics and validation logic reside in tools/financial_rigor.py. This module handles market-cap verification, three-scenario valuation, Benford's law checks, and cross-validation functions that ensure analytical precision across all Skills.

What is the purpose of the AGENTS.md file?

AGENTS.md documents the compatibility rules between Claude Code and Codex agents, explaining how the canonical skill definitions map to different AI client implementations and detailing the generation process managed by scripts/sync-codex-skills.py.

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