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

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, 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 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, skills/portfolio-review.md, and 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.

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

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

### 前置步骤：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.

### 第一步：数据收集

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 to cross-validate critical fields against multiple sources.

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.

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

- **关键结论**：这门生意具备长期稳定的现金流特征
- **段永平式追问**：这门生意好在哪？护城河是否可维持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 with specific parameters.

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.

## 输出要求

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:

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

对 $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": <值>}'

分析 – <大师名称> 视角

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

估值与决策

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.

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