# How to Contribute to the AI Berkshire Project: A Complete Guide

> Contribute to ai-berkshire by forking the repo modifying skills or tools files and submitting a pull request Learn how to add AI capabilities to Berkshire today

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

---

**You can contribute to the ai-berkshire project by forking the repository, modifying files under `skills/` or `tools/`, running the synchronization scripts to regenerate Codex artifacts, and submitting a pull request targeting the `main` branch.**

The ai-berkshire project is an open-source research framework that combines Claude Code commands with OpenAI Codex skills for financial analysis. Contributing to the ai-berkshire project involves understanding its three-layer architecture and following a specific workflow that keeps generated artifacts synchronized with their markdown source files.

## Understanding the Repository Architecture

The repository is organized into three distinct layers, each offering specific contribution opportunities. Before submitting changes, identify which layer aligns with your contribution:

- **Skill Layer**: Human-readable markdown commands located in `skills/` (e.g., `/investment-research`). These are the canonical source files that define available commands.
- **Agent Layer**: Orchestrates parallel AI agents for each skill. You modify this layer indirectly by editing skill markdown files; the [`scripts/sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-skills.py) script generates the corresponding Codex wrappers.
- **Tool Layer**: Precise financial utilities in `tools/` that use `decimal.Decimal` arithmetic for rigorous calculations. Extend this layer by adding validation utilities or calculation helpers to files like [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py).

## Step-by-Step Contribution Workflow

The contribution process follows standard GitHub practices with additional synchronization steps required for this codebase:

1. **Fork the repository** on GitHub to create your own copy of `xbtlin/ai-berkshire`.

2. **Clone your fork locally** and navigate to the project directory:
   ```bash
   git clone https://github.com/<your-username>/ai-berkshire.git
   cd ai-berkshire
   ```

3. **Set up the development environment** by following the installation instructions in [`README.md`](https://github.com/xbtlin/ai-berkshire/blob/main/README.md), which covers client installation and skill setup.

4. **Add or modify source files** depending on your contribution type:
   - Create new skills in `skills/<skill-name>.md`
   - Update existing skills like [`skills/investment-research.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/investment-research.md)
   - Extend tooling in [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py)

5. **Run the sync scripts** after editing any `skills/*.md` file to regenerate Codex-compatible artifacts, as required by the canonical workflow described in [`AGENTS.md`](https://github.com/xbtlin/ai-berkshire/blob/main/AGENTS.md):
   ```bash
   python3 scripts/sync-codex-skills.py   # Updates codex-skills/*/SKILL.md

   python3 scripts/sync-codex-prompts.py  # Optional: updates slash prompts

   ```

6. **Commit your changes** with clear messages describing the skill addition or tool enhancement.

7. **Open a Pull Request** targeting the upstream `main` branch. Continuous integration will run if configured, after which maintainers will review and merge your contribution.

## Practical Contribution Examples

### Adding a New Skill

To add a custom investment research skill, create a markdown file in the `skills/` directory, then regenerate the artifacts:

```bash

# Create the skill definition

cat > skills/my-new-skill.md <<'EOF'

# /my-new-skill — Custom Analysis Skill

## Purpose

Demonstrates how to add custom investment research capabilities

## Parameters

- `ticker`: Stock symbol, e.g., AAPL

## Example Call

/my-new-skill AAPL
EOF

# Regenerate Codex artifacts (required step)

python3 scripts/sync-codex-skills.py

```

### Improving Financial Tools

To enhance the precision of financial calculations, modify [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py) to add new verification commands using `decimal.Decimal` arithmetic:

```python

# In tools/financial_rigor.py

from decimal import Decimal

def calculate_volatility(prices: list[Decimal]) -> Decimal:
    """Add rigorous volatility calculation with decimal precision."""
    # Implementation here

    pass

```

Always include unit tests when extending the tool layer to maintain the project's financial rigor standards.

## Summary

- **Fork and clone** the `xbtlin/ai-berkshire` repository to begin contributing to the ai-berkshire project.
- **Modify the three layers**: Add skills under `skills/`, adjust agent behavior via sync scripts, or extend tools under `tools/`.
- **Run synchronization scripts** ([`scripts/sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-skills.py)) after editing any markdown files in `skills/` to keep generated artifacts current.
- **Submit pull requests** to the `main` branch following the workflow documented in [`AGENTS.md`](https://github.com/xbtlin/ai-berkshire/blob/main/AGENTS.md) and [`README.md`](https://github.com/xbtlin/ai-berkshire/blob/main/README.md).

## Frequently Asked Questions

### What files should I edit to add a new Claude Code command?

Edit files in the `skills/` directory. These markdown files serve as the canonical source for Claude Code commands. After editing, you must run `python3 scripts/sync-codex-skills.py` to generate the corresponding Codex-compatible packages under `codex-skills/`.

### Why do I need to run the sync scripts after editing skills?

The [`scripts/sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-skills.py) script regenerates the machine-readable Codex artifacts from the human-readable markdown sources. According to [`AGENTS.md`](https://github.com/xbtlin/ai-berkshire/blob/main/AGENTS.md), this synchronization is mandatory to ensure the generated wrappers match the canonical skill definitions, preventing divergence between the source and deployed code.

### Can I contribute financial calculation utilities?

Yes. Add precise calculation functions to [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py) using `decimal.Decimal` for arithmetic operations to avoid floating-point errors. This file contains validation utilities and cross-verification methods that support the skill layer's financial analysis requirements.

### Where can I find the installation instructions for local development?

The [`README.md`](https://github.com/xbtlin/ai-berkshire/blob/main/README.md) file contains comprehensive instructions for installing the client, cloning the repository, and setting up the skills environment. Review this file before attempting to run the sync scripts or modify source code.