# How Are the Key Skills in ai-berkshire Trained or Developed? A Prompt-Engineering Guide

> Discover how ai-berkshire skills are developed using prompt-driven instructions and markdown files, not traditional model retraining. Learn about this innovative approach.

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

---

**The key skills in ai-berkshire are not machine-learning models trained on data; instead, they are prompt-driven instruction bundles authored as markdown files and synchronized to Claude and Codex runtimes without requiring model retraining.**

Developing the key skills in ai-berkshire follows a unique **prompt-first architecture** rather than traditional ML training pipelines. This open-source investment research framework treats skills as version-controlled markdown documents that guide large language models (LLMs) through domain-specific workflows. The development process emphasizes deterministic tooling, iterative prompt refinement, and automated synchronization across AI runtimes.

## What Are the Skills in ai-berkshire?

In the ai-berkshire repository, a "skill" is a **prompt-driven instruction bundle** that tells Claude or Codex how to perform a specific investment research task. Unlike neural networks that require gradient descent and dataset curation, these skills are declarative workflows defined in `skills/*.md` files. For example, [`skills/investment-research.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/investment-research.md) contains the full workflow description, required inputs, and the exact prompt template the LLM receives when analyzing a stock ticker.

## The Skill Development Workflow

The development of key skills in ai-berkshire follows a six-step authoring pipeline rather than a training regimen. Each step is version-controlled and fully auditable.

### Step 1: Author the Skill Definition

Researchers begin by writing a markdown file that describes the workflow, required inputs, and the precise prompt the LLM should receive. This file serves as the single source of truth for the skill's behavior.

- **Location**: `skills/*.md` (e.g., [`skills/investment-research.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/investment-research.md), [`skills/quality-screen.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/quality-screen.md), [`skills/portfolio-review.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/portfolio-review.md))
- **Content**: Workflow description, argument schema, and the LLM prompt template

### Step 2: Reference Shared Tools

Each skill delegates precise calculations and data validation to deterministic Python utilities. This separation of concerns ensures that financial mathematics remain accurate and auditable, while the LLM handles reasoning and synthesis.

- **Financial rigor checks**: [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py) performs cross-validation of market data and precise calculations
- **Report auditing**: [`tools/report_audit.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/report_audit.py) automatically audits generated reports for consistency and accuracy

When a skill executes, it calls these tools as prescribed in the markdown definition (see lines 56-71 of [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py) for implementation details).

### Step 3: Generate Codex Artifacts

A helper script scans the `skills/` directory and creates matching Codex-compatible packages. This ensures the same skill definition works across both Claude and OpenAI Codex runtimes.

```bash

# Generate Codex packages from markdown skills

python scripts/sync-codex-skills.py

```

The script [`scripts/sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-skills.py) automatically converts each markdown skill into a `codex-skills/*/SKILL.md` package structure, maintaining parity between runtime environments.

### Step 4: Produce CLI Slash Prompts

A second script transforms each skill into an installable slash prompt, enabling command-line invocation like `ai-berkshire investment-research`.

```bash

# Generate and install CLI prompts

python scripts/sync-codex-prompts.py
./scripts/install-codex-prompts.sh

```

### Step 5: Runtime Execution

When invoked, the framework loads the skill markdown, injects user arguments, executes auxiliary tools, and sends the constructed prompt to the LLM. The core runner code lives in the agent layer, documented in [`AGENTS.md`](https://github.com/xbtlin/ai-berkshire/blob/main/AGENTS.md), which defines the coordination contract between Claude and Codex agents.

### Step 6: Continuous Refinement

Authors iterate on the markdown description, add new data sources, or refine the analysis steps. No retraining of the LLM is required—only the prompt text evolves. Changes to `skills/*.md` automatically propagate to Codex prompts after the next synchronization run.

## Why Traditional Training Is Not Required

The ai-berkshire architecture eliminates the need for model fine-tuning through three design principles:

- **Prompt-first design**: The underlying LLM already possesses general language and reasoning capabilities. Skill files merely guide the model to apply these capabilities to investment research workflows, similar to few-shot prompting at scale.

- **Deterministic tooling**: Financial calculations and cross-source verification are strictly handled by Python scripts ([`financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/financial_rigor.py), [`report_audit.py`](https://github.com/xbtlin/ai-berkshire/blob/main/report_audit.py)). This guarantees numerical accuracy without involving the LLM in mathematical operations that could introduce hallucinations.

- **Version-controlled evolution**: All skill definitions live in Git, creating a fully auditable history of how each skill's capabilities developed. When business logic changes, contributors edit the markdown and push, rather than retraining a model.

## How to Invoke a Skill: Practical Examples

Once the skills are authored and synchronized, users interact with them through command-line interfaces or direct API calls.

### Command Line Invocation

```bash

# Install the generated Codex prompts (one-time setup)

./scripts/install-codex-prompts.sh

# Run the investment-research skill for a specific ticker

ai-berkshire investment-research --ticker AAPL

```

This command triggers the following internal sequence:

1. **Parse arguments**: The CLI wrapper converts `--ticker AAPL` into `$ARGUMENTS` for the markdown prompt
2. **Load the skill**: Reads [`skills/investment-research.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/investment-research.md) as the source of truth
3. **Execute tools**: Calls `tools/financial_rigor.py verify-market-cap` as defined in the skill specification
4. **Send prompt**: Dispatches the constructed prompt to Claude or Codex
5. **Return report**: Receives a structured markdown research report

### Direct API Usage

```python
from ai_berkshire.agent import run_skill

# Load the quality-screen skill and analyze Chinese equities

report = run_skill(
    skill_name="quality-screen",
    arguments="腾讯, 美团, 英伟达"
)

print(report)  # Markdown containing the 7-indicator screening result

```

The `run_skill` function is a thin wrapper that assembles the prompt, manages the LLM endpoint call, and stitches the response back into the caller's workflow.

## Summary

- **Skills are markdown, not models**: The key skills in ai-berkshire are authored as markdown files in `skills/*.md`, not trained neural networks.
- **Deterministic tooling ensures accuracy**: Financial calculations are handled by [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py) and [`tools/report_audit.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/report_audit.py), removing mathematical liability from the LLM.
- **Synchronization enables portability**: [`scripts/sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-skills.py) and [`scripts/sync-codex-prompts.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-prompts.py) propagate skill definitions to both Claude and Codex runtimes.
- **No retraining required**: Skill development is iterative prompt engineering; changes are version-controlled in Git and deployed instantly without model updates.

## Frequently Asked Questions

### Do the ai-berkshire skills require fine-tuning or model training?

No. The skills are prompt-driven instruction bundles that leverage the base capabilities of Claude or Codex. Development involves refining markdown prompts in `skills/*.md` files rather than performing gradient descent or dataset curation. The LLM's general reasoning abilities are directed toward investment tasks through careful prompt engineering.

### How do I add a new skill to the ai-berkshire repository?

Create a new markdown file in the `skills/` directory describing the workflow, inputs, and LLM prompt. Then run [`scripts/sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-skills.py) to generate the Codex package and [`scripts/sync-codex-prompts.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-prompts.py) to create the CLI command. The new skill becomes available immediately after installation, with no retraining or model deployment required.

### What ensures accuracy in financial calculations if the LLM doesn't perform the math?

Deterministic Python scripts handle all quantitative operations. According to the source code in [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py), the framework performs explicit financial calculations and cross-validation outside the LLM context. The LLM receives the calculated results for synthesis and narrative generation, but the numbers themselves are computed by audited, version-controlled code.

### Where is the source of truth for skill definitions stored?

The canonical definitions reside in `skills/*.md` files (such as [`skills/investment-research.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/investment-research.md)). These markdown files are the single source of truth; the synchronization scripts generate derivative artifacts for specific runtimes (Codex packages, CLI prompts) from these originals. This ensures consistency across deployment targets while maintaining a human-readable, version-controlled skill definition.