How to Customize Skills in AI Berkshire: A Step-by-Step Developer Guide

To customize skills in AI Berkshire, edit the Markdown files in the skills/ directory, optionally add Python helper utilities under tools/, then regenerate the Codex artifacts by running python3 scripts/sync-codex-skills.py.

The AI Berkshire repository implements investment-research workflows as modular Skills—human-readable command definitions that drive the "four masters" methodology. Each skill is a Markdown file describing a command-style interface (e.g., /portfolio-review). Understanding how to customize skills in AI Berkshire requires working with the three-tier architecture and the synchronization pipeline that bridges Claude Code and the Codex client.

Understand the Three-Tier Architecture

Before modifying any files, recognize how the system separates concerns:

• Skill Layer (skills/*.md): The canonical source for every command. These Markdown files define the $ARGUMENTS placeholder, expected input formats, and high-level workflow steps.
• Agent Layer: Orchestrates parallel agents (e.g., investment-team) for deep research, merging outputs and enforcing methodology constraints.
• Tool Layer (tools/financial_rigor.py): Provides deterministic financial calculations, cross-validation, and scenario analysis used by skills.

When you customize a skill, you primarily edit the Skill Layer, optionally extending the Tool Layer if new calculations are required.

Customize an Existing Skill

1. Locate and Edit the Skill Markdown

All skills reside in skills/. For example, to modify the portfolio review workflow, edit skills/portfolio-review.md.

The file structure follows a standard pattern:

# <Skill Title>

<Short description>

## 设计理念

...

## 执行流程

### 第一步：...

To customize the argument format, locate the section describing input formats (often labeled "支持输入格式" or similar). Modify the $ARGUMENTS placeholder description—this placeholder is automatically substituted by the client with raw user input.

For example, to accept a JSON list of positions instead of plain text:

## 支持输入格式

- JSON 列表，例如：

```json
[
  {"symbol":"腾讯","share":500,"price":480},
  {"symbol":"美团","share":1000,"price":130}
]

• 传统 "持仓30%" 语法仍然保留。

### 2. Add Helper Tools (Optional)

If your customization requires parsing new formats or performing novel calculations, create a utility under `tools/` rather than embedding logic in the Markdown. For example, [`tools/parse_portfolio.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/parse_portfolio.py):

```python

# tools/parse_portfolio.py

import json
from typing import List, Dict

def load_json(text: str) -> List[Dict]:
    """Parse a JSON list of position dicts."""
    return json.loads(text)

if __name__ == "__main__":
    import sys
    print(load_json(sys.argv[1]))

Reference this tool from your skill's workflow description. The skill Markdown describes when to call the tool; the Python module handles how.

3. Regenerate Codex Artifacts

This step is mandatory. The Codex client does not read skills/ directly—it consumes generated files in codex-skills/. Run the synchronization script from the repository root:

python3 scripts/sync-codex-skills.py

The script reads each skills/*.md, adds front-matter metadata (name and description), and writes codex-skills/<skill>/SKILL.md. The generated file includes adapter notes mapping Claude-specific constructs (Task, Agent, WebSearch) to Codex capabilities.

Important: Without re-running this script, the Codex client will serve the old version and your customizations will not be visible.

Create a New Skill from Scratch

To create a completely new command (e.g., /risk-heatmap), follow the same workflow:

1. Create skills/risk-heatmap.md:

# 风险热图：可视化组合风险分布

对 $ARGUMENTS 生成风险热图。

## 支持输入格式

- 持仓列表（同 `portfolio-review`）  
- 可选 `--scenario <scenario>`（`global-recession`、`interest-rate-spike`）

## 设计理念

使用 `tools/financial_rigor.py three-scenario` 计算每只标的在不同宏观情景下的预期回撤，并绘制热图。

## 执行流程

### 第一步：解析持仓

同 `portfolio-review`。

### 第二步：情景回撤计算

对每只标的调用：

```bash
python3 tools/financial_rigor.py three-scenario \
    --symbol $CODEX_SYMBOL \
    --scenario $SCENARIO \
    --output json

第三步：生成热图

使用内置的 matplotlib 绘图函数，将结果写入 reports/risk-heatmap-$(date +%F).png.

第四步：输出报告

返回热图链接（相对路径）与简要文字说明。

2. **Add supporting tools** under `tools/` if needed (e.g., [`tools/heatmap.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/heatmap.py)).

3. **Regenerate artifacts**:

```bash
python3 scripts/sync-codex-skills.py

4. Test the new skill:

codex --prompt "/risk-heatmap" "腾讯30%, 美团20%, 茅台20%, 现金30% --scenario global-recession"

Test and Commit Your Changes

Validate your customizations before committing:

Testing with Codex client:

codex --prompt "/portfolio-review" "$(cat my-portfolio.txt)"

Testing with Claude Code:

/portfolio-review  腾讯30%, 美团20%, 茅台20%, 现金30%

Verify that the output reflects your new argument syntax and that helper scripts execute correctly.

Committing:

git add skills/risk-heatmap.md tools/heatmap.py
git add codex-skills/risk-heatmap/SKILL.md
git commit -m "Add risk-heatmap skill with JSON position support"

Summary

• AI Berkshire skills are defined as Markdown files in skills/*.md, with tools/financial_rigor.py providing deterministic financial calculations.
• Always edit skills/, never the generated codex-skills/ directory directly.
• Mandatory sync step: Run python3 scripts/sync-codex-skills.py to regenerate Codex-compatible artifacts after any Markdown edit.
• Three-tier separation: Keep command definitions in Skills, orchestration in Agents, and precise calculations in Tools.
• Testing: Verify changes using either the Codex client (codex --prompt) or Claude Code (/command) before committing both source and generated files.

Frequently Asked Questions

Do I need to edit files in codex-skills/ directly?

No. The codex-skills/ directory contains auto-generated artifacts. Edit only the source Markdown in skills/, then run scripts/sync-codex-skills.py to regenerate the Codex-compatible versions. The Codex client reads the generated files, while Claude Code can read the original skills/ files directly.

Can I add completely new skills that don't exist in the repository?

Yes. Create a new file following the naming convention skills/<your-skill>.md, populate it with the standard structure (title, description, input format, workflow steps), and run the sync script. The new skill will appear in the Codex client immediately after regeneration and can be invoked via codex --prompt "/your-skill".

What if I need functionality not covered by existing tools?

Extend the Tool Layer. Add a new Python module under tools/ (e.g., tools/your_module.py), import it from your skill's workflow description, and invoke it via python3 tools/your_module.py ... in the execution steps. This maintains the clean separation between skill definitions and implementation logic.

How do I handle different input formats in the same skill?

Update the $ARGUMENTS placeholder description. In the skill's Markdown, explicitly document all supported formats in the "支持输入格式" section. If the format requires parsing logic (like JSON), implement a helper function in tools/ and reference it in the workflow steps. The $ARGUMENTS variable is replaced verbatim with the user's raw input, giving you full control over parsing.

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