# How Skills Are Integrated with Agents in AI-Berkshire: A Complete Technical Guide

> Discover how AI-Berkshire integrates skills with agents using a markdown pipeline and Python scripts. Learn to enable agents to register and execute skills as slash commands in this technical guide.

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

---

**AI-Berkshire integrates skills with agents through a markdown-driven pipeline where human-readable skill definitions in `skills/*.md` are automatically compiled into machine-readable packages via [`scripts/sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-skills.py), enabling agents to register and execute them as slash commands.**

The AI-Berkshire repository implements a clean separation between **what** the system can do and **who** executes the work. Understanding how **skills integrated with agents in AI-Berkshire** function reveals a declarative workflow that transforms plain-text capability definitions into executable agent commands through automated code generation.

## The Architecture: Separating Skills from Agents

AI-Berkshire strictly separates **skills** (capabilities) from **agents** (execution entities). According to [`AGENTS.md`](https://github.com/xbtlin/ai-berkshire/blob/main/AGENTS.md) in the repository root, this design ensures that skill logic remains human-editable and version-controlled while agents consume automatically generated, deterministic packages.

The *source of truth* resides entirely in the `skills/` directory. Each capability is authored as a markdown file containing descriptions, argument schemas, and prompt templates. Agents never read the source markdown directly; instead, they consume compiled packages from `codex-skills/`, ensuring a stable runtime interface regardless of how often the human-readable sources evolve.

## Defining Skills in Markdown

### Structure of a Skill Definition

Each skill in AI-Berkshire is defined as a markdown file stored in `skills/` (e.g., [`skills/investment-research.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/investment-research.md)). These files follow a standardized structure that includes:

- A human-readable description of the capability
- Required and optional arguments with type definitions
- A prompt template using Jinja-style syntax (`{{variable}}`)

### Example: Investment Research Skill

Here is the canonical definition from [`skills/investment-research.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/investment-research.md):

```markdown

# Investment Research Skill

## Description

Perform a full‑cycle investment research on a given ticker.

## Arguments

- `ticker` (string) – Stock symbol to research.
- `region` (string, optional) – Market region, default “CN”.

## Prompt Template

You are a value‑investor analyst. Research {{ticker}} in {{region}}. Use at least two independent data sources and output:
- Business overview
- Financial summary (Decimal arithmetic)
- Valuation range
- Investment thesis (✅/❌/⚪)

```

## The Synchronization Pipeline

### Running the Sync Script

The transformation from markdown to agent-ready code happens through [`scripts/sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-skills.py). This script parses every `skills/*.md` file and generates two artifacts:

1. A Codex-compatible skill package under `codex-skills/<skill-name>/SKILL.md`
2. A Claude-Code compatibility prompt under `codex-prompts/<skill-name>.md`

Execute the pipeline with:

```bash
python3 scripts/sync-codex-skills.py

```

### Generated Codex Skill Format

The generated [`codex-skills/investment-research/SKILL.md`](https://github.com/xbtlin/ai-berkshire/blob/main/codex-skills/investment-research/SKILL.md) converts the markdown into structured YAML that agents can parse:

```yaml
name: investment-research
description: Perform a full‑cycle investment research on a ticker.
arguments:
  - name: ticker
    type: string
  - name: region
    type: string
    default: CN
prompt: |
  You are a value‑investor analyst. Research {{ticker}} in {{region}}. ...

```

## Agent Integration and Runtime Execution

### Skill Registration

When an AI agent (Claude or Codex) initializes, it scans the `codex-skills/` directory and registers each [`SKILL.md`](https://github.com/xbtlin/ai-berkshire/blob/main/SKILL.md) as a callable command. The agent exposes the skill's arguments to users through slash commands, making the capabilities discoverable and type-safe.

### Command Execution Flow

The runtime execution follows this pipeline:

1. The user invokes a slash command: `/investment-research ticker=TSLA region=US`
2. The agent resolves the command to the corresponding skill definition in `codex-skills/`
3. Arguments fill the prompt template from the generated [`SKILL.md`](https://github.com/xbtlin/ai-berkshire/blob/main/SKILL.md)
4. The completed prompt is sent to the underlying LLM
5. Structured output returns to the user

## Claude-Code Compatibility Layer

For compatibility with Claude-Code users, the sync script creates matching prompt files in `codex-prompts/<skill-name>.md`. These files act as thin wrappers that forward slash-commands to the generated Codex skills, ensuring the same skill definitions work across different agent environments without duplication. When a user types `/investment-research`, the compatibility layer routes this to the Codex skill package while preserving argument validation.

## Summary

- **Skills** in AI-Berkshire are authored as markdown files in `skills/*.md`, serving as the single source of truth for capabilities.
- The **[`scripts/sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-skills.py)** pipeline automatically generates machine-readable skill packages in `codex-skills/` and compatibility prompts in `codex-prompts/`.
- **Agents** register skills by scanning the generated `codex-skills/` directory at startup, exposing them as type-safe slash commands.
- Changes to skill logic propagate automatically by re-running the sync script, maintaining a deterministic contract between skills and agents.

## Frequently Asked Questions

### What is the source of truth for skill definitions in AI-Berkshire?

The source of truth resides in the plain-text markdown files within the `skills/` directory (e.g., [`skills/investment-research.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/investment-research.md)). These human-editable files contain the canonical descriptions, argument schemas, and prompt templates. The generated files in `codex-skills/` are derived artifacts that should never be manually edited.

### How do I add a new skill to AI-Berkshire?

Create a new markdown file in the `skills/` directory following the standard structure with Description, Arguments, and Prompt Template sections. After saving, run `python3 scripts/sync-codex-skills.py` to generate the corresponding Codex skill package and Claude-Code prompt. The agent will automatically register the new skill on its next startup.

### What happens when I modify an existing skill?

When you modify a skill's markdown definition in `skills/*.md`, simply re-run [`scripts/sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-skills.py) to regenerate the Codex-compatible packages. This propagation is immediate and deterministic—no manual updates to `codex-skills/` or `codex-prompts/` are required, ensuring the agent-skill contract remains synchronized with your changes.

### Can agents use skills without the sync script?

No. Agents consume only the generated machine-readable packages in `codex-skills/*/SKILL.md`. Without running the sync script after editing the markdown source files, agents will execute stale versions of the skills or fail to register new capabilities entirely.