# What Is the Role of CLAUDE.md in AI-Berkshire? Command Specification and Architecture > Discover CLAUDE.md's crucial role in AI-Berkshire. Understand its command specification and architecture for seamless Claude Code integration and investment-research Skill execution. - Repository: [Xbt Lin/ai-berkshire](https://github.com/xbtlin/ai-berkshire) - Tags: architecture - Published: 2026-07-01 --- **CLAUDE.md serves as the central command-definition document for Claude Code integration in the AI-Berkshire repository, specifying how investment-research Skills are exposed, installed, and executed without containing executable code itself.** The `xbtlin/ai-berkshire` repository provides a collection of Claude Code Skills designed for value-investment research based on the "四大师" framework. At the heart of this integration sits **CLAUDE.md**, a canonical specification file that bridges the gap between the repository's Skill definitions and Claude Code's command interface. This document defines the structural requirements, naming conventions, and operational workflows that enable users to deploy automated investment analysis through natural language commands. ## CLAUDE.md as the Claude Code Command Specification Unlike executable scripts or configuration files written in Python or YAML, **CLAUDE.md** functions as documentation-as-contract. According to the source at [`CLAUDE.md`](https://github.com/xbtlin/ai-berkshire/blob/main/CLAUDE.md) lines 3-6, the file establishes that the repository provides Claude Code Skills for value-investment research grounded in the principles of Buffett, Munger, Duan Yong-ping, and Li Lu. The file acts as the single source of truth for how the Skill suite integrates with Claude Code, guiding developers who modify Skills and end-users who install and run them. It resides in the repository root and is referenced by the installation scripts to validate the correct directory structure before copying files to the Claude Code commands directory. ## Project Structure and Directory Layout **CLAUDE.md** explicitly defines the top-level directory structure that Claude Code expects when installing the Skill suite. As documented at lines 10-13, the file specifies four critical directories: - `skills/` — Contains individual Skill markdown definitions (e.g., [`investment-team.md`](https://github.com/xbtlin/ai-berkshire/blob/main/investment-team.md)) - `tools/` — Houses utility scripts for financial calculations - `reports/` — Destination for generated research outputs - `assets/` — Stores static resources and templates The installation process, automated by [`scripts/install-claude-commands.sh`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/install-claude-commands.sh), copies the contents of `skills/` into `~/.claude/commands/`, making the Skills discoverable by Claude Code. This directory mapping ensures that when users invoke slash commands like `/investment-team`, Claude Code locates the corresponding Skill definition in the local commands directory. ## Report Naming Conventions and Output Standards One of the critical responsibilities of **CLAUDE.md** is enforcing deterministic output paths. Lines 42-55 define the naming conventions that each Skill must follow when writing reports, enabling downstream automation and predictable file locations. For example, when analyzing a company like Tencent (腾讯), the `/investment-team` Skill creates a directory structure under `reports/腾讯/`, populating it with individual perspective files for each "大师" (master investor) and a final synthesis report named `最终报告.md`. This convention allows other tools and users to locate generated reports programmatically without parsing unpredictable output directories. The deterministic paths support the repository's goal of building a searchable, structured investment research archive. ## Skill Execution Rules and Research Principles **CLAUDE.md** establishes the behavioral constraints that govern how Skills operate at runtime. Lines 68-77 outline "objective-first" research principles that every Skill must observe: - **Data-driven analysis** — All conclusions must derive from quantitative and qualitative data rather than pre-existing biases - **No pre-set bias** — Skills must approach each investment thesis with neutral evaluation criteria - **Rigorous verification** — Financial metrics require cross-validation against authoritative sources These rules are enforced through the Skill markdown definitions themselves but are documented centrally in **CLAUDE.md** to ensure Claude Code users understand the operational constraints before invoking commands. ## Installation and Git Workflow The file provides the exact commands required to maintain synchronization between the local Skill installation and the upstream repository. Lines 87-104 specify the Git workflow: ```bash git pull --rebase origin main ``` This pattern ensures that users always have the latest Skill definitions and security updates before running investment analysis. **CLAUDE.md** emphasizes that the repository should remain in sync with upstream to prevent version mismatches between Skill logic and the tools they depend on. Following installation via [`scripts/install-claude-commands.sh`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/install-claude-commands.sh), users can verify their setup by checking that the Skill files appear in `~/.claude/commands/` and match the versions specified in the repository's `skills/` directory. ## Operational Validation with Financial Tools Beyond structural documentation, **CLAUDE.md** references specific validation utilities required for accurate financial analysis. Lines 108-112 direct users to verify market-cap calculations and other critical metrics using [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py) before finalizing reports. For example, when a Skill automatically calculates valuation metrics, users should cross-check with: ```bash python3 tools/financial_rigor.py --ticker 0700.HK --metric market_cap ``` This validation step ensures that the data-driven principles outlined in the execution rules translate into accurate, actionable investment research. After verification, **CLAUDE.md** recommends pushing completed reports back to GitHub to maintain a versioned research archive. ## Summary - **CLAUDE.md** acts as the canonical specification document for Claude Code integration in the `xbtlin/ai-berkshire` repository, defining how Skills are structured and invoked. - The file mandates specific directory layouts (`skills/`, `tools/`, `reports/`, `assets/`) that must be copied to `~/.claude/commands/` for Claude Code discovery. - Deterministic naming conventions (e.g., `reports/{company}/最终报告.md`) enable automated report generation and retrieval. - "Objective-first" research rules require data-driven analysis without pre-set bias, enforced at the Skill level but documented centrally. - Operational workflows include specific Git commands (`git pull --rebase origin main`) for maintaining synchronization and [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py) for financial validation. ## Frequently Asked Questions ### What is the difference between CLAUDE.md and the Skill files in the skills/ directory? **CLAUDE.md** provides the overarching specification for how all Skills integrate with Claude Code, while individual files in `skills/` (such as [`investment-team.md`](https://github.com/xbtlin/ai-berkshire/blob/main/investment-team.md)) contain the specific command definitions and prompts for each research capability. Think of **CLAUDE.md** as the architectural guide and the `skills/` files as the implementation details that Claude Code executes when users type slash commands. ### Does CLAUDE.md contain executable code? No, **CLAUDE.md** contains no executable code. It serves purely as documentation that describes the repository structure, installation procedures, and operational constraints. The actual executable logic resides in [`scripts/install-claude-commands.sh`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/install-claude-commands.sh) for setup and within the Skill definitions under `skills/` that Claude Code interprets at runtime. ### Why does CLAUDE.md specify Git workflow commands? The Git workflow section (lines 87-104) ensures that users maintain synchronized copies of the Skill suite. Since Claude Code Skills may be updated with new financial validation logic or additional "master investor" perspectives, running `git pull --rebase origin main` before installation prevents version conflicts between the Skills and their dependent tools in [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py). ### How does CLAUDE.md enforce the "objective-first" research methodology? While **CLAUDE.md** does not programmatically enforce rules, it documents the "objective-first" principles (lines 68-77) that Skill developers must implement in their command definitions. These principles require data-driven analysis without pre-set bias, and Skill authors reference **CLAUDE.md** when constructing prompts to ensure Claude Code generates investment research according to these constraints rather than generic financial advice.