# How to Implement a Multi-Agent Investment Research Team in ai-berkshire

> Learn to implement the multi-agent investment research team in ai-berkshire. Discover how cooperating agents, markdown skills, and JSON data create a powerful research tool. Get started today.

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

---

**The ai-berkshire repository implements a multi-agent investment research team as a set of cooperating agents defined in markdown skill files, orchestrated through a central Python script, and communicating via shared JSON data assets.**

The ai-berkshire project provides a modular framework for automated investment research by modeling the workflow as a team of specialized AI agents. Each agent encapsulates a specific research function—such as sector analysis, earnings review, or portfolio construction—and collaborates through structured data exchanges. This architecture allows you to implement a multi-agent investment research team using plain markdown prompts and Python utilities without requiring complex code changes.

## Core Architecture Components

The system relies on five key components that define how agents interact and share knowledge.

### Agent Skill Definitions

The `skills/` directory contains markdown files that define each agent's behavior. The primary orchestrator is defined in [`skills/investment-team.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/investment-team.md), which coordinates specialist agents like [`industry-research.md`](https://github.com/xbtlin/ai-berkshire/blob/main/industry-research.md) and [`earnings-review.md`](https://github.com/xbtlin/ai-berkshire/blob/main/earnings-review.md). Each file specifies the prompt template, expected inputs, and output format using a structured markdown syntax.

### Codex Compatibility Layer

To support Codex-based environments, the repository maintains a parallel structure in `codex-prompts/`. The file [`codex-prompts/investment-team.md`](https://github.com/xbtlin/ai-berkshire/blob/main/codex-prompts/investment-team.md) contains auto-generated counterparts of the skill files, ensuring the multi-agent investment research team can operate across different LLM platforms.

### Orchestration Script

The [`scripts/sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-skills.py) script manages the agent ecosystem. It scans the `skills/` directory, detects changes to agent definitions, and regenerates the corresponding Codex prompt files. This guarantees synchronization between the human-readable skill definitions and the machine-executable prompts.

### Shared Data Assets

Agents communicate through JSON and CSV files stored in `data/`. The central [`data/watchlist.json`](https://github.com/xbtlin/ai-berkshire/blob/main/data/watchlist.json) serves as the single source of truth for ticker symbols, while other data assets store fundamentals and fair-value tables. This file-based approach eliminates the need for complex message queues while maintaining state between agent invocations.

### Utility Tools

The `tools/` directory provides reusable Python functions that agents invoke during research. Key utilities include [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py), which validates valuation metrics and liquidity ratios, and [`tools/ashare_data.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/ashare_data.py), which handles market data fetching. These tools perform the non-LLM computational work, ensuring financial calculations remain deterministic and auditable.

## Multi-Agent Workflow

The multi-agent investment research team operates through a five-stage pipeline defined in the repository's orchestration logic.

1. **Initialization** – The user triggers the *investment-team* skill via Claude Code slash command or Codex prompt, loading the orchestration context.
2. **Task Decomposition** – The top-level agent parses the research goal and delegates subtasks to specialist agents (e.g., *industry-research*, *earnings-review*, *portfolio-review*).
3. **Data Exchange** – Each specialist reads required inputs from JSON/CSV data assets, performs calculations using scripts in `tools/`, and writes results back into a shared research bundle.
4. **Synthesis** – The top-level agent aggregates specialist outputs, applies the **financial-rigor** check via [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py), and produces a final markdown report.
5. **Output** – The completed report is saved under `reports/` and can be audited using [`tools/report_audit.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/report_audit.py).

## Implementation Guide

Creating a custom agent requires only markdown editing and synchronization commands.

### Creating a New Specialist Agent

Add a new markdown file to the `skills/` directory to define your agent's capabilities. For example, to create a macro-trend analyst:

```markdown

# File: skills/macro-trend.md

# -------------------------------------------------

# {{#system}}

# You are the Macro Trend Analyst. Use the provided watchlist and

# economic indicators to identify macro‑level drivers of market

# performance for the next quarter.

# {{/system}}

#

# {{#user}}

# Input: {{watchlist}}  # JSON list of tickers

# Output: Summarize key macro trends and list affected sectors.

# {{/user}}

# -------------------------------------------------

```

### Synchronizing with the Orchestration Layer

After creating the skill file, regenerate the Codex-compatible version and integrate it into the team:

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

```

This command automatically detects [`macro-trend.md`](https://github.com/xbtlin/ai-berkshire/blob/main/macro-trend.md) and updates [`codex-prompts/macro-trend.md`](https://github.com/xbtlin/ai-berkshire/blob/main/codex-prompts/macro-trend.md) accordingly.

### Integrating into the Research Team

Reference the new agent in the top-level orchestration file to include it in the workflow:

```markdown

# In skills/investment-team.md (excerpt)

- Run **Macro Trend Analyst** to obtain macro‑level insights.
- Feed those insights into the **Portfolio Review** agent for weighting adjustments.

```

When executed, the workflow invokes the new agent alongside existing specialists, passing data through the shared JSON structures in `data/`.

## Summary

- The ai-berkshire repository implements a multi-agent investment research team using markdown-based skill definitions stored in `skills/` and synchronized via [`scripts/sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-skills.py).
- Agents communicate through shared data files like [`data/watchlist.json`](https://github.com/xbtlin/ai-berkshire/blob/main/data/watchlist.json) rather than direct API calls, ensuring a single source of truth for research data.
- The system separates LLM reasoning (defined in markdown prompts) from computational logic (implemented in [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py) and other Python utilities).
- Adding new research capabilities requires only creating a markdown file in `skills/` and running the synchronization script, with no changes to the core orchestration code required.

## Frequently Asked Questions

### How does the synchronization script maintain consistency across platforms?

The [`scripts/sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-skills.py) script scans the `skills/` directory for markdown files containing agent definitions and automatically generates equivalent prompts in `codex-prompts/`. This ensures that changes to agent behavior in the source skills immediately propagate to Codex-compatible formats, maintaining consistency across Claude Code and Codex environments without manual copying.

### What mechanism allows agents to share data during the research workflow?

Agents exchange information through JSON and CSV files in the `data/` directory, particularly [`data/watchlist.json`](https://github.com/xbtlin/ai-berkshire/blob/main/data/watchlist.json) for ticker symbols and shared research bundles for intermediate results. This file-based architecture acts as a persistent knowledge base that every agent reads from and writes to, eliminating complex inter-process communication while maintaining audit trails.

### Can custom validation logic be added to the research workflow?

Yes, you can extend the validation capabilities by modifying [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py) or adding new Python modules to the `tools/` directory. These utilities are invoked by agents through inline code blocks in their prompts, allowing you to integrate custom financial calculations, back-testing logic, or risk metrics into the multi-agent investment research team without changing the agent prompt definitions.

### What is the difference between the skills and codex-prompts directories?

The `skills/` directory contains the canonical markdown definitions of each agent with human-readable formatting and Claude Code-specific syntax, while `codex-prompts/` contains machine-optimized versions generated by [`scripts/sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-skills.py). The latter strips platform-specific annotations and ensures compatibility with OpenAI Codex, allowing the same multi-agent investment research team to function across different LLM coding assistants.