# How Are Agents Defined in AI-Berkshire: Orchestration, Taxonomy, and Research Standards > Discover how agents are defined in AI-Berkshire. Explore the centralized taxonomy, agent types, and research standards ensuring accurate financial data and robust tool usage for AI development. - Repository: [Xbt Lin/ai-berkshire](https://github.com/xbtlin/ai-berkshire) - Tags: deep-dive - Published: 2026-07-01 --- **Agents in AI-Berkshire are defined through a centralized taxonomy in [`AGENTS.md`](https://github.com/xbtlin/ai-berkshire/blob/main/AGENTS.md), where each skill declares an `agent_type` (typically `team-lead`) and optional `subagent_type`, enforcing research-quality rules like cross-checking financial data and using exact-arithmetic tools.** AI-Berkshire structures its investment-research workflows through a rigorous, explicit agent-based architecture. The definitions live in the central [`AGENTS.md`](https://github.com/xbtlin/ai-berkshire/blob/main/AGENTS.md) file and are referenced across every skill file in the `skills/` directory, creating a standardized orchestration layer for data collection, analysis, and report generation. ## Agent Taxonomy and Declaration in Skill Files Each skill markdown file declares its agent identity through YAML front-matter. This declaration determines how the agent orchestrates sub-agents, gathers data, and produces research outputs. ### The `agent_type` and `subagent_type` Fields The **`agent_type`** field defines the primary orchestration role. In the current repository, the common value is **`team-lead`**, which designates the top-level coordinator responsible for spawning sub-agents, running validation tools, and producing final reports. Skills may also declare a **`subagent_type`**; when omitted, the system defaults to **`general-purpose`**. The following excerpt from [`skills/private-company-research.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/private-company-research.md) demonstrates the standard declaration: ```yaml # skills/private-company-research.md (excerpt) agent_type: team-lead # top-level orchestrator subagent_type: general-purpose # optional sub-agent role ``` This same pattern appears across other skills including [`skills/news-pulse.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/news-pulse.md) and [`skills/investment-team.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/investment-team.md), ensuring consistency in how agents are defined throughout the repository. ## Research-Quality Standards and Orchestration Responsibilities Agents act as the "who" and "how" of research tasks, enforcing strict quality standards documented in [`AGENTS.md`](https://github.com/xbtlin/ai-berkshire/blob/main/AGENTS.md). These rules govern data validation, mathematical precision, and transparency. ### Validation Rules from AGENTS.md According to the AI-Berkshire source code, `team-lead` agents must enforce three critical research-quality policies: - **Cross-check financial data** from at least two independent sources before including it in analysis - **Label low-confidence conclusions** and explicitly identify any source gaps in the final report - **Use exact-arithmetic tools** located in the `tools/` directory for all valuation calculations ### Tool Invocation Patterns When executing research workflows, agents invoke specialized validation tools to maintain mathematical rigor. The **[`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py)** module provides exact-arithmetic capabilities for valuations, ensuring precision in investment calculations. Agents also leverage **[`tools/stock_screener.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/stock_screener.py)** alongside validation logic to filter and verify financial data before report generation. ## Cross-Platform Compatibility and Synchronization The agent definitions support dual execution environments, maintaining compatibility between Claude Code and Codex implementations through automated synchronization. ### Claude vs Codex Compatibility Layer [`AGENTS.md`](https://github.com/xbtlin/ai-berkshire/blob/main/AGENTS.md) serves as the canonical source of truth for both systems. Claude Code uses **[`CLAUDE.md`](https://github.com/xbtlin/ai-berkshire/blob/main/CLAUDE.md)** for specific behavior overrides, while Codex-generated skills read agent definitions directly from [`AGENTS.md`](https://github.com/xbtlin/ai-berkshire/blob/main/AGENTS.md). This split ensures that both platforms interpret the `agent_type` and `subagent_type` fields consistently while allowing platform-specific optimizations. ### Automated Sync with sync-codex-skills.py The **[`scripts/sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-skills.py)** helper script maintains lock-step alignment between the two systems. After any change to a skill’s agent definition or the central [`AGENTS.md`](https://github.com/xbtlin/ai-berkshire/blob/main/AGENTS.md) taxonomy, running this script regenerates the corresponding Codex skill package, ensuring that Claude and Codex implementations remain synchronized. ## Summary - Agents are defined in **[`AGENTS.md`](https://github.com/xbtlin/ai-berkshire/blob/main/AGENTS.md)** with a taxonomy of **`agent_type`** (e.g., `team-lead`) and **`subagent_type`** (e.g., `general-purpose`). - Each skill file under **`skills/`** declares its agent in YAML front-matter to determine orchestration responsibilities and tool invocation. - **`team-lead`** agents enforce research-quality rules including cross-checking financial sources and using **[`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py)** for exact arithmetic. - The **[`scripts/sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-skills.py)** script maintains compatibility between Claude and Codex execution environments by regenerating skill packages automatically. ## Frequently Asked Questions ### What is the difference between agent_type and subagent_type in AI-Berkshire? The **`agent_type`** field defines the primary orchestration role, typically `team-lead` for top-level coordinators that manage entire research workflows. The **`subagent_type`** field specifies specialized subordinate roles for delegated tasks, defaulting to `general-purpose` when specialized behavior is not required. This hierarchy allows the `team-lead` to spawn appropriate sub-agents based on the specific research context. ### Where are agent definitions stored in the AI-Berkshire repository? Agent definitions are centralized in **[`AGENTS.md`](https://github.com/xbtlin/ai-berkshire/blob/main/AGENTS.md)** at the repository root. Individual skill files under **`skills/`**—such as [`private-company-research.md`](https://github.com/xbtlin/ai-berkshire/blob/main/private-company-research.md), [`news-pulse.md`](https://github.com/xbtlin/ai-berkshire/blob/main/news-pulse.md), and [`investment-team.md`](https://github.com/xbtlin/ai-berkshire/blob/main/investment-team.md)—reference these definitions through their YAML front-matter, creating a decoupled architecture where behavioral policies are maintained centrally but executed locally within each skill. ### How do AI-Berkshire agents ensure research quality? Agents enforce the standards documented in [`AGENTS.md`](https://github.com/xbtlin/ai-berkshire/blob/main/AGENTS.md) by cross-checking financial data against at least two independent sources, using exact-arithmetic tools like **[`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py)** for valuations, and explicitly labeling any low-confidence conclusions or source gaps. These rules are hard requirements for any `team-lead` agent during report generation. ### How does AI-Berkshire maintain compatibility between Claude and Codex agents? The repository uses **[`AGENTS.md`](https://github.com/xbtlin/ai-berkshire/blob/main/AGENTS.md)** as the canonical definition for both systems, with **[`CLAUDE.md`](https://github.com/xbtlin/ai-berkshire/blob/main/CLAUDE.md)** providing Claude-specific overrides. The **[`scripts/sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-skills.py)** script automatically regenerates Codex skill packages whenever agent definitions are updated, ensuring that Claude Code and Codex implementations remain synchronized and interpret the agent taxonomy identically.