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

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 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.

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

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

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 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, this is a required step in the canonical workflow.

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:

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: Contains installation instructions, quick-start guides, and contribution overview.
• 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: Generates Codex-compatible skill packages from the markdown source files.
• 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.
• Run sync scripts (scripts/sync-codex-skills.py and scripts/sync-codex-prompts.py) after any modification to regenerate Codex artifacts.
• Extend tooling by adding verification functions to 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. 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. For tool modifications in 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. Ensure any new financial utilities use precise decimal.Decimal arithmetic rather than floating-point math.

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