# How to Contribute Skills to the AI Berkshire Repository: A Complete Guide > Learn how to contribute skills to the ai-berkshire repository. Follow simple steps to edit markdown files, open pull requests, and sync your changes for maximum compatibility. - Repository: [Xbt Lin/ai-berkshire](https://github.com/xbtlin/ai-berkshire) - Tags: how-to-guide - Published: 2026-07-07 --- **Contributing skills to ai-berkshire requires editing the canonical `skills/*.md` files, opening focused pull requests, and running [`scripts/sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/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`](https://github.com/xbtlin/ai-berkshire/blob/main/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`](https://github.com/xbtlin/ai-berkshire/blob/main/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`](https://github.com/xbtlin/ai-berkshire/blob/main/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 `/` 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`](https://github.com/xbtlin/ai-berkshire/blob/main/README.md) (Chinese) and [`README_EN.md`](https://github.com/xbtlin/ai-berkshire/blob/main/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`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-skills.py)** – The synchronization script that propagates changes from `skills/` to `codex-skills/`. - **[`CONTRIBUTING.md`](https://github.com/xbtlin/ai-berkshire/blob/main/CONTRIBUTING.md)** – The complete contribution policy with detailed guidelines. - **[`README.md`](https://github.com/xbtlin/ai-berkshire/blob/main/README.md)** and **[`README_EN.md`](https://github.com/xbtlin/ai-berkshire/blob/main/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. ```bash # 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: ```bash # Claude Code example - replace with actual command name / 腾讯 # 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`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-skills.py) to regenerate Codex packages. - **Document both languages** – Update [`README.md`](https://github.com/xbtlin/ai-berkshire/blob/main/README.md) and [`README_EN.md`](https://github.com/xbtlin/ai-berkshire/blob/main/README_EN.md) when user-facing behavior changes. - **Verify before submitting** – Test skills in both Claude Code (`/`) 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`](https://github.com/xbtlin/ai-berkshire/blob/main/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 `/` 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`](https://github.com/xbtlin/ai-berkshire/blob/main/README.md) (Chinese) and [`README_EN.md`](https://github.com/xbtlin/ai-berkshire/blob/main/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.