How to Integrate AI Berkshire with Your Own Tools: A Complete Guide

AI Berkshire exposes three integration layers—declarative Markdown skills, shell-scriptable agents, and importable Python utilities—allowing you to embed AI-driven investment research into CLI workflows, CI pipelines, or custom Python applications.

The xbtlin/ai-berkshire repository is designed as a plug-and-play research framework that bridges AI agents and financial data processing. Whether you need to automate investment reports or validate market data within your existing stack, you can integrate AI Berkshire via command-line calls, Python imports, or CI hooks without refactoring your current architecture.

Understanding the Three-Layer Architecture

The framework is organized into distinct layers that separate workflow definition from execution logic.

Skill Layer (Declarative Workflows)

The skill layer contains .md files under skills/ (e.g., skills/investment-research.md) that define declarative "what to do" workflows. These files are parsed by Claude Code or Codex to expose slash-style commands like /investment-research. The Markdown format makes skills human-readable and version-controllable.

Agent Layer (Orchestration Scripts)

The agent layer manages parallel AI agents via helper scripts in scripts/. These handle installation and orchestration:

• scripts/install-claude-commands.sh – copies skill files to Claude Code’s global command folder
• scripts/install-codex-skills.sh – installs generated skill packages into ~/.codex/skills

Tool Layer (Python Utilities)

The tool layer provides reusable Python modules in tools/ for data-heavy tasks. Key modules include tools/financial_rigor.py for precise calculations, tools/report_audit.py for automated validation, and tools/xueqiu_scraper.py for market data retrieval.

Integration Method 1: Command-Line Invocation

The fastest way to integrate AI Berkshire is through shell scripts or CI pipelines. First, install the skill set once per machine:

git clone https://github.com/xbtlin/ai-berkshire.git
cd ai-berkshire
./scripts/install-codex-skills.sh

Then invoke any skill from automation scripts:

codex investment-research "腾讯" \
  --output /tmp/tencent_report.md \
  --log-level INFO

The codex binary reads the generated skill definition from codex-skills/investment-research/SKILL.md and returns a reproducible Markdown report.

Integration Method 2: Direct Python Imports

For custom Python applications, import the tools package directly to reuse rigor-focused functions without invoking the AI agent layer.

Financial Validation with financial_rigor

Use verify_market_cap in tools/financial_rigor.py to cross-check market capitalization with decimal precision:

from tools.financial_rigor import verify_market_cap

# Example values from your data source

price = 510                # HKD per share

shares = 9.11e9            # total shares outstanding

reported_cap = 4.65e12     # market cap reported by vendor

ok, diff = verify_market_cap(
    price=price,
    shares=shares,
    reported=reported_cap,
    currency="HKD"
)

if ok:
    print(f"✅ Market cap matches within {diff:.2%}")
else:
    print(f"⚠️ Market cap discrepancy: {diff:.2%}")

The function uses decimal.Decimal for exact arithmetic and reports the relative deviation.

Market Data with xueqiu_scraper

Retrieve real-time stock data using fetch_stock from tools/xueqiu_scraper.py:

from tools.xueqiu_scraper import fetch_stock

# Retrieve latest price/PE for Tencent Holdings

data = fetch_stock("HK:0700")
print(f"Price: {data['price']} HKD, PE: {data['pe']}")

The function wraps HTTP logic for the Xueqiu API and returns a normalized dictionary.

Integration Method 3: Automated CI and Pre-Commit Hooks

Enforce data quality by integrating tools/report_audit.py into your CI pipeline or Git hooks. The auditor parses Markdown reports, extracts numeric tables, and validates against thresholds:

./tools/report_audit.py \
  --path reports/AI算力-funnel-20260509.md \
  --threshold 0.01   # fail if any cross-validation error >1%

The script exits with a non-zero status if discrepancies exceed the specified threshold, making it ideal for pre-commit validation or automated quality gates.

Integration Method 4: Programmatic Skill Orchestration

For batch processing, orchestrate multiple skills using Python’s subprocess module:

import subprocess

def run_skill(skill, args):
    cmd = ["codex", skill] + args
    result = subprocess.run(cmd, capture_output=True, text=True, check=True)
    return result.stdout

# Run investment-team research for multiple tickers

for ticker in ["腾讯", "阿里巴巴", "美团"]:
    report = run_skill("investment-team", [ticker])
    with open(f"reports/{ticker}_team.md", "w", encoding="utf-8") as f:
        f.write(report)

This pattern supports daily batch jobs that generate research suites without manual intervention.

Summary

• AI Berkshire (xbtlin/ai-berkshire) provides three integration layers: Markdown skills, shell scripts, and Python utilities.
• Install skills once using scripts/install-codex-skills.sh or scripts/install-claude-commands.sh, then invoke via codex <skill> or claude-code <skill>.
• Import Python tools directly from tools/financial_rigor.py and tools/xueqiu_scraper.py for financial validation and market data within your applications.
• Automate validation by adding tools/report_audit.py to CI pipelines to enforce cross-validation thresholds.
• Batch orchestrate skills using standard subprocess calls to generate reports for multiple tickers programmatically.

Frequently Asked Questions

Can I use AI Berkshire without installing Claude Code or Codex?

Yes. While the skill layer requires an AI client for full workflow execution, the Python utilities in tools/ are standalone modules. You can import verify_market_cap from tools/financial_rigor.py or fetch_stock from tools/xueqiu_scraper.py in any Python environment without the AI agent dependencies.

How does the market cap validation handle currency precision?

The verify_market_cap function in tools/financial_rigor.py uses decimal.Decimal for all arithmetic operations to avoid floating-point errors. It accepts a currency parameter (e.g., "HKD") and returns a tuple containing a boolean validity flag and the relative deviation as a float for threshold comparison.

What file format do the skills use for workflow definitions?

Skills are defined in plain Markdown files stored under skills/ (source) and codex-skills/ (generated). These files use declarative syntax that Claude Code and Codex parse to expose slash commands. Because they are Markdown, you can version them with Git and inspect workflow logic without running the code.

Can I integrate the report auditor into GitHub Actions?

Yes. The tools/report_audit.py script is designed for CI environments. It accepts --path and --threshold arguments and exits with a non-zero status code if validation fails, which will halt GitHub Actions workflows. Configure it to run on pull requests that modify report files to ensure data integrity before merging.

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