# How to Implement a New Skill for AI-Berkshire: A Step-by-Step Developer Guide

> Implement a new skill for AI-Berkshire with this developer guide. Learn to create Markdown files, sync Codex skills, and enable slash-command discovery.

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

---

**To implement a new skill for AI-Berkshire, create a Markdown file in `skills/<skill-name>.md`, run [`./scripts/sync-codex-skills.sh`](https://github.com/xbtlin/ai-berkshire/blob/main/./scripts/sync-codex-skills.sh) to generate the Codex-compatible package, and optionally run [`./scripts/sync-codex-prompts.sh`](https://github.com/xbtlin/ai-berkshire/blob/main/./scripts/sync-codex-prompts.sh) to enable slash-command discovery.**

The `xbtlin/ai-berkshire` repository treats files in the `skills/` directory as the single source of truth for every command. Each `.md` file defines a **Skill**—including the user-facing entry point, required arguments, and the workflow triggered (agents, tools, or Bash commands). When you implement a new skill for AI-Berkshire, you only edit the source Markdown; automated scripts handle synchronization with the Codex ecosystem.

## Understanding the Skill Architecture

AI-Berkshire uses a stateless, source-driven architecture that keeps Claude-Code and Codex in lock-step. Four components work together to deliver a unified experience:

- **Skill source** (`skills/<new-skill>.md`): The human-readable Markdown definition you create and maintain. It contains front-matter (optional), a top-level heading, and the Claude-Code workflow.
- **Codex adapter** ([`scripts/sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-skills.py)): Contains the `metadata_for` and `codex_body` functions that parse your source file, prepend a "Codex adapter note," and generate a compatible front-matter block.
- **Codex skill package** (`codex-skills/<skill>/SKILL.md`): The auto-generated file that Codex loads at runtime. Never edit this directly.
- **Optional slash-prompt** (`codex-prompts/<skill>.md`): A thin wrapper generated by [`scripts/sync-codex-prompts.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-prompts.py) that exposes the skill via Codex's `/` UI.

Because the generation process is stateless, the adapter reads the source file, enriches or adds front-matter, and writes the result to the destination without maintaining history.

## Step 1: Create the Skill Source File

Create a new file in `skills/` using clear ATX headings and command patterns. The top-level heading (e.g., `# My New Skill`) becomes the human-readable name.

Include the command pattern using `$ARGUMENTS` to accept input, followed by the workflow section detailing agents, tools, or Bash commands to execute.

```bash
cat > skills/example-skill.md <<'EOF'
---
name: example-skill
---

# Example Skill

/$ARGUMENTS

## Workflow

- Use `Read` to fetch a web page.
- Run a Bash command that calls `tools/financial_rigor.py`.
- Summarise the result with a short markdown table.

## Expected output

| Field | Value |
|-------|-------|
| Price | $123 |
| EPS   | $4.56 |
EOF

```

If you omit the front-matter block, the sync script will automatically add it using the filename.

## Step 2: Sync with Codex Using the Adapter Script

After saving the source file, generate the Codex-compatible package by executing the sync script from the repository root:

```bash
cd /path/to/ai-berkshire
./scripts/sync-codex-skills.sh

# or explicitly:

python3 scripts/sync-codex-skills.py

```

The script scans every `skills/*.md`, applies the `metadata_for` and `codex_body` transformations, and writes the output to `codex-skills/<skill>/SKILL.md`. You will see a summary in your terminal (e.g., "Generated 19 Codex skills …").

## Step 3: Generate Optional Slash Prompts

To make your skill discoverable via Codex's `/` prompt interface, run the prompts synchronization script:

```bash
./scripts/sync-codex-prompts.sh

```

This creates `codex-prompts/<skill>.md`, which serves as the thin wrapper exposing the command to the UI.

## Step 4: Test and Validate

Verify the generated package contains the expected front-matter and adapter note:

```bash
cat codex-skills/example-skill/SKILL.md | head -n 20

```

Test the skill invocation in both environments:

```bash

# Claude-Code

/example-skill AAPL

# Codex

example-skill AAPL

```

The workflow automatically picks up any references to agents, tools like [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py), or Bash commands defined in your source file.

## Step 5: Commit Your Changes

Add the new source file to version control. You may choose to commit the generated `codex-skills/` and `codex-prompts/` directories, or add them to `.gitignore` if you prefer to generate them on-the-fly during deployment.

## Key Files and Scripts Reference

- **[`skills/example-skill.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/example-skill.md)**: The canonical skill definition you edit manually.
- **[`scripts/sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-skills.py)**: The adapter containing `metadata_for()` and `codex_body()` functions for stateless generation.
- **[`codex-skills/example-skill/SKILL.md`](https://github.com/xbtlin/ai-berkshire/blob/main/codex-skills/example-skill/SKILL.md)**: The auto-generated Codex runtime file—never edit directly.
- **[`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py)**: Example utility demonstrating how skills reference custom tools.
- **[`scripts/install-codex-skills.sh`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/install-codex-skills.sh)**: Helper script that installs generated skills into `~/.codex/skills`.

## Summary

- **Source-first workflow**: Always edit files in `skills/`; never modify generated files in `codex-skills/`.
- **Stateless sync**: Running [`./scripts/sync-codex-skills.sh`](https://github.com/xbtlin/ai-berkshire/blob/main/./scripts/sync-codex-skills.sh) regenerates all Codex packages from source, ensuring Claude-Code and Codex stay synchronized.
- **Command pattern**: Use `/$ARGUMENTS` in your Markdown to define input parameters.
- **Optional discovery**: Run [`./scripts/sync-codex-prompts.sh`](https://github.com/xbtlin/ai-berkshire/blob/main/./scripts/sync-codex-prompts.sh) to enable slash-command visibility in Codex.
- **Testing**: Validate generated packages with `cat` before invoking via `/example-skill` (Claude-Code) or `example-skill` (Codex).

## Frequently Asked Questions

### What file format should I use for new AI-Berkshire skills?

Always use Markdown (`.md`) with optional YAML front-matter. The file must reside in the `skills/` directory. A top-level heading (e.g., `# Skill Name`) is required, and the command pattern should reference `$ARGUMENTS` to accept user input.

### Do I need to manually edit the generated Codex skill files?

No. The files in `codex-skills/<skill>/SKILL.md` are generated automatically by [`scripts/sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-skills.py). Because the adapter is stateless, any manual changes would be overwritten on the next sync. Always modify the source file in `skills/` and rerun the sync script.

### How do I make my skill discoverable via slash commands in Codex?

Run [`./scripts/sync-codex-prompts.sh`](https://github.com/xbtlin/ai-berkshire/blob/main/./scripts/sync-codex-prompts.sh) after creating your skill. This generates a thin wrapper in `codex-prompts/<skill>.md` that exposes the skill through Codex's `/` prompt UI, allowing users to discover and invoke it interactively.

### Can I reference custom tools in my skill workflow?

Yes. Reference any tool by its relative path (e.g., [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py)) within the workflow section of your Markdown. The skill execution context resolves these paths at runtime, enabling you to integrate Python scripts, Bash utilities, or external agents seamlessly.