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

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 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, 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, 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 file outlines the four-role team composition and defines the agent_type for the lead agent, while 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)

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 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 to include:

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:

python3 scripts/sync-codex-skills.py

Launching a Four-Agent Parallel Team

Invoke the full team configuration as shown in skills/investment-team.md:

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 – 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 – Demonstrates the complete four-agent team configuration with proper agent_type declarations.
• skills/financial-data.md – Defines validation standards for financial data used by the financial-analyst agent.
• codex-skills/investment-team/SKILL.md – Shows the auto-generated Codex wrapper including subagent_type mappings.
• scripts/sync-codex-skills.py – The synchronization utility that bridges human-editable skills with runtime implementations.
• 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 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 and implemented through the tools/financial_rigor.py script. The financial-analyst agent references these standards to verify data accuracy across multiple sources.

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