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

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.

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

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

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

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

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:

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

# 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 — Bootstraps the Claude Code client and injects the model name from .env into command wrappers
• scripts/install-codex-skills.sh — Installs generated Codex packages, ensuring the SKILL.md files contain the correct model reference
• 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 after editing a skill?

Codex will continue using the previously generated 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.

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