# Recommended Structure for a Skill File in ai-berkshire: The Complete Guide

> Learn the recommended structure for an ai-berkshire skill file. Our guide details the 10-section template including headers arguments data collection verification and audit requirements for optimal organization.

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

---

**In ai-berkshire, a skill file is a Markdown document stored in the `skills/` directory that follows a standardized 10-section template including headers, argument placeholders, data collection specifications, verification calls to [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py), and audit requirements.**

The ai-berkshire repository treats skill files as the single source of truth for automated investment research workflows. Each skill is a **Markdown file** that defines a complete analytical pipeline, while the generated Codex versions in `codex-skills/*/SKILL.md` are derived automatically and should never be edited manually. Mastering the recommended structure for a skill file in ai-berkshire ensures your workflows remain human-readable, machine-parsable, and compatible with the [`scripts/sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-skills.py) automation pipeline.

## The Canonical Skill File Structure

Every skill file in `skills/` follows a rigid logical flow designed to make complex investment research reproducible. Based on the source files [`skills/investment-research.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/investment-research.md), [`skills/portfolio-review.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/portfolio-review.md), and [`skills/industry-research.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/industry-research.md), the structure breaks down into ten distinct sections.

### Header and Argument Placeholder

The file opens with an **H1 title** describing the skill's purpose, followed immediately by an argument placeholder showing where runtime variables are injected.

```markdown

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

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

```

This pattern appears in all canonical skills, ensuring the AI agent knows exactly what target to analyze when the skill is invoked.

### Framework Overview

Following the header, a **high-level outline** describes the analytical steps. This section typically lists the sequential modules the skill will execute, such as data collection, multi-perspective analysis, and valuation.

### Pre-Check and Bias Awareness

Before any data collection begins, the skill must include a **mandatory bias awareness check**. This section ensures the AI acknowledges potential research biases before proceeding.

```markdown

### 前置步骤：AI研究偏见自觉（必须执行）

```

This pre-check appears in all investment research skills to maintain analytical rigor.

### Data Collection Requirements

This section enumerates every data item required for the analysis, including specific source rules. Typical entries include income structure breakdowns, financial indicator tables, and competitive landscape assessments.

```markdown

### 第一步：数据收集

1. **收入结构**：分析公司主营业务构成及占比变化（来源规则见 `skills/financial-data.md`）
2. **财务指标**：收集ROE、毛利率、现金流等核心数据
3. **竞争格局**：获取行业集中度及护城河相关数据

```

### Verification and Financial Rigor

Every skill must validate its data using the repository's financial rigor utilities. This section calls [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py) to cross-validate critical fields against multiple sources.

```bash
python3 tools/financial_rigor.py cross-validate \
  --field <字段名> --values '{"源1": <值>, "源2": <值>}'

```

According to the source code, this verification step is non-optional for skills handling financial data.

### Multi-Perspective Analysis Sections

The core of the skill consists of **distinct analysis sections**, each representing a specific investment philosophy (e.g., Buffett, Munger, Duan Yongping, Li Lu). Each section ends with a **"追问" (deep-dive prompt)** that drives deeper critical thinking.

```markdown

### 第二步：生意本质分析 — 段永平视角

- **关键结论**：这门生意具备长期稳定的现金流特征
- **段永平式追问**：这门生意好在哪？护城河是否可维持10年以上？

```

### Valuation and Decision Framework

This section computes valuation scenarios using the three-scenario method and summarizes the final recommendation. It calls [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py) with specific parameters.

```bash
python3 tools/financial_rigor.py three-scenario \
  --price <price> --eps <eps> --shares <shares> \
  --growth <乐观> <中性> <悲观> --pe <乐观> <中性> <悲观> --years 3

```

### Output Requirements and Audit Controls

