# How the Agent Layer Orchestrates Team-Based Skills in AI Berkshire

> Explore how the AI Berkshire agent layer orchestrates team-based skills. Discover the team-lead skill coordinating autonomous sub-agents for complex research workflows.

- Repository: [Xbt Lin/ai-berkshire](https://github.com/xbtlin/ai-berkshire)
- Tags: internals
- Published: 2026-07-10

---

**The AI Berkshire agent layer implements a lightweight orchestration pattern where a team-lead skill coordinates multiple autonomous sub-agents in parallel to execute complex research workflows.**

AI Berkshire's agent layer transforms single-agent interactions into collaborative team-based skills by enabling dynamic creation of specialized sub-agents that execute concurrently. This architecture, defined in the `investment-team` skill at [`skills/investment-team.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/investment-team.md), allows a coordinator agent to delegate distinct analytical roles—such as business analysis and risk assessment—to background agents that run simultaneously. Understanding how this agent layer manages team lifecycle, task distribution, and result aggregation is essential for extending the framework with custom multi-agent workflows.

## The Agent Layer Architecture

The agent layer in AI Berkshire follows a hub-and-spoke model where the skill itself functions as the **team-lead** (`agent_type: team-lead`). This coordinator manages the entire lifecycle of the research team, from initial permission validation through final report synthesis and cleanup. The design emphasizes **robustness** through fail-fast permission checks, **parallelism** via concurrent sub-agent execution, and **data integrity** enforced by dual-source validation requirements.

According to the source code in [`skills/investment-team.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/investment-team.md), the workflow executes through seven distinct phases, each leveraging specific agent management commands.

## Step-by-Step Team-Based Workflow

### Permission Pre-Check

Before launching any background agents, the skill verifies that `WebSearch` is whitelisted in the local settings. This prevents silent degradation of sub-agents that depend on external data retrieval.

```bash

# Verify WebSearch is available

grep -l '"WebSearch"' .claude/settings.local.json ~/.claude/settings.local.json

```

If this check fails, the workflow aborts immediately to avoid spawning agents that cannot fulfill their data requirements.

### Team Creation

The team-lead initializes the research environment using the `TeamCreate` command, specifying a unique team name and explicitly declaring itself as the coordinator.

```yaml
TeamCreate:
  team_name: "meituan-research"
  agent_type: "team-lead"

```

This creates the logical container that will track all subsequent sub-agent activities and facilitate inter-agent messaging.

### Task Creation and Sub-Agent Configuration

The team-lead generates four distinct tasks using `TaskCreate`, each targeting a specialized role: **business-analyst**, **financial-analyst**, **industry-researcher**, and **risk-assessor**. Each task configuration includes:

- A specific subject and detailed description
- An `activeForm` template defining the analytical framework
- `subagent_type: general-purpose` to spawn autonomous background agents
- `run_in_background: true` to enable parallel execution
- The `team_name` to attach the agent to the correct research context

```yaml
TaskCreate:
  - subject: "商业模式分析"
    description: |
      1. 商业模式本质…
      2. 护城河分析…
    activeForm: "business-analyst"
    subagent_type: "general-purpose"
    run_in_background: true
    team_name: "meituan-research"
  - subject: "财务与估值分析"
    description: |
      1. 近3‑5年营收…
      2. 估值分析…
    activeForm: "financial-analyst"
    subagent_type: "general-purpose"
    run_in_background: true
    team_name: "meituan-research"

```

This single message launches all four sub-agents simultaneously, each receiving tailored instructions while sharing the team context.

### Parallel Execution and Progress Reporting

Once spawned, sub-agents operate concurrently, each pulling the latest data via `WebSearch` and adhering to the strict dual-source validation rules defined in [`skills/financial-data.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/financial-data.md). As they complete their analyses, they communicate partial results back to the team-lead using `SendMessage`:

```yaml
SendMessage:
  type: "message"
  recipient: "team-lead"
  content: "【业务分析】...（Markdown 表格）"

```

The team-lead aggregates these progress updates, displays a live status table, and marks tasks as completed using `TaskUpdate`:

```yaml
TaskUpdate:
  task_id: "<task-id>"
  status: "completed"

```

### Final Synthesis and Cleanup

After receiving all four completed analyses, the team-lead compiles the final investment report into a timestamped markdown file:

```bash

# Compile final report

echo "# Meituan 投研报告" > ~/meituan-investment-report_$(date +%Y%m%d).md

cat part1.md part2.md part3.md part4.md >> ~/meituan-investment-report_$(date +%Y%m%d).md

```

Before publication, the workflow runs a random-sample audit using [`tools/report_audit.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/report_audit.py) to validate report integrity:

```bash
python3 tools/report_audit.py extract --report ~/meituan-investment-report_$(date +%Y%m%d).md
python3 tools/report_audit.py verdict --results '<JSON>' --report ~/meituan-investment-report_$(date +%Y%m%d).md

```

Finally, the team-lead tears down the research team with `TeamDelete`, releasing resources and closing the workflow loop.

## Core Implementation Files

The agent layer functionality relies on three critical components:

- **[`skills/investment-team.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/investment-team.md)** – Defines the team orchestration workflow and agent management logic
- **[`skills/financial-data.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/financial-data.md)** – Specifies dual-source validation requirements for financial data used by sub-agents
- **[`tools/report_audit.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/report_audit.py)** – Implements random-sample auditing to verify final report quality

These files work together to ensure that the agent layer operates reproducibly and auditably across all team-based skills.

## Summary

- **The agent layer** uses a team-lead pattern to coordinate multiple `general-purpose` sub-agents in parallel, enabling complex multi-perspective research workflows.
- **Fail-fast validation** occurs before team creation, verifying `WebSearch` permissions to prevent degraded sub-agent performance.
- **Four specialized roles** (business-analyst, financial-analyst, industry-researcher, risk-assessor) execute concurrently via `TaskCreate` with `run_in_background: true`.
- **Data integrity** is enforced through dual-source validation rules defined in [`skills/financial-data.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/financial-data.md), requiring corroboration from independent sources.
- **Lifecycle management** includes `TeamCreate`, `TaskUpdate` progress tracking, `SendMessage` coordination, and `TeamDelete` cleanup, with optional [`report_audit.py`](https://github.com/xbtlin/ai-berkshire/blob/main/report_audit.py) validation.

## Frequently Asked Questions

### What distinguishes the team-lead from sub-agents in the AI Berkshire agent layer?

The **team-lead** is the primary skill instance that defines the workflow and owns the final output synthesis, while **sub-agents** are transient, background processes spawned via `TaskCreate` with `subagent_type: general-purpose`. The team-lead manages coordination through `TeamCreate` and aggregates results via `SendMessage`, whereas sub-agents execute specific analytical tasks in isolation and report their findings back to the coordinator.

### How does the agent layer ensure data quality across parallel sub-agents?

Each sub-agent must adhere to the validation rules defined in [`skills/financial-data.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/financial-data.md), which mandates that every financial datum be corroborated by at least two independent sources. Additionally, the workflow includes a random-sample audit via [`tools/report_audit.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/report_audit.py) that validates the final compiled report before publication, ensuring that parallel execution does not compromise data integrity.

### Can I customize the number or types of analysts in the team-based skill?

Yes. The modular design in [`skills/investment-team.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/investment-team.md) makes it straightforward to add new roles or modify existing ones by adjusting the `TaskCreate` configurations. You can define additional `activeForm` templates for new specializations (e.g., "ESG-analyst" or "competitive-intelligence") without altering the overarching orchestration logic, as long as each new task specifies `subagent_type: general-purpose` and attaches to the correct `team_name`.

### What happens if WebSearch is not available when running a team-based skill?

The workflow implements a **fail-fast** mechanism that aborts execution before any sub-agents are spawned. The permission pre-check in [`skills/investment-team.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/investment-team.md) explicitly searches for `"WebSearch"` in the local settings files, and if the capability is not found, the skill terminates immediately. This prevents the resource waste and silent failures that would occur if sub-agents launched without access to required external data sources.