What Is the Role of CLAUDE.md in AI-Berkshire? Command Specification and Architecture

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

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, 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 before finalizing reports.

For example, when a Skill automatically calculates valuation metrics, users should cross-check with:

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 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) 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 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.

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.

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