# How to Create a New Agent in AI-Berkshire: A Declarative Skill Guide

> Easily create a new agent in AI-Berkshire by writing a Markdown skill definition. Generate artifacts and invoke your agent using this declarative skill guide.

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

---

**To create a new agent in AI-Berkshire, write a Markdown skill definition in the `skills/` directory, execute `python3 scripts/sync-codex-skills.py` to generate Codex-compatible artifacts, and invoke the agent via the CLI or generated slash-prompts.**

AI-Berkshire is an open-source autonomous workflow framework that treats every agent as a **skill** defined in Markdown. By maintaining a single source of truth in declarative skill files, the repository eliminates the need for manual Python coding when adding new capabilities. This guide explains the exact file structure, sync process, and runtime behavior required to create a new agent in AI-Berkshire based on the actual source code implementation.

## The Three-Stage Agent Creation Workflow

Creating a new agent follows a strict pipeline that keeps the codebase DRY (Don't Repeat Yourself) while supporting both Claude-Code and Codex execution environments.

### Stage 1: Define the Agent in `skills/*.md`

Every agent begins as a Markdown file in the `skills/` directory. The filename becomes the agent's identifier (e.g., [`stock-price-checker.md`](https://github.com/xbtlin/ai-berkshire/blob/main/stock-price-checker.md)). Refer to [`AGENTS.md`](https://github.com/xbtlin/ai-berkshire/blob/main/AGENTS.md) for global compatibility rules and naming conventions.

The skill file must contain three core components:

1. **H1 Title**: The agent's display name
2. **Argument Block**: Declared with `{{ARGUMENTS}}` followed by parameter definitions
3. **Workflow Section**: Ordered steps using built-in primitives like **TaskCreate**, **SendMessage**, and **TeamCreate**

### Stage 2: Generate Codex Artifacts with [`sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/sync-codex-skills.py)

Once the Markdown definition is complete, run the repository-wide **sync script**:

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

```

Located at [`scripts/sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-skills.py), this script performs three critical operations:
- Scans all `skills/*.md` files
- Converts the declarative DSL into a JSON-style skill manifest
- Writes `codex-skills/<agent-name>/SKILL.md` and `codex-prompts/<agent-name>.md`

### Stage 3: Deploy and Invoke the Agent

After synchronization, the new agent is immediately available through two interfaces:

**CLI Invocation:**

```bash
python -m ai-berkshire <agent-name> --<argument> <value>

```

**Slash Prompt:**
Use the generated file at `codex-prompts/<agent-name>.md` for Codex-style interactions.

## Anatomy of a Skill Definition File

The `skills/*.md` files use a domain-specific language (DSL) interpreted by both the Claude-Code runtime and the Codex shim.

### Header and Arguments

The top-level heading identifies the agent, while the `{{ARGUMENTS}}` block defines runtime variables:

```markdown

# Stock Price Checker

## Arguments

{{ARGUMENTS}}
- ticker: `string` – The stock symbol (e.g., AAPL, 600519)

```

### Workflow Primitives

