How Skills Are Integrated with Agents in AI-Berkshire: A Complete Technical Guide

AI-Berkshire integrates skills with agents through a markdown-driven pipeline where human-readable skill definitions in skills/*.md are automatically compiled into machine-readable packages via scripts/sync-codex-skills.py, enabling agents to register and execute them as slash commands.

The AI-Berkshire repository implements a clean separation between what the system can do and who executes the work. Understanding how skills integrated with agents in AI-Berkshire function reveals a declarative workflow that transforms plain-text capability definitions into executable agent commands through automated code generation.

The Architecture: Separating Skills from Agents

AI-Berkshire strictly separates skills (capabilities) from agents (execution entities). According to AGENTS.md in the repository root, this design ensures that skill logic remains human-editable and version-controlled while agents consume automatically generated, deterministic packages.

The source of truth resides entirely in the skills/ directory. Each capability is authored as a markdown file containing descriptions, argument schemas, and prompt templates. Agents never read the source markdown directly; instead, they consume compiled packages from codex-skills/, ensuring a stable runtime interface regardless of how often the human-readable sources evolve.

Defining Skills in Markdown

Structure of a Skill Definition

Each skill in AI-Berkshire is defined as a markdown file stored in skills/ (e.g., skills/investment-research.md). These files follow a standardized structure that includes:

• A human-readable description of the capability
• Required and optional arguments with type definitions
• A prompt template using Jinja-style syntax ({{variable}})

Example: Investment Research Skill

Here is the canonical definition from skills/investment-research.md:

# Investment Research Skill

## Description

Perform a full‑cycle investment research on a given ticker.

## Arguments

- `ticker` (string) – Stock symbol to research.
- `region` (string, optional) – Market region, default “CN”.

## Prompt Template

You are a value‑investor analyst. Research {{ticker}} in {{region}}. Use at least two independent data sources and output:
- Business overview
- Financial summary (Decimal arithmetic)
- Valuation range
- Investment thesis (✅/❌/⚪)

The Synchronization Pipeline

Running the Sync Script

The transformation from markdown to agent-ready code happens through scripts/sync-codex-skills.py. This script parses every skills/*.md file and generates two artifacts:

1. A Codex-compatible skill package under codex-skills/<skill-name>/SKILL.md
2. A Claude-Code compatibility prompt under codex-prompts/<skill-name>.md

Execute the pipeline with:

python3 scripts/sync-codex-skills.py

Generated Codex Skill Format

The generated codex-skills/investment-research/SKILL.md converts the markdown into structured YAML that agents can parse:

name: investment-research
description: Perform a full‑cycle investment research on a ticker.
arguments:
  - name: ticker
    type: string
  - name: region
    type: string
    default: CN
prompt: |
  You are a value‑investor analyst. Research {{ticker}} in {{region}}. ...

Agent Integration and Runtime Execution

Skill Registration

When an AI agent (Claude or Codex) initializes, it scans the codex-skills/ directory and registers each SKILL.md as a callable command. The agent exposes the skill's arguments to users through slash commands, making the capabilities discoverable and type-safe.

Command Execution Flow

The runtime execution follows this pipeline:

1. The user invokes a slash command: /investment-research ticker=TSLA region=US
2. The agent resolves the command to the corresponding skill definition in codex-skills/
3. Arguments fill the prompt template from the generated SKILL.md
4. The completed prompt is sent to the underlying LLM
5. Structured output returns to the user

Claude-Code Compatibility Layer

For compatibility with Claude-Code users, the sync script creates matching prompt files in codex-prompts/<skill-name>.md. These files act as thin wrappers that forward slash-commands to the generated Codex skills, ensuring the same skill definitions work across different agent environments without duplication. When a user types /investment-research, the compatibility layer routes this to the Codex skill package while preserving argument validation.

Summary

• Skills in AI-Berkshire are authored as markdown files in skills/*.md, serving as the single source of truth for capabilities.
• The scripts/sync-codex-skills.py pipeline automatically generates machine-readable skill packages in codex-skills/ and compatibility prompts in codex-prompts/.
• Agents register skills by scanning the generated codex-skills/ directory at startup, exposing them as type-safe slash commands.
• Changes to skill logic propagate automatically by re-running the sync script, maintaining a deterministic contract between skills and agents.

Frequently Asked Questions

What is the source of truth for skill definitions in AI-Berkshire?

The source of truth resides in the plain-text markdown files within the skills/ directory (e.g., skills/investment-research.md). These human-editable files contain the canonical descriptions, argument schemas, and prompt templates. The generated files in codex-skills/ are derived artifacts that should never be manually edited.

How do I add a new skill to AI-Berkshire?

Create a new markdown file in the skills/ directory following the standard structure with Description, Arguments, and Prompt Template sections. After saving, run python3 scripts/sync-codex-skills.py to generate the corresponding Codex skill package and Claude-Code prompt. The agent will automatically register the new skill on its next startup.

What happens when I modify an existing skill?

When you modify a skill's markdown definition in skills/*.md, simply re-run scripts/sync-codex-skills.py to regenerate the Codex-compatible packages. This propagation is immediate and deterministic—no manual updates to codex-skills/ or codex-prompts/ are required, ensuring the agent-skill contract remains synchronized with your changes.

Can agents use skills without the sync script?

No. Agents consume only the generated machine-readable packages in codex-skills/*/SKILL.md. Without running the sync script after editing the markdown source files, agents will execute stale versions of the skills or fail to register new capabilities entirely.

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