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

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

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

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

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. As they complete their analyses, they communicate partial results back to the team-lead using SendMessage:

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:

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:

# 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 to validate report integrity:

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 – Defines the team orchestration workflow and agent management logic
• skills/financial-data.md – Specifies dual-source validation requirements for financial data used by sub-agents
• 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, requiring corroboration from independent sources.
• Lifecycle management includes TeamCreate, TaskUpdate progress tracking, SendMessage coordination, and TeamDelete cleanup, with optional 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, 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 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 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 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.

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