The workflow body uses ordered steps with these key primitives:
- **TaskCreate**: Defines a unit of work with subject, description, and execution form (e.g., `activeForm: bash`)
- **SendMessage**: Returns results to the team lead or user via the `type: message` directive
- **TeamCreate**: Initializes multi-agent teams for parallel execution (used in complex workflows like [`investment-team.md`](https://github.com/xbtlin/ai-berkshire/blob/main/investment-team.md))

## Complete Example: Stock Price Checker Agent

Here is a minimal, runnable example that queries stock prices using the built-in Xueqiu scraper.

Create [`skills/stock-price-checker.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/stock-price-checker.md):

```markdown

# Stock Price Checker

Check the latest price of a given ticker using the built‑in Xueqiu scraper.

## Arguments

{{ARGUMENTS}}
- ticker: `string` – The stock symbol (e.g., AAPL, 600519)

## Workflow

1. **TaskCreate** – Retrieve price  
   - subject: `Fetch latest price for {{ticker}}`  
   - description: |
     Use the tool `tools/xueqiu_scraper.py` to get the current price.
   - activeForm: `bash`
   - command: |
     python3 ~/ai-berkshire/tools/xueqiu_scraper.py --ticker {{ticker}}

2. **SendMessage** – Return result to user  
   - type: `message`  
   - recipient: `team-lead`  
   - content: |
     The current price of {{ticker}} is {{output}}.

```

After running `python3 scripts/sync-codex-skills.py`, invoke the agent:

```bash
python -m ai-berkshire stock-price-checker --ticker AAPL

```

## How the Sync Script Processes Skills

The [`scripts/sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-skills.py) script is the bridge between declarative Markdown and executable code. It extracts meta-information from each skill file, validates the DSL syntax, and generates two artifacts:

1. **`codex-skills/<skill>/SKILL.md`**: A Codex-compatible JSON-style manifest containing the parsed task graph
2. **`codex-prompts/<skill>.md`**: A slash-command prompt file for direct Codex invocation

This architecture ensures that adding a new agent never requires manual edits to Python code—only the Markdown definition and a sync run.

## Execution Engine and Runtime Behavior

When you invoke an agent, the execution engine reads the generated [`SKILL.md`](https://github.com/xbtlin/ai-berkshire/blob/main/SKILL.md) and performs the following:

1. **Materializes the Team**: Creates the defined team structure and spins up required **sub-agents** (default `subagent_type: general-purpose`)
2. **Orchestrates Parallel Execution**: Processes the task graph, handling dependencies between `TaskCreate` steps
3. **Sandboxed I/O**: All operations (WebSearch, Bash, Read/Write) are **sandboxed** to the repository root according to the security policy

For complex multi-agent workflows, study the **Investment Team** implementation at [`skills/investment-team.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/investment-team.md), which demonstrates parallel sub-agents, data-validation steps, and report finalization.

## Summary

- **Create a new agent in AI-Berkshire** by adding a Markdown file to `skills/` with an H1 title, `{{ARGUMENTS}}` block, and workflow steps using `TaskCreate` and `SendMessage` primitives.
- Run `python3 scripts/sync-codex-skills.py` to generate the executable artifacts in `codex-skills/` and `codex-prompts/`.
- Invoke agents via `python -m ai-berkshire <agent-name>` or through the generated slash-prompts.
- The declarative DSL is the single source of truth—no Python coding required for standard agent creation.
- Complex workflows support multi-agent teams via `TeamCreate` and parallel task execution.

## Frequently Asked Questions

### Do I need to write Python code to create a new agent in AI-Berkshire?

No. The framework uses a declarative approach where you only write Markdown skill files in the `skills/` directory. The [`scripts/sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-skills.py) script handles all code generation automatically, converting your Markdown DSL into executable JSON manifests and prompt files.

### What is the difference between the `skills/` and `codex-skills/` directories?

The `skills/` directory contains the human-readable source of truth written in Markdown. The `codex-skills/` directory contains auto-generated, machine-readable artifacts created by the sync script. You should only edit files in `skills/`; changes to `codex-skills/` will be overwritten on the next sync.

### How do I pass custom arguments when running an agent?

Arguments are defined in the skill's `{{ARGUMENTS}}` block using the format `- name: type – description`. Once synced, pass these via CLI flags: `python -m ai-berkshire <agent-name> --<argument-name> <value>`. The runtime substitutes `{{argument-name}}` placeholders in your workflow with the provided values.

### Can I create multi-agent workflows with sub-agents?

Yes. Complex agents like [`skills/investment-team.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/investment-team.md) demonstrate the `TeamCreate` primitive, which initializes multiple sub-agents (default type `general-purpose`) to execute tasks in parallel. The execution engine handles team coordination, message passing between agents, and parallel task scheduling automatically.