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

> Contribute to the AI Berkshire project! Fork the repo, add your skills/tools, run sync scripts, and submit a pull request. Get involved today.

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

---

**Yes, you can contribute to the AI Berkshire project by forking the repository, adding skills or tools, running the sync scripts, and submitting a pull request.**

AI Berkshire is an open-source research framework hosted at `xbtlin/ai-berkshire` that combines Claude Code commands with Codex skills. Whether you want to add new investment research capabilities or improve the financial rigor tools, contributing to the AI Berkshire project follows a straightforward GitHub workflow. The repository structure supports contributions across three distinct layers: skills, agents, and tooling.

## Contribution Workflow Overview

The project follows a standard GitHub contribution model. You fork the repository, clone your fork locally, make changes to the relevant source files, regenerate the Codex artifacts using sync scripts, and submit a pull request targeting the `main` branch.

## Repository Architecture for Contributors

The codebase is organized into three architectural layers that define where contributions typically occur:

- **Skill layer**: Human-readable markdown commands located in `skills/` (e.g., `/investment-research`). Add new `.md` files here or edit existing ones.
- **Agent layer**: Orchestrates parallel AI agents for each skill. Modify the corresponding skill markdown files; the sync script generates the Codex wrapper automatically.
- **Tool layer**: Precise financial utilities using `decimal.Decimal` arithmetic. Extend modules like [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py) with new validation functions or calculators.

## Step-by-Step Contribution Guide

### Forking and Setup

Start by creating your own copy of the repository and setting up the local environment.

```bash
git clone https://github.com/<your-username>/ai-berkshire.git
cd ai-berkshire

```

The [`README.md`](https://github.com/xbtlin/ai-berkshire/blob/main/README.md) contains installation instructions for the client and skills.

### Adding or Modifying Skills

New skills are added as markdown files in the `skills/` directory. For example, to create a custom research skill:

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

# /my-new-skill — Example New Skill

## Purpose

Demonstrate how to add a custom skill

## Parameters

- `ticker` code, e.g., AAPL

## Example Invocation

/my-new-skill AAPL
EOF

```

To improve existing capabilities, edit files like [`skills/investment-research.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/investment-research.md) to clarify checklists or refine prompts.

### Running the Sync Scripts

After modifying any file in `skills/`, you must regenerate the Codex artifacts. According to [`AGENTS.md`](https://github.com/xbtlin/ai-berkshire/blob/main/AGENTS.md), this is a required step in the canonical workflow.

```bash
python3 scripts/sync-codex-skills.py   # Updates codex-skills/*/SKILL.md

python3 scripts/sync-codex-prompts.py  # Updates slash prompts (optional)

```

These scripts keep the generated Codex packages synchronized with the canonical markdown source files.

### Submitting Your Changes

Commit your modifications and push them to your fork:

```bash
git add skills/my-new-skill.md scripts/
git commit -m "Add my-new-skill skill"
git push origin main

```

Then open a Pull Request targeting the upstream `main` branch. CI checks will run automatically before maintainers review your submission.

## Key Files Every Contributor Should Know

Understanding these core files helps you navigate the codebase effectively:

- **[`README.md`](https://github.com/xbtlin/ai-berkshire/blob/main/README.md)**: Contains installation instructions, quick-start guides, and contribution overview.
- **[`AGENTS.md`](https://github.com/xbtlin/ai-berkshire/blob/main/AGENTS.md)**: Describes the canonical workflow and explains why you must run the sync script after editing `skills/*.md` files.
- **`skills/`**: The source of truth for all Claude Code commands. These human-readable markdown files are the "canonical" files that drive the system.
- **[`scripts/sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-skills.py)**: Generates Codex-compatible skill packages from the markdown source files.
- **[`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py)**: Houses precise financial calculation utilities and validation logic.

## Summary

- **Fork and clone** the `xbtlin/ai-berkshire` repository to begin contributing.
- **Add skills** by creating new `.md` files in `skills/` or edit existing ones like [`skills/investment-research.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/investment-research.md).
- **Run sync scripts** ([`scripts/sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-skills.py) and [`scripts/sync-codex-prompts.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-prompts.py)) after any modification to regenerate Codex artifacts.
- **Extend tooling** by adding verification functions to [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py) with accompanying unit tests.
- **Submit a PR** targeting the `main` branch after committing your changes.

## Frequently Asked Questions

### Do I need special permissions to contribute to the AI Berkshire project?

No, the project follows the standard open-source GitHub model. Anyone can fork the repository, make changes, and submit a pull request. Maintainers will review your contribution before merging.

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

The `skills/` directory contains the canonical human-readable markdown files that define commands and prompts. The `codex-skills/` directory contains auto-generated artifacts created by [`scripts/sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-skills.py). You should only edit files in `skills/` and let the sync script update `codex-skills/`.

### How do I test my changes before submitting a pull request?

After running the sync scripts, you can install the skills locally following the instructions in [`README.md`](https://github.com/xbtlin/ai-berkshire/blob/main/README.md). For tool modifications in [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py), write and run unit tests to verify your `decimal.Decimal` calculations work correctly.

### Can I contribute improvements to the financial calculation tools?

Yes, the `tools/` directory welcomes enhancements. You can add new verification commands, volatility calculators, or cross-validation utilities to [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py). Ensure any new financial utilities use precise `decimal.Decimal` arithmetic rather than floating-point math.