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

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 or 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 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 file demonstrates a full multi-step analysis pipeline implementing the Buffett-Munger-Duan Yongping-Li Lu four-masters framework:

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

对 $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).

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