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

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). Refer to 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

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

python3 scripts/sync-codex-skills.py

Located at 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:

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:

# 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)

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:

# 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:

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

How the Sync Script Processes Skills

The 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 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, 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 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 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.

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