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

Integrating key skills into AI Berkshire requires running the sync script at 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 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 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:

# 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:

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

/investment-research 腾讯

Codex CLI:

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:

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:

# 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 entry. You can reuse the sync script to handle this registration automatically.

Key Files and Their Roles

• skills/investment-research.md – Canonical skill definition and source of truth for the investment research capability.
• scripts/sync-codex-skills.py – Sync script that generates Codex skill wrappers from markdown sources.
• codex-skills/investment-research/SKILL.md – Example generated Codex skill file produced by the sync script.
• tools/financial_rigor.py – Financial-rigor helper utilities used by agents to guarantee numeric precision.
• 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 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) 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. 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.

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