# What Are Skills in the Context of AI-Berkshire? A Complete Guide to Markdown-Based Research Workflows

> Discover what skills mean in AI-Berkshire. Learn how these Markdown-based workflow specifications are executed as slash commands by Claude Code for efficient research.

- Repository: [Xbt Lin/ai-berkshire](https://github.com/xbtlin/ai-berkshire)
- Tags: deep-dive
- Published: 2026-07-01

---

**In AI-Berkshire, a skill is a Markdown-based specification of a research workflow or tool that Claude Code executes as a slash command, stored under `skills/<name>.md`.**

The AI-Berkshire repository by xbtlin implements a unique skill system that turns Markdown files into executable research workflows. Understanding what skills are in the context of AI-Berkshire is essential for analysts who want to automate financial research, data validation, and reporting tasks through Claude Code's slash-command interface.

## How Skills Are Defined and Stored

Every skill lives as a file under the `skills/` directory and follows the pattern `skills/<name>.md`【/cache/repos/github.com/xbtlin/ai-berkshire/main/AGENTS.md#L8-L10】. These Markdown files serve as the **single source of truth** for research workflows. When saved, they automatically register as slash commands in Claude Code, making them immediately available for invocation without additional compilation or deployment steps.

## The Anatomy of an AI-Berkshire Skill

A skill file contains four essential components that bridge human-readable documentation and machine-executable logic:

1. **Header (`# <Title>`)** – The H1 heading becomes the slash-command name that users type to invoke the workflow.

2. **Argument placeholders (`$ARGUMENTS`)** – These tokens allow users to pass parameters (such as stock tickers or company codes) when triggering the command.
3. **Logical sections** – Structured steps describing data collection, validation, analysis, and reporting phases, often using H2/H3 headings and bullet lists.
4. **Embedded commands** – Bash snippets that call shared utilities in the `tools/` directory, such as [`financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/financial_rigor.py) or [`report_audit.py`](https://github.com/xbtlin/ai-berkshire/blob/main/report_audit.py).

## Execution Flow: From Markdown to Action

When a user runs a slash command like `/investment-research AAPL`, Claude Code performs the following operations:

- **Parses** the corresponding [`skills/investment-research.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/investment-research.md) file
- **Substitutes** `$ARGUMENTS` with the provided value (`AAPL`)
- **Extracts** Bash commands and Python tool invocations from fenced code blocks
- **Orchestrates** the required agents (Task, Bash, Python tools) to execute the workflow
- **Returns** the final output as a formatted report

This dual nature makes skills both human-auditable and machine-executable, keeping research logic version-controlled alongside the underlying utilities.

## Concrete Example: The Investment Research Skill

The [`skills/investment-research.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/investment-research.md) file demonstrates a full multi-step analysis pipeline implementing the Buffett-Munger-Duan Yongping-Li Lu four-masters framework:

```markdown

# 投资研究：巴菲特-芒格-段永平-李录 四大师综合分析框架

对 $ARGUMENTS 进行系统化投资研究分析。

## 研究框架

...

### 第一步：数据收集

> **数据源规范**：参见 `skills/financial-data.md`。所有财务数据必须来自两个独立来源...

#### 数据交叉验证（必须执行，使用金融严谨性工具）

...
Step 1 — 市值验算（精确十进制，非浮点）：

```bash
python3 ~/ai-berkshire/tools/financial_rigor.py verify-market-cap \
  --price {股价} --shares {总股本} --reported {报告市值} --currency {币种}

```

```

This file mixes natural-language instructions, structured tables, and executable snippets—exactly what a skill needs to drive an autonomous research run【/cache/repos/github.com/xbtlin/ai-berkshire/main/skills/investment-research.md#L1-L70】.

## Cross-Platform Synchronization

While the `skills/*.md` files serve as the canonical source for Claude Code, AI-Berkshire supports Codex through an automated transformation process. The helper script [`scripts/sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-skills.py) generates full skill packages under `codex-skills/*/SKILL.md` by processing the Markdown definitions【/cache/repos/github.com/xbtlin/ai-berkshire/main/AGENTS.md#L23-L30】. This ensures that workflows defined once in Markdown can operate across different AI agent platforms without manual duplication.

## Key Components and File Paths

Understanding the skill architecture requires familiarity with these core files:

| File | Role |
|------|------|
| [`AGENTS.md`](https://github.com/xbtlin/ai-berkshire/blob/main/AGENTS.md) | Describes project layout and explains that `skills/*.md` are the canonical source for Claude Code commands |
| `skills/*.md` | Concrete skill definitions (e.g., [`investment-research.md`](https://github.com/xbtlin/ai-berkshire/blob/main/investment-research.md)) that form the heart of the workflow system |
| [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py) | Shared Python utility for precise financial calculations used by many skills |
| [`scripts/sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-skills.py) | Generates Codex-compatible skill packages from the Markdown sources |
| `codex-skills/*/SKILL.md` | Auto-generated Codex skill packages derived from the canonical Markdown |

## Summary

- **Skills in AI-Berkshire** are Markdown-based workflow specifications stored in `skills/<name>.md` that function as executable slash commands.
- They combine human-readable instructions with embedded Bash/Python snippets, using `$ARGUMENTS` for parameter substitution.
- The system uses `skills/*.md` as the single source of truth, with [`scripts/sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-skills.py) generating Codex-compatible versions when needed.
- Shared tools like [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py) provide rigorous calculation capabilities that skills invoke via command-line calls.
- This architecture enables version-controlled, auditable research automation that works across Claude Code and Codex platforms.

## Frequently Asked Questions

### What file format do AI-Berkshire skills use?

AI-Berkshire skills use **Markdown** files with specific structural conventions. Each skill resides at `skills/<name>.md`, where the H1 heading becomes the slash-command name and code blocks contain executable Bash or Python commands【/cache/repos/github.com/xbtlin/ai-berkshire/main/AGENTS.md#L8-L10】.

### How do I invoke a skill in AI-Berkshire?

You invoke a skill by typing its slash command in Claude Code followed by any arguments. For example, if you have a skill defined in [`skills/example-analysis.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/example-analysis.md) with the title `# 示例分析`, you would run `/示例分析 AAPL` to execute the workflow on Apple stock, with `AAPL` substituting for `$ARGUMENTS` in the Markdown file.

### Where are skill files located in the repository?

Skill files are located in the `skills/` directory at the repository root. According to the project documentation in [`AGENTS.md`](https://github.com/xbtlin/ai-berkshire/blob/main/AGENTS.md), this directory contains the canonical Markdown definitions that Claude Code uses directly as command sources【/cache/repos/github.com/xbtlin/ai-berkshire/main/AGENTS.md#L8-L10】.

### How do AI-Berkshire skills integrate with Codex?

The repository includes [`scripts/sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-skills.py), which transforms the canonical Markdown skills into full skill packages under `codex-skills/*/SKILL.md`【/cache/repos/github.com/xbtlin/ai-berkshire/main/AGENTS.md#L23-L30】. This allows the same workflow definitions to power both Claude Code (which reads Markdown directly) and Codex (which uses the generated packages).