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

> Customize AI Berkshire skills by editing Markdown files in skills/ and regenerating Codex artifacts. Follow this developer guide from xbtlin/ai-berkshire for easy customization.

- Repository: [Xbt Lin/ai-berkshire](https://github.com/xbtlin/ai-berkshire)
- Tags: how-to-guide
- Published: 2026-07-08

---

**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`](https://github.com/xbtlin/ai-berkshire/blob/main/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`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/portfolio-review.md).

The file structure follows a standard pattern:

```markdown

# <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:

```markdown

## 支持输入格式

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

```bash
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`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/risk-heatmap.md)**:

```markdown

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

对 $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**:

```bash
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**:

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

```

**Testing with Claude Code**:

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

```

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

**Committing**:

```bash
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`](https://github.com/xbtlin/ai-berkshire/blob/main/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`](https://github.com/xbtlin/ai-berkshire/blob/main/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`](https://github.com/xbtlin/ai-berkshire/blob/main/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.