What Is the Purpose of AGENTS.md in the AI-Berkshire Project?

AGENTS.md serves as the central architectural guide for Codex-related workflows, defining how the AI-Berkshire project maintains compatibility between Claude Code and Codex while enforcing research quality standards and editing conventions.

The AGENTS.md file in the xbtlin/ai-berkshire repository acts as the authoritative reference manual for contributors working with AI-assisted development tools. It establishes the protocols for authoring, synchronizing, and maintaining skills and prompts across dual-platform environments, ensuring that the single source of truth remains in the canonical skills/ directory while generated artifacts live in codex-skills/ and codex-prompts/.

Core Purpose of AGENTS.md in AI-Berkshire

Dual-Platform Architectural Guide

AGENTS.md explains how the project supports both Claude Code and Codex users without fragmenting the codebase. The file mandates that all canonical skill definitions reside in skills/*.md files, which serve as the master source for Claude Code slash-commands. When contributors modify these files, automated synchronization scripts propagate the changes to Codex-compatible formats, ensuring platform-specific optimizations do not diverge from the core logic.

Project Layout and Directory Structure

According to the source code analysis, AGENTS.md defines the project layout across six main directories:

• skills/ – Canonical source files for Claude Code commands (the single source of truth)
• codex-skills/ – Auto-generated Codex skill packages derived from skills/*.md
• codex-prompts/ – Generated prompt templates for Codex workflows
• tools/ – Research quality utilities including financial_rigor.py and report_audit.py
• reports/ – Output directory for analyzed research
• scripts/ – Synchronization utilities that enforce compatibility rules

This structure ensures that contributors know exactly where to place new content and where to find generated artifacts.

Synchronization Workflow and Compatibility Rules

The Canonical Source Pattern

The compatibility rules in AGENTS.md (lines 25-28) dictate that no contributor should edit files in codex-skills/ or codex-prompts/ directly. Instead, all changes must originate in the skills/*.md files. This pattern prevents drift between the Claude Code and Codex implementations, maintaining consistency across both platforms.

Sync Scripts and Validation

The project provides two primary synchronization utilities in the scripts/ directory:

• scripts/sync-codex-skills.py – Regenerates Codex skill files from canonical sources
• scripts/sync-codex-prompts.py – Synchronizes prompt templates

To propagate changes after editing a skill file, run:

python3 scripts/sync-codex-skills.py

This command generates the corresponding Codex-compatible file under codex-skills/example_skill/SKILL.md.

To verify that generated artifacts are up-to-date without modifying files (the Editing Rules check, lines 58-63), use:

python3 scripts/sync-codex-skills.py --check
python3 scripts/sync-codex-prompts.py --check

These validation commands ensure repository integrity before commits.

Research Quality Standards and Editing Conventions

Financial Rigor and Verification

AGENTS.md establishes research quality standards that mandate dual-source verification and exact-arithmetic calculations for financial analysis. The repository includes specialized tools to enforce these standards:

• tools/financial_rigor.py – Validates valuation calculations using exact arithmetic
• tools/report_audit.py – Audits research reports before publication

Run the financial rigor check against datasets as follows:

python3 tools/financial_rigor.py data/sample.csv

Contribution Guidelines

The editing conventions section in AGENTS.md standardizes how contributors structure Markdown files, name directories, and reference external data. These rules ensure that automated scripts can parse skill definitions correctly and that the repository remains reproducible across different development environments.

Practical Workflow Example

When adding a new Claude Code skill to the project, follow this workflow defined in AGENTS.md:

1. Create the canonical source file in the skills/ directory:

# skills/valuation_analysis.md

## Valuation Analysis

Defines a slash-command for running DCF models with exact arithmetic.

2. Execute the synchronization script to generate the Codex version:

python3 scripts/sync-codex-skills.py

3. Verify the generated file appears at codex-skills/valuation_analysis/SKILL.md and validate synchronization:

python3 scripts/sync-codex-skills.py --check

4. Run research quality checks if the skill involves financial data:

python3 tools/financial_rigor.py data/valuation_input.csv

Summary

• AGENTS.md is the central architectural guide for managing dual-platform AI workflows in the AI-Berkshire project.
• The file mandates a single source of truth pattern where skills/*.md files serve as canonical sources for both Claude Code and Codex.
• Synchronization scripts (scripts/sync-codex-skills.py and scripts/sync-codex-prompts.py) propagate changes and validate repository state via --check flags.
• Research quality standards require validation through tools/financial_rigor.py and tools/report_audit.py to ensure exact-arithmetic and dual-source verification.
• Contributors must never edit generated files in codex-skills/ or codex-prompts/ directly, only the canonical sources in skills/.

Frequently Asked Questions

What is the primary purpose of AGENTS.md in AI-Berkshire?

AGENTS.md serves as the reference manual that tells contributors how to author, sync, and maintain Codex-compatible skills, prompts, and tools within the AI-Berkshire codebase. It defines the architectural boundaries between Claude Code and Codex implementations while enforcing research quality standards.

How do I sync changes from Claude Code skills to Codex-compatible formats?

After editing any file in skills/*.md, run python3 scripts/sync-codex-skills.py from the repository root. This regenerates the corresponding Codex artifacts in codex-skills/*/SKILL.md. Always validate changes first using the --check flag to ensure synchronization before committing.

What research quality tools are required by AGENTS.md?

The file mandates the use of tools/financial_rigor.py for exact-arithmetic financial calculations and tools/report_audit.py for auditing research reports. These tools enforce dual-source verification and prevent floating-point errors in valuation models.

Can I edit files in codex-skills/ directly?

No. AGENTS.md explicitly forbids editing generated files in codex-skills/ or codex-prompts/. These directories contain auto-generated artifacts derived from the canonical sources in skills/. Direct edits would be overwritten by the synchronization scripts and violate the compatibility rules.

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