# AI Berkshire Skill Migration to Hermes — Reference Notes

## Context

AI Berkshire (https://github.com/xbtlin/ai-berkshire) is a value-investing research framework (16 Claude Code Skills) built around Buffett, Munger, Duan Yongping, and Li Lu's methodologies. It claims ~66% annualized returns.

## Migration Pattern: Claude Code → Hermes Skill

### 1. Format Conversion

Claude Code Skills are plain Markdown. Hermes requires YAML frontmatter:

```yaml
---
name: <skill-name>
description: <short description>
version: 1.0.0
metadata:
  hermes:
    tags: [tag1, tag2]
    category: ai-berkshire/<sub-category>
    config:
      - key: ai_berkshire.tools_path
        description: "financial_rigor.py 路径"
        prompt: "请输入 financial_rigor.py 的完整路径"
        default: "~/.hermes/skills/ai-berkshire/scripts/financial_rigor.py"
---
```

### 2. Body Structure

Convert to Hermes standard sections:
- `## When to Use` — trigger conditions
- `## Procedure` — step-by-step workflow
- `## Pitfalls` — common mistakes and anti-patterns
- `## Verification` — quality gates and exit criteria

### 3. Tool Call Adaptation

| Claude Code | Hermes Equivalent |
|-------------|-------------------|
| `tool_use("bash", ...)` | `terminal` tool |
| `tool_use("web_search", ...)` | `web_search` tool |
| `TaskCreate` / `TeamCreate` | `delegate_task` with `tasks` array |
| `SendMessage` (agent-to-agent) | Subagent returns summary to parent |
| `WebFetch` | `browser_navigate` + `browser_snapshot` |

### 4. Path Adaptation

All paths referencing `~/ai-berkshire/tools/` must be updated to `~/.hermes/skills/ai-berkshire/scripts/`.

### 5. Parallel Agent Pattern

Claude Code uses `TaskCreate` + `run_in_background: true` for parallel agents. In Hermes, use `delegate_task` with `tasks` array (up to 3 concurrent for this user). For 4+ parallel agents, split into two batches or use sequential delegation.

## Directory Mapping

| AI Berkshire File | Hermes Skill Path | Command |
|-------------------|-------------------|---------|
| `skills/investment-research.md` | `ai-berkshire/deep-research/SKILL.md` | `/deep-research` |
| `skills/investment-team.md` | `ai-berkshire/investment-team/SKILL.md` | `/investment-team` |
| `skills/earnings-review.md` | `ai-berkshire/earnings-review/SKILL.md` | `/earnings-review` |
| `skills/news-pulse.md` | `ai-berkshire/news-pulse/SKILL.md` | `/news-pulse` |
| `skills/portfolio-review.md` | `ai-berkshire/portfolio/SKILL.md` | `/portfolio` |
| `skills/dyp-ask.md` | `ai-berkshire/thinking-tools/dyp-ask/SKILL.md` | `/dyp-ask` |
| `skills/financial-data.md` | `ai-berkshire/thinking-tools/financial-data/SKILL.md` | `/financial-data` |
| `tools/financial_rigor.py` | `ai-berkshire/scripts/financial_rigor.py` | — |

## Key Pitfalls Discovered

1. **Claude Code's `TaskCreate`/`TeamCreate` are not native Hermes concepts** — must translate to `delegate_task` with explicit task descriptions. No automatic team lifecycle management (create/delete/shutdown) in Hermes.

2. **Agent-to-agent messaging (`SendMessage`) doesn't exist in Hermes** — subagents return summaries to the parent; the parent synthesizes. No persistent team state.

3. **`$ARGUMENTS` in Claude Code → direct user input in Hermes** — no special variable; just use the user's message as the analysis target.

4. **Config keys in frontmatter** — Hermes uses `metadata.hermes.config` for interactive prompts on first load. The `default` field should use the actual installed path, not the original repo path.

5. **financial_rigor.py paths** — the script hardcodes `~/ai-berkshire/tools/` in some examples. Must search-replace all occurrences when migrating.

6. **Skill name collision** — `investment-research` and `investment-team` are generic names. Use `ai-berkshire/` prefix in category to namespace them.

## Verification Checklist

- [ ] All SKILL.md files have YAML frontmatter with `name`, `description`, `version`
- [ ] All paths updated to `~/.hermes/skills/ai-berkshire/scripts/`
- [ ] `financial_rigor.py` runs correctly with new paths
- [ ] `delegate_task` usage respects max_concurrent_children=3 limit
- [ ] Main entry SKILL.md lists all available sub-commands