How to Contribute Skills to the AI Berkshire Repository: A Complete Guide

Contributing skills to ai-berkshire requires editing the canonical skills/*.md files, opening focused pull requests, and running scripts/sync-codex-skills.py to maintain compatibility with both Claude Code and Codex.

The AI Berkshire project treats all skill files as the single source of truth for AI-powered investment research commands. When contributing skills to ai-berkshire, developers must follow a specific workflow that ensures compatibility across both Claude Code and OpenAI Codex platforms. This guide covers the complete contribution lifecycle based on the repository's official CONTRIBUTING.md and source code structure.

Understanding the Skill Contribution Workflow

Types of Contributions

The repository accepts three distinct contribution types according to the CONTRIBUTING.md guidelines:

• Bug fixes – Address broken prompts, workflow failures, or output formatting issues in existing skills.
• Improvements – Enhance existing skills with tighter analysis, better data cross-validation, or more usable output formats.
• New skill proposals – Require discussing the research scenario via a GitHub issue first to ensure alignment with the project's philosophy and avoid wasted effort.

Step-by-Step Contribution Process

1. Identify Your Contribution Type

Before coding, determine whether you're fixing a bug, improving an existing skill, or proposing a new one. For new skills, you must open an issue describing the research scenario, its boundaries, and why existing skills don't cover the use case. This classification keeps the skill set stable and ensures every change is purposeful.

2. Open an Issue for New Skills

New skill proposals require an issue that outlines the research scenario and justifies the addition. This step guarantees alignment with the project's philosophy before you invest time in development, as specified in CONTRIBUTING.md.

3. Prepare a Focused Pull Request

Each PR should accomplish exactly one thing: add a skill, fix a bug, or update documentation. Include a clear description covering what changed, why it changed, and how you verified it. Run the skill in Claude Code or Codex and attach the results to demonstrate end-to-end functionality. Focused PRs make review faster and keep git history clean.

4. Edit the Canonical Source Files

Always modify files in skills/*.md rather than the generated codex-skills/*/SKILL.md directories. The skills/ directory contains the canonical source of truth, while the codex-skills/ directory is automatically regenerated by the sync script. Direct edits to generated files will be overwritten.

5. Run the Sync Script

After your PR merges, run python3 scripts/sync-codex-skills.py to propagate changes from skills/ to codex-skills/. Use the --check flag to verify synchronization without making changes. This script ensures Codex-compatible skill packages stay in sync with the source definitions.

6. Verify End-to-End Functionality

Test your changes by running the skill in the appropriate client. For Claude Code, use the /<skill> command (e.g., /investment-research 腾讯). For Codex, invoke the skill by name (e.g., investment-research 腾讯). Confirm the output matches expectations before submitting.

7. Maintain Documentation Parity

If your change affects user-visible behavior, update both README.md (Chinese) and README_EN.md (English). The project maintains parallel documentation; mismatches confuse users and reduce accessibility.

Repository Structure and Key Files

Understanding the file architecture is essential for effective contributions.

• skills/*.md – Canonical skill definitions and the single source of truth for all skill logic.
• codex-skills/*/SKILL.md – Generated Codex skill packages. Never edit these directly; they are overwritten by the sync script.
• scripts/sync-codex-skills.py – The synchronization script that propagates changes from skills/ to codex-skills/.
• CONTRIBUTING.md – The complete contribution policy with detailed guidelines.
• README.md and README_EN.md – User-facing documentation that must stay synchronized when skills change.

Verification Commands for Pull Requests

Include these commands in your PR description to demonstrate that your contribution works correctly.

# Clone the repository

git clone https://github.com/xbtlin/ai-berkshire.git
cd ai-berkshire

# Install Claude Code commands (macOS/Linux)

./scripts/install-claude-commands.sh

# Or install Codex skills

./scripts/install-codex-skills.sh

Run the actual skill and paste the output in your PR:

# Claude Code example - replace <skill> with actual command name

/<skill> 腾讯

# Codex example

investment-research 腾讯

Attach the actual output highlighting the fixed bug or new functionality to demonstrate end-to-end verification.

Summary

• Edit only skills/*.md – Never modify generated files in codex-skills/ directly.
• One PR, one purpose – Keep changes focused and include verification results.
• Sync after merge – Run scripts/sync-codex-skills.py to regenerate Codex packages.
• Document both languages – Update README.md and README_EN.md when user-facing behavior changes.
• Verify before submitting – Test skills in both Claude Code (/<skill>) and Codex (skill-name) environments.

Frequently Asked Questions

Can I edit the files in codex-skills/ directly?

No. The codex-skills/*/SKILL.md files are generated automatically by scripts/sync-codex-skills.py. Always edit the canonical source files in skills/*.md instead. Changes to generated files will be overwritten during the next synchronization.

Do I need to open an issue before submitting a new skill?

Yes. New skill proposals require an issue that describes the research scenario, defines its boundaries, and explains why existing skills don't cover the use case. This step ensures alignment with the project's philosophy before you begin development.

How do I verify that my skill contribution works correctly?

Run the skill in the appropriate client and attach the output to your PR. For Claude Code, use /<skill-name> followed by your test parameters. For Codex, invoke the skill by its name directly. Include the actual output showing the fixed bug or new functionality to demonstrate end-to-end compatibility.

What files should I update if my skill change affects user behavior?

Update both README.md (Chinese) and README_EN.md (English) to maintain documentation parity. The project maintains parallel documentation in both languages, and mismatches can confuse users. You should also ensure the canonical skills/*.md file reflects your changes, then run the sync script to update generated files.

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