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

> Integrate AI Berkshire into your tools easily. Explore declarative Markdown skills, shell-scriptable agents, and importable Python utilities for seamless AI-driven investment research. Embed AI Berkshire into your custom applic...

- Repository: [Xbt Lin/ai-berkshire](https://github.com/xbtlin/ai-berkshire)
- Tags: how-to-guide
- Published: 2026-06-29

---

**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`](https://github.com/xbtlin/ai-berkshire/blob/main/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`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/install-claude-commands.sh) – copies skill files to Claude Code’s global command folder
- [`scripts/install-codex-skills.sh`](https://github.com/xbtlin/ai-berkshire/blob/main/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`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py) for precise calculations, [`tools/report_audit.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/report_audit.py) for automated validation, and [`tools/xueqiu_scraper.py`](https://github.com/xbtlin/ai-berkshire/blob/main/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:

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

```

Then invoke any skill from automation scripts:

```bash
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`](https://github.com/xbtlin/ai-berkshire/blob/main/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`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py) to cross-check market capitalization with decimal precision:

```python
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`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/xueqiu_scraper.py):

```python
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`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/report_audit.py) into your CI pipeline or Git hooks. The auditor parses Markdown reports, extracts numeric tables, and validates against thresholds:

```bash
./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:

```python
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`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/install-codex-skills.sh) or [`scripts/install-claude-commands.sh`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/install-claude-commands.sh), then invoke via `codex <skill>` or `claude-code <skill>`.
- **Import Python tools** directly from [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py) and [`tools/xueqiu_scraper.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/xueqiu_scraper.py) for financial validation and market data within your applications.
- **Automate validation** by adding [`tools/report_audit.py`](https://github.com/xbtlin/ai-berkshire/blob/main/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`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py) or `fetch_stock` from [`tools/xueqiu_scraper.py`](https://github.com/xbtlin/ai-berkshire/blob/main/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`](https://github.com/xbtlin/ai-berkshire/blob/main/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`](https://github.com/xbtlin/ai-berkshire/blob/main/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.