How Are Agents Defined in AI-Berkshire: Orchestration, Taxonomy, and Research Standards

Agents in AI-Berkshire are defined through a centralized taxonomy in 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 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 demonstrates the standard declaration:

# 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 and 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. 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 module provides exact-arithmetic capabilities for valuations, ensuring precision in investment calculations. Agents also leverage 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 serves as the canonical source of truth for both systems. Claude Code uses CLAUDE.md for specific behavior overrides, while Codex-generated skills read agent definitions directly from 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 helper script maintains lock-step alignment between the two systems. After any change to a skill’s agent definition or the central 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 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 for exact arithmetic.
• The 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 at the repository root. Individual skill files under skills/—such as private-company-research.md, news-pulse.md, and 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 by cross-checking financial data against at least two independent sources, using exact-arithmetic tools like 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 as the canonical definition for both systems, with CLAUDE.md providing Claude-specific overrides. The 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.

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