# Can I Contribute to the AI Berkshire Project? A Complete Guide

> Contribute to the ai-berkshire project by forking the xbtlin/ai-berkshire GitHub repo and submitting pull requests to add skills, financial tools, or docs.

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

---

**Yes, the AI Berkshire project actively accepts contributions through a standard GitHub fork-and-PR workflow, allowing developers to add new skills, enhance financial tooling, or improve documentation.**

The AI Berkshire repository is an open-source research framework that combines Claude Code commands with Codex-compatible skills. Whether you want to extend the investment research capabilities or tighten the financial rigor utilities, the codebase is structured to make contributions straightforward.

## Understanding the AI Berkshire Architecture

Before diving into the contribution workflow, it helps to understand how the repository is organized. The project follows a three-layer architecture that separates human-readable skills from execution logic.

### Skill Layer

The **skill layer** contains human-readable markdown commands that define AI behaviors, such as `/investment-research`. These files live in the `skills/` directory and serve as the "canonical" source of truth. When you contribute here, you are editing the primary documentation that defines how AI agents should behave.

### Agent Layer

The **agent layer** orchestrates parallel AI agents for each skill. Rather than editing complex orchestration code directly, you modify the corresponding skill markdown in `skills/` and run the sync scripts to regenerate the Codex wrappers automatically.

### Tool Layer

The **tool layer** provides precise financial utilities using `decimal.Decimal` arithmetic and cross-validation logic. Found in `tools/` (specifically [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py)), this layer handles the mathematical rigor required for financial analysis.

## How to Contribute to AI Berkshire

The contribution workflow follows the standard GitHub model with additional steps to regenerate Codex artifacts. According to the [`AGENTS.md`](https://github.com/xbtlin/ai-berkshire/blob/main/AGENTS.md) file, you must run sync scripts after editing any `skills/*.md` file to keep generated artifacts current.

### Step-by-Step Contribution Workflow

1. **Fork the repository** on GitHub to create your own copy.
2. **Clone your fork locally** and set up the development environment.
3. **Add or modify source files** in `skills/`, `codex-skills/`, or `tools/`.
4. **Run the sync scripts** to regenerate Codex artifacts:
   - `python3 scripts/sync-codex-skills.py` (required after skill changes)
   - `python3 scripts/sync-codex-prompts.py` (optional, for slash prompts)
5. **Commit your changes** and open a Pull Request targeting the upstream `main` branch.
6. **Wait for CI and review** – maintainers will review and merge approved PRs.

### Practical Example: Adding a New Skill

Here is a complete example of creating a new skill and preparing it for submission:

```bash

# 1️⃣ Fork & clone

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

# 2️⃣ Create a new skill (example)

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

# /my-new-skill — 示例新技能

## 用途

演示如何添加自定义 Skill

## 参数

- `ticker` 代码，例如 AAPL

## 示例调用

/my-new-skill AAPL
EOF

# 3️⃣ Regenerate Codex artifacts

python3 scripts/sync-codex-skills.py   # updates codex‑skills/*/SKILL.md

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

# 4️⃣ Commit & push

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

# 5️⃣ Open a PR on GitHub

# (use the GitHub UI or gh pr create)

```

## Contribution Examples by Layer

Different types of contributions target different parts of the codebase.

### Adding or Modifying Skills

To **add a new skill**, create a markdown file in [`skills/my-new-skill.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/my-new-skill.md), describe the prompt parameters, then run `python3 scripts/sync-codex-skills.py` to generate the Codex package. To **improve an existing skill**, modify files like [`skills/investment-research.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/investment-research.md) to clarify checklists or add constraints, then run the sync script before committing.

### Enhancing Financial Tools

For precision improvements, extend utilities in [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py). For example, you might add a volatility calculator or improve cross-validation logic. Always include unit tests when modifying the tool layer to ensure `decimal.Decimal` calculations remain accurate.

## Key Files for Contributors

Understanding these specific files will help you navigate the codebase effectively:

- **[`README.md`](https://github.com/xbtlin/ai-berkshire/blob/main/README.md)** – Contains installation instructions, quick-start guides, and the contribution overview.
- **[`AGENTS.md`](https://github.com/xbtlin/ai-berkshire/blob/main/AGENTS.md)** – Describes the canonical workflow and explains why you must run sync scripts after editing skill files.
- **`skills/`** – The source directory for all Claude Code commands; edit these markdown files to change AI behavior.
- **[`scripts/sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-skills.py)** – Generates Codex-compatible skill packages from `skills/*.md` files.
- **[`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py)** – Houses precise financial calculations and validation utilities.

## Summary

- **AI Berkshire welcomes contributions** via standard GitHub fork-and-PR workflows.
- **Always run sync scripts** ([`scripts/sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-skills.py)) after modifying any file in `skills/` to regenerate Codex artifacts.
- **Three contribution layers exist**: skills (markdown in `skills/`), agents (generated from skills), and tools (Python in `tools/`).
- **Key documentation** lives in [`README.md`](https://github.com/xbtlin/ai-berkshire/blob/main/README.md) (setup) and [`AGENTS.md`](https://github.com/xbtlin/ai-berkshire/blob/main/AGENTS.md) (workflow requirements).
- **New skills require** both the markdown source creation and synchronization before submitting a PR.

## Frequently Asked Questions

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

No, you do not need special permissions. The repository follows standard open-source practices. Simply fork the repository, make your changes, and submit a Pull Request. The maintainers will review your contribution according to the project's guidelines.

### What happens if I forget to run the sync scripts after editing a skill?

If you modify files in `skills/` but forget to run `python3 scripts/sync-codex-skills.py`, the generated Codex artifacts will become out of sync with the canonical markdown source. The [`AGENTS.md`](https://github.com/xbtlin/ai-berkshire/blob/main/AGENTS.md) documentation explicitly requires running these scripts, so your PR may be rejected or require revision before merging.

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

Yes, the tool layer in [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py) accepts contributions that enhance precision or add validation capabilities. When contributing here, ensure you use `decimal.Decimal` for all arithmetic operations to maintain financial accuracy, and include appropriate unit tests with your changes.

### Where should I start if I want to add a new investment research command?

Start by creating a new markdown file in the `skills/` directory that defines the command syntax, parameters, and AI behavior. Follow the existing format used in [`skills/investment-research.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/investment-research.md), then run [`scripts/sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-skills.py) to generate the necessary Codex wrappers before submitting your PR.