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

> Discover the purpose of AGENTS.md in the AI-Berkshire project. It guides Codex workflows, ensuring Claude Code compatibility, research quality, and editing standards.

- Repository: [Xbt Lin/ai-berkshire](https://github.com/xbtlin/ai-berkshire)
- Tags: how-to-guide
- Published: 2026-07-01

---

**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`](https://github.com/xbtlin/ai-berkshire/blob/main/AGENTS.md) file in the [xbtlin/ai-berkshire](https://github.com/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`](https://github.com/xbtlin/ai-berkshire/blob/main/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`](https://github.com/xbtlin/ai-berkshire/blob/main/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`](https://github.com/xbtlin/ai-berkshire/blob/main/financial_rigor.py) and [`report_audit.py`](https://github.com/xbtlin/ai-berkshire/blob/main/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`](https://github.com/xbtlin/ai-berkshire/blob/main/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`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-skills.py)** – Regenerates Codex skill files from canonical sources
- **[`scripts/sync-codex-prompts.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-prompts.py)** – Synchronizes prompt templates

To propagate changes after editing a skill file, run:

```bash
python3 scripts/sync-codex-skills.py

```

This command generates the corresponding Codex-compatible file under [`codex-skills/example_skill/SKILL.md`](https://github.com/xbtlin/ai-berkshire/blob/main/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:

```bash
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`](https://github.com/xbtlin/ai-berkshire/blob/main/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`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py)** – Validates valuation calculations using exact arithmetic
- **[`tools/report_audit.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/report_audit.py)** – Audits research reports before publication

Run the financial rigor check against datasets as follows:

```bash
python3 tools/financial_rigor.py data/sample.csv

```

### Contribution Guidelines

The **editing conventions** section in [`AGENTS.md`](https://github.com/xbtlin/ai-berkshire/blob/main/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`](https://github.com/xbtlin/ai-berkshire/blob/main/AGENTS.md):

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

```markdown

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

```bash
python3 scripts/sync-codex-skills.py

```

3. Verify the generated file appears at [`codex-skills/valuation_analysis/SKILL.md`](https://github.com/xbtlin/ai-berkshire/blob/main/codex-skills/valuation_analysis/SKILL.md) and validate synchronization:

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

```

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

```bash
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`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-skills.py) and [`scripts/sync-codex-prompts.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-prompts.py)) propagate changes and validate repository state via `--check` flags.
- **Research quality standards** require validation through [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py) and [`tools/report_audit.py`](https://github.com/xbtlin/ai-berkshire/blob/main/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`](https://github.com/xbtlin/ai-berkshire/blob/main/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`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py) for exact-arithmetic financial calculations and [`tools/report_audit.py`](https://github.com/xbtlin/ai-berkshire/blob/main/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`](https://github.com/xbtlin/ai-berkshire/blob/main/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.