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

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), 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 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:

# 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, 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 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. 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 – Contains installation instructions, quick-start guides, and the contribution overview.
• 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 – Generates Codex-compatible skill packages from skills/*.md files.
• 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) 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 (setup) and 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 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 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, then run scripts/sync-codex-skills.py to generate the necessary Codex wrappers before submitting your PR.

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