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

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, which coordinates specialist agents like industry-research.md and 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 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 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 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, which validates valuation metrics and liquidity ratios, and 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, and produces a final markdown report.
5. Output – The completed report is saved under reports/ and can be audited using 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:

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

python3 scripts/sync-codex-skills.py

This command automatically detects macro-trend.md and updates 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:

# 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.
• Agents communicate through shared data files like 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 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 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 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 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. 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.

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