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

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

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:

   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, 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
   • Extend tooling in 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:

   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:

# 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 to add new verification commands using decimal.Decimal arithmetic:

# 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) 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 and 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 script regenerates the machine-readable Codex artifacts from the human-readable markdown sources. According to 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 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 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.

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