The final operational section defines explicitly where the report must be written and how it must be formatted. It also mandates the audit flow using [`tools/report_audit.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/report_audit.py).

```markdown

## 输出要求

1. 所有分析必须有数据支撑，使用 Markdown 表格呈现关键数据
2. 最终将完整报告写入 `~/[公司名]投资研究报告.md`
3. 必须执行 `tools/report_audit.py`-based 抽检

```

## Minimal Skill Template

When creating a new skill in `skills/`, start with this skeleton and fill in domain-specific content:

```markdown

# 示例技能：<简要描述>

对 $ARGUMENTS 进行系统化分析。

## 研究框架

按照以下步骤执行：

### 前置检查

- AI 研究偏见自觉（必须执行）

### 第一步：数据收集

1. 数据项 A ……（来源规则见 `skills/financial-data.md`）
2. 数据项 B ……

### 验证

必须调用 `tools/financial_rigor.py` 对关键字段进行交叉验证：

```bash
python3 tools/financial_rigor.py cross-validate \
  --field <字段名> --values '{"源1": <值>, "源2": <值>}'

```

### 分析 – <大师名称> 视角

- 关键结论 …
- **<大师>式追问**：<深度问题>

### 估值与决策

```bash
python3 tools/financial_rigor.py three-scenario \
  --price <price> --eps <eps> --shares <shares> \
  --growth <乐观> <中性> <悲观> --pe <乐观> <中性> <悲观> --years 3

```

### 输出要求

1. 使用 Markdown 表格呈现关键数据  
2. 报告写入 `~/[公司名]报告.md`  
3. 必须执行 `tools/report_audit.py`-based 抽检

```

## Key Files and Automation Pipeline

Understanding the relationship between source files and generated artifacts is critical:

- **`skills/*.md`** – The canonical skill definitions. These are the only files you should edit manually.
- **`codex-skills/*/SKILL.md`** – Auto-generated Codex-compatible versions. **Do not edit** these files directly.
- **[`scripts/sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-skills.py)** – The synchronization script that regenerates Codex files from `skills/` sources.
- **[`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py)** – Provides programmatic data-validation and valuation utilities referenced throughout skill files.
- **[`tools/report_audit.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/report_audit.py)** – Implements the final audit flow required in every skill's output section.
- **[`AGENTS.md`](https://github.com/xbtlin/ai-berkshire/blob/main/AGENTS.md)** – Project-level documentation explaining the "skills as source of truth" convention.

## Summary

- Skill files in ai-berkshire are **Markdown documents** stored under `skills/` that serve as the single source of truth for workflows.
- The **recommended structure** includes ten sections: Header, Argument Placeholder, Framework Overview, Pre-Check, Data Collection, Verification, Multi-Perspective Analysis, Valuation, Output Requirements, and Audit Controls.
- Always use **[`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py)** for data validation and **[`tools/report_audit.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/report_audit.py)** for final quality control.
- Never manually edit files in `codex-skills/`; instead, modify the source in `skills/` and run [`scripts/sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-skills.py).
- Reference existing skills like [`skills/investment-research.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/investment-research.md) as templates for new domain-specific workflows.

## Frequently Asked Questions

### Where should I create a new skill file in ai-berkshire?

Create new skill files as Markdown documents in the **`skills/`** directory at the repository root. The canonical source files (such as [`skills/investment-research.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/investment-research.md) and [`skills/portfolio-review.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/portfolio-review.md)) reside here, and this is the only location where manual edits should occur. Once you add or modify a file here, 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.

### Why does the skill file structure require explicit tool calls to financial_rigor.py?

The **explicit calls to [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py)** ensure programmatic verification of financial data before analysis proceeds. As implemented in the ai-berkshire source, this cross-validation step prevents the AI from hallucinating financial metrics by mandating that key fields (like revenue, EPS, or PE ratios) be verified against multiple data sources using the `cross-validate` subcommand.

### Can I modify the generated files in the codex-skills directory?

**No.** The files in `codex-skills/*/SKILL.md` are auto-generated from the source files in `skills/` via the [`scripts/sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-skills.py) script. According to the repository's [`AGENTS.md`](https://github.com/xbtlin/ai-berkshire/blob/main/AGENTS.md) documentation, these generated files are derived artifacts; manual edits will be overwritten the next time the synchronization script runs. Always edit the source Markdown files in `skills/` instead.

### What is the purpose of the "追问" (deep-dive prompt) in each analysis section?

The **"追问"** (translated as "deep-dive prompt" or "follow-up question") serves as a structured critical thinking checkpoint at the end of each investment master's analysis section. For example, after the Duan Yongping analysis section, the "段永平式追问" forces the AI to justify why a business is "the right business" and whether its moat is sustainable for 10+ years. This pattern ensures that the AI does not simply collect data but engages in qualitative depth analysis characteristic of value investing methodologies.