# How to Configure Agents in ai-berkshire: A Complete Guide to Skill-Based Agent Orchestration

> Learn how to configure agents in ai-berkshire by editing skill files and running sync scripts. This guide ensures effective skill-based agent orchestration for your projects.

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

---

**You configure agents in ai-berkshire by editing Markdown-based skill files in the `skills/` directory, setting the `agent_type` and runtime parameters, then running [`scripts/sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-skills.py) to generate Codex-compatible wrappers.**

The ai-berkshire repository implements an agent-based workflow system that orchestrates parallel research tasks through declarative configuration. Agents are defined in human-readable Markdown skill files that specify roles, capabilities, and orchestration logic for both Claude Code and Codex runtimes.

## Understanding Agent Configuration Components

Configuring an agent in ai-berkshire requires defining three specific parts that control how the agent behaves at runtime.

### Agent Type and Role Definition

The **agent type** determines the functional role of the agent within the team. According to the source code in [`skills/investment-team.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/investment-team.md), valid roles include `team-lead`, `business-analyst`, `financial-analyst`, `industry-researcher`, and `risk-assessor`. You declare this in the skill file header using the `agent_type` field.

### Sub-agent Type for Codex Runtime

When targeting the Codex runtime, you must specify a **subagent_type** in the generated Codex skill files. As implemented in [`codex-skills/investment-team/SKILL.md`](https://github.com/xbtlin/ai-berkshire/blob/main/codex-skills/investment-team/SKILL.md), this field selects the generic capability set—typically `general-purpose` unless a custom implementation exists.

### Runtime Options and Flags

Runtime behavior is controlled through the **TaskCreate** payload inside skill files. Key parameters include `run_in_background` (boolean), `team_name` (string identifier), and agent-specific `name` fields. These options determine parallel execution behavior and result aggregation.

## The Core Architecture

The ai-berkshire system uses a dual-file architecture where human-editable skills automatically generate machine-readable runtime configurations.

### Skill Files (`skills/*.md`)

These Markdown files serve as the source of truth for agent behavior. The [`skills/investment-team.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/investment-team.md) file outlines the four-role team composition and defines the `agent_type` for the lead agent, while [`skills/financial-data.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/financial-data.md) provides cross-validation standards used by the `financial-analyst` agent.

### Codex Skill Packages (`codex-skills/*/SKILL.md`)

Auto-generated wrappers map Claude-specific concepts onto the Codex runtime. The `subagent_type` field in these files tells Codex which generic agent implementation to instantiate. These files should never be edited manually.

### Sync Scripts ([`scripts/sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-skills.py))

This utility transforms every `skills/*.md` file into a matching `codex-skills/*/SKILL.md` after any change. Running `python3 scripts/sync-codex-skills.py` guarantees that the runtime sees the latest configuration, or use `--check` to verify sync status without writing files.

### Team Orchestration Primitives

The system uses `TeamCreate`, `TaskCreate`, and `TaskUpdate` primitives to build team objects and launch agents in parallel. The `team-lead` agent aggregates sub-agent outputs into the final report through structured task updates.

## Step-by-Step Agent Configuration

Follow these steps to configure a new agent in the ai-berkshire repository.

1. **Select a skill template** – Copy an existing skill file such as [`skills/investment-team.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/investment-team.md) as your starting point.

2. **Set the `agent_type`** – Choose from predefined roles like `financial-analyst` or `industry-researcher` and declare it in the skill header.

3. **Define `subagent_type`** – Specify `general-purpose` for Codex compatibility unless using a custom implementation.

4. **Configure runtime flags** – Inside the `TaskCreate` block, set `run_in_background: true`, assign a `team_name`, and provide the agent's `name`.

5. **Sync the changes** – Execute `python3 scripts/sync-codex-skills.py` to regenerate the corresponding `codex-skills/*/SKILL.md` file.

## Configuration Examples

### Defining a Financial Analyst Agent

Edit [`skills/financial-analysis.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/financial-analysis.md) to include:

```yaml
agent_type: `financial-analyst`
subagent_type: `general-purpose`

TaskCreate:
  - subject: "分析{公司名}财务数据"
    description: |
      1. 拉取收入、净利润、现金流等关键指标
      2. 交叉验证（参见 skills/financial-data.md）
    activeForm:
      run_in_background: true
      team_name: "{公司名}-research"
      name: "financial-analyst"

```

After saving, sync the configuration:

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

```

### Launching a Four-Agent Parallel Team

Invoke the full team configuration as shown in [`skills/investment-team.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/investment-team.md):

```json
TaskCreate [
  { "name": "business-analyst", "subagent_type": "general-purpose", "run_in_background": true, "team_name": "meituan-research" },
  { "name": "financial-analyst", "subagent_type": "general-purpose", "run_in_background": true, "team_name": "meituan-research" },
  { "name": "industry-researcher", "subagent_type": "general-purpose", "run_in_background": true, "team_name": "meituan-research" },
  { "name": "risk-assessor", "subagent_type": "general-purpose", "run_in_background": true, "team_name": "meituan-research" }
]

```

Each sub-agent executes its assigned task and reports back via `TaskUpdate`, while the `team-lead` configured in the skill file aggregates results into the final output.

## Key Configuration Files

Understanding these file locations is essential for proper agent configuration in ai-berkshire.

- **[`AGENTS.md`](https://github.com/xbtlin/ai-berkshire/blob/main/AGENTS.md)** – Contains high-level compatibility notes between Claude and Codex runtimes and establishes that `skills/*.md` files are the source of truth.
- **[`skills/investment-team.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/investment-team.md)** – Demonstrates the complete four-agent team configuration with proper `agent_type` declarations.
- **[`skills/financial-data.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/financial-data.md)** – Defines validation standards for financial data used by the `financial-analyst` agent.
- **[`codex-skills/investment-team/SKILL.md`](https://github.com/xbtlin/ai-berkshire/blob/main/codex-skills/investment-team/SKILL.md)** – Shows the auto-generated Codex wrapper including `subagent_type` mappings.
- **[`scripts/sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-skills.py)** – The synchronization utility that bridges human-editable skills with runtime implementations.
- **[`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py)** – Validation helper invoked by agents for cross-source data verification.

## Summary

- **Agent configuration** in ai-berkshire uses Markdown skill files in `skills/` as the primary interface.
- **Three components** define an agent: `agent_type` (role), `subagent_type` (Codex capability), and TaskCreate runtime flags.
- **Always sync changes** using [`scripts/sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-skills.py) after editing skill files to update Codex-compatible wrappers.
- **Team orchestration** relies on `TeamCreate` and `TaskCreate` primitives to launch parallel agents and aggregate results through the `team-lead`.
- **Source of truth** resides in `skills/*.md` files, while `codex-skills/*/SKILL.md` files are auto-generated and should not be manually edited.

## Frequently Asked Questions

### What is the difference between `agent_type` and `subagent_type`?

The `agent_type` defines the functional role and business logic of the agent (such as `financial-analyst` or `team-lead`) and is defined in the Claude skill files. The `subagent_type` is specific to the Codex runtime and selects the generic implementation capability, typically set to `general-purpose` unless using custom Codex skills.

### How do I sync changes after editing a skill file?

Run `python3 scripts/sync-codex-skills.py` from the repository root after saving any changes to `skills/*.md` files. This regenerates the corresponding `codex-skills/*/SKILL.md` wrappers. Use the `--check` flag to verify whether files need synchronization without writing changes.

### Can I configure agents to run in the background?

Yes, set `run_in_background: true` in the `activeForm` section of the `TaskCreate` payload within your skill file. This allows the `team-lead` agent to launch multiple sub-agents in parallel and aggregate their results asynchronously.

### Where are the validation rules for financial data defined?

Cross-validation standards for financial analysis are defined in [`skills/financial-data.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/financial-data.md) and implemented through the [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py) script. The `financial-analyst` agent references these standards to verify data accuracy across multiple sources.