# How to Add a New AI Model to AI Berkshire: A Complete Integration Guide

> Integrate new AI models into AI Berkshire. Follow this guide to set environment variables, reference skills, and regenerate Codex wrappers for seamless addition.

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

---

**You can add a new AI model to AI Berkshire by setting the `AI_MODEL` environment variable in your `.env` file, referencing that variable in your skill's front-matter, and regenerating the Codex wrappers using [`sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/sync-codex-skills.py).**

AI Berkshire is built on a modular three-layer architecture that separates **Skills** (user-facing commands), **Agents** (LLM orchestration logic), and **Tools** (low-level utilities). This design lets you swap underlying language models without touching core research logic. Whether you are integrating Claude 3.5 Sonnet, GPT-4o-mini, or a self-hosted open-source weights file, the framework consumes model identifiers through environment variables and skill configuration files.

## Understand the Three-Layer Architecture

Before modifying code, recognize that AI Berkshire delegates LLM selection to the **client wrapper** rather than hard-coding models in skill definitions. The wrapper—implemented in the installation scripts—reads environment variables and passes the model name to the underlying SDK (Claude Code or OpenAI Codex).

- **Skills** live in `skills/*.md` and define the user interface and prompts
- **Agents** handle the communication between Skills and the LLM
- **Tools** in `tools/` provide specialized utilities like [`financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/financial_rigor.py)

The model you specify in the `.env` file flows through the wrapper into the Agent's API calls.

## Step 1: Expose the Model via Environment Variables

The client wrappers in [`scripts/install-claude-commands.sh`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/install-claude-commands.sh) and [`scripts/install-codex-skills.sh`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/install-codex-skills.sh) read the `AI_MODEL` variable (or provider-specific variants like `CLAUDE_MODEL` or `OPENAI_MODEL`) before launching skill binaries.

Create or edit a `.env` file in the repository root:

```text

# .env — repository root

AI_MODEL=gpt-4o-mini

```

These scripts automatically invoke `dotenv` to load variables before execution, ensuring the model identifier is available to the Agents at runtime.

## Step 2: Update Skill Definitions with Front-Matter

Each skill is defined as a Markdown file in the `skills/` directory. The [`sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/sync-codex-skills.py) tool parses YAML front-matter to determine which model the Agent should invoke.

Create a new skill or edit an existing one to include the `model:` key:

```markdown
---
name: my-model-test
description: Sanity-check for the newly added LLM
model: $AI_MODEL
---

# Prompt

Please summarize the latest earnings release for NVIDIA (NVDA) in one sentence.

```

The `$AI_MODEL` syntax expands to the value set in your `.env` file when the wrapper executes the skill.

## Step 3: Regenerate the Codex Skill Wrappers

After modifying skill definitions, you must regenerate the machine-readable wrappers that Codex consumes. Run the synchronization script from the repository root:

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

```

This command converts `skills/*.md` files into `codex-skills/*/SKILL.md` packages, preserving the `model:` reference from the front-matter. If you use Claude Code instead of Codex, simply reload the commands folder; the new skill appears automatically without regeneration.

## Step 4: Verify the Agent Uses the New Model

Invoke your new skill to confirm the correct model is receiving the request:

```bash

# Claude Code example

claude --dangerously-skip-permissions
/my-model-test

```

For Claude Code, add the `--verbose` flag to see the model name in debug logs. For Codex, inspect the generated [`codex-skills/my-model-test/SKILL.md`](https://github.com/xbtlin/ai-berkshire/blob/main/codex-skills/my-model-test/SKILL.md) file, which should contain a line reading `model: $AI_MODEL`.

## Step 5: Add Custom Tools for Model-Specific Parameters (Optional)

Some providers require additional arguments such as `temperature` or `max_tokens`. Create a Python wrapper in `tools/` to expose these parameters via environment variables:

```python

# tools/my_model_wrapper.py

import os
import argparse
from openai import OpenAI

def main():
    parser = argparse.ArgumentParser()
    parser.add_argument("--prompt", required=True)
    args = parser.parse_args()

    client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))
    resp = client.chat.completions.create(
        model=os.getenv("AI_MODEL"),
        messages=[{"role": "user", "content": args.prompt}],
        temperature=float(os.getenv("MY_MODEL_TEMPERATURE", "0.7")),
    )
    print(resp.choices[0].message.content)

if __name__ == "__main__":
    main()

```

Reference this tool in your skill's front-matter under the `tool:` key to inject provider-specific logic into the Agent's workflow.

## Key Files in the Integration Process

- **[`scripts/install-claude-commands.sh`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/install-claude-commands.sh)** — Bootstraps the Claude Code client and injects the model name from `.env` into command wrappers
- **[`scripts/install-codex-skills.sh`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/install-codex-skills.sh)** — Installs generated Codex packages, ensuring the [`SKILL.md`](https://github.com/xbtlin/ai-berkshire/blob/main/SKILL.md) files contain the correct model reference
- **[`scripts/sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-skills.py)** — Converts Markdown skill definitions into Codex-compatible packages while respecting the `model:` front-matter field
- **`skills/`** — Canonical source for all skill definitions; add `.md` files here to expose new models
- **`tools/`** — Location for optional low-level wrappers that handle model-specific parameters

## Summary

- AI Berkshire selects LLMs through **client wrappers** that read the `AI_MODEL` environment variable
- Set your desired model in a `.env` file at the repository root
- Reference the model in skill front-matter using `model: $AI_MODEL` inside `skills/*.md`
- Run `python3 scripts/sync-codex-skills.py` to regenerate Codex wrappers after editing skills
- Use optional **Tools** in `tools/` to manage provider-specific parameters like temperature and token limits

## Frequently Asked Questions

### Can I use multiple AI models simultaneously in AI Berkshire?

Yes. You can create separate skills with different `model:` values in their front-matter, each pointing to distinct environment variables (e.g., `CLAUDE_MODEL` for Claude skills and `OPENAI_MODEL` for GPT skills). The client wrapper for each skill reads its assigned variable, allowing you to route specific tasks to specific providers within the same project.

### Does AI Berkshire support local or self-hosted open-source models?

Yes. As long as the model exposes an API endpoint compatible with the OpenAI or Anthropic SDKs, you can point the `AI_MODEL` variable to your local endpoint (e.g., `http://localhost:8000/v1`) and set the appropriate API key in the `.env` file. If the model requires custom authentication headers, create a wrapper in `tools/` to handle the connection logic.

### What happens if I don't run [`sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/sync-codex-skills.py) after editing a skill?

Codex will continue using the previously generated [`SKILL.md`](https://github.com/xbtlin/ai-berkshire/blob/main/SKILL.md) files in `codex-skills/`, meaning your updated `model:` reference or prompt changes will not take effect. Claude Code users do not need to run this script, as Claude reloads skills dynamically from the `skills/` directory.

### How do I troubleshoot which model is actually being called?

Check the debug output of your client wrapper. For Claude Code, launch with `--verbose` to see the model identifier in the logs. For Codex, inspect the generated `codex-skills/<skill-name>/SKILL.md` file to verify the `model:` field matches your `.env` configuration. You can also add print statements to a custom tool in `tools/` to log the exact model name before making API calls.