# How to Integrate Key Skills into the AI Berkshire Project: A Complete Guide

> Learn to integrate key skills into the AI Berkshire project by running the sync script. This guide shows how to generate Codex-compatible wrappers and invoke them for powerful AI integration.

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

---

**Integrating key skills into AI Berkshire** requires running the sync script at [`scripts/sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-skills.py) to generate Codex-compatible wrappers from the markdown skill definitions in `skills/`, then invoking them via Claude Code slash commands or Codex CLI calls.

AI Berkshire is an open-source investment research engine built around self-contained *Skills*—markdown-driven command definitions that compile into runnable Codex or Claude Code commands. Understanding how to integrate these key skills into your workflow allows you to deploy institutional-grade financial analysis directly into your AI assistant.

## Understanding the Three-Layer Skill Architecture

The repository implements a strict separation of concerns across three architectural layers. Each skill follows a standardized flow: **CLI → Skill dispatcher → Agent pool → (search, compute, cross‑validate) → Aggregator → Structured output**.

### The Skill Layer (Markdown Definitions)

The canonical skill definitions reside in the `skills/` directory as markdown files. These files declare the skill name, required arguments, and operational descriptions.

For example, [`skills/investment-research.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/investment-research.md) serves as the source of truth for the investment research capability. When you integrate key skills, you are primarily interacting with these markdown definitions before they are compiled into executable formats.

### The Agent Layer (Parallel AI Processing)

Each skill spawns **four parallel AI agents** that perform distinct analyses:

- **Business model** analysis
- **Valuation** calculations
- **Competitive moat** assessment
- **Risk** evaluation

These agents return structured JSON results that feed into the aggregator logic. The dispatcher and aggregator logic lives in the generated Codex skill wrappers, while the heavy-lifting agents invoke the underlying tooling.

### The Tool Layer (Python Utilities)

Reusable Python utilities guarantee numeric precision and cross-source validation. The file [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py) provides helper functions that agents call to verify calculations like market-cap validations or PE-based valuations.

## Step-by-Step Integration Process

Follow this three-step workflow to integrate key skills into your local environment.

### Step 1: Install the Client and Clone the Repository

Install the appropriate client for your AI assistant, then clone the repository:

```bash

# Claude Code users

npm install -g @anthropic-ai/claude-code

# Codex users (macOS / Linux)

curl -fsSL https://chatgpt.com/codex/install.sh | sh

# Clone the repository

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

```

### Step 2: Generate Skill Packages with the Sync Script

Run the synchronization script to compile the markdown skill definitions into Codex-compatible format:

```bash
python3 scripts/sync-codex-skills.py

```

This script reads the canonical skill source files under `skills/` and creates the Codex-compatible `codex-skills/*/SKILL.md` files. This generation step is essential for the skills to appear as runnable commands in your AI client.

### Step 3: Invoke Skills via CLI

After generation, invoke skills using your preferred interface:

**Claude Code (slash command):**

```text
/investment-research 腾讯

```

**Codex CLI:**

```text
codex investment-research 腾讯

```

## Practical Code Examples for Skill Integration

### Direct Tool Invocation

When extending a skill or building custom workflows, you can invoke the underlying tools directly. This example verifies a market-cap calculation using the financial rigor utility:

```bash
python3 tools/financial_rigor.py verify-market-cap \
  --price 510 --shares 9.11e9 --reported 4.65e12 --currency HKD

```

The tool uses Python's `Decimal` type to ensure numeric precision during financial calculations.

### Creating Custom Skill Wrappers

To add new functionality, create a Python wrapper that imports from the tool layer:

```python

# File: custom_skills/my_new_skill.py

from tools.financial_rigor import verify_valuation

def my_new_skill(ticker: str, target_price: float):
    # Example: validate the target price against a PE-based valuation

    result = verify_valuation(ticker=ticker, target_price=target_price)
    return {"ticker": ticker, "validation": result}

```

After saving the file, register it with Codex by creating a corresponding [`codex-skills/my_new_skill/SKILL.md`](https://github.com/xbtlin/ai-berkshire/blob/main/codex-skills/my_new_skill/SKILL.md) entry. You can reuse the sync script to handle this registration automatically.

## Key Files and Their Roles

- **[`skills/investment-research.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/investment-research.md)** – Canonical skill definition and source of truth for the investment research capability.
- **[`scripts/sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-skills.py)** – Sync script that generates Codex skill wrappers from markdown sources.
- **[`codex-skills/investment-research/SKILL.md`](https://github.com/xbtlin/ai-berkshire/blob/main/codex-skills/investment-research/SKILL.md)** – Example generated Codex skill file produced by the sync script.
- **[`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py)** – Financial-rigor helper utilities used by agents to guarantee numeric precision.
- **[`scripts/install-claude-commands.sh`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/install-claude-commands.sh)** – Installation helper for Claude Code command integration.

## Summary

- **Integrate key skills** by running `python3 scripts/sync-codex-skills.py` to compile markdown definitions into runnable commands.
- The architecture separates concerns into **Skill** (markdown), **Agent** (parallel AI processing), and **Tool** (Python utilities) layers.
- Invoke skills via `/investment-research 腾讯` in Claude Code or `codex investment-research 腾讯` in Codex.
- Extend functionality by importing from [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py) into custom Python wrappers.
- All skill definitions in `skills/` serve as the source of truth, with generated artifacts living in `codex-skills/`.

## Frequently Asked Questions

### How do I add a new skill to the AI Berkshire project?

Create a new markdown file in the `skills/` directory defining the skill name, arguments, and behavior. Run `python3 scripts/sync-codex-skills.py` to generate the Codex-compatible wrapper in `codex-skills/`. The script automatically handles the conversion from markdown definition to executable skill format.

### What is the difference between the skill layer and the tool layer?

The **skill layer** (`skills/*.md`) contains high-level command definitions and workflow orchestration. The **tool layer** ([`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py)) contains low-level Python utilities that perform specific calculations like valuation verification or market-cap validation. Agents in the middle layer call tools while executing skill instructions.

### Can I use AI Berkshire skills without Claude Code or Codex?

Yes, you can invoke the underlying Python tools directly from the command line. For example, `python3 tools/financial_rigor.py verify-market-cap` runs the validation logic independently. However, to access the full four-agent parallel processing and structured aggregation, you need either Claude Code or Codex to dispatch the skill commands.

### Where does the skill dispatcher logic reside?

The dispatcher and aggregator logic lives in the generated Codex skill wrappers created by [`scripts/sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-skills.py). When you run a skill command, the CLI interfaces with these wrappers to spawn the four parallel agents and aggregate their JSON outputs into structured final reports.