# How to Add a New Skill to the AI-Berkshire Project: A Complete Guide

> Easily add a new skill to the ai-berkshire project. Follow our guide to create a Markdown file, run sync scripts, and generate prompts for seamless integration.

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

---

**To add a new skill to the AI-Berkshire project, create a Markdown file in the `skills/` directory, run the sync script at [`scripts/sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-skills.py) to generate the Codex-compatible package, and optionally generate slash prompts with [`scripts/sync-codex-prompts.sh`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-prompts.sh).**

The AI-Berkshire repository treats files in the `skills/` directory as the single source of truth for every command. Each `.md` file defines a human-readable Skill that works with Claude-Code, while a stateless sync pipeline automatically generates Codex-compatible versions that stay synchronized with your source changes.

## Understanding the AI-Berkshire Skill Architecture

The project uses a **source-first architecture** where the Markdown files in `skills/` are the only files you edit manually. When you add a new skill, the system generates derivative artifacts through an automated pipeline.

The core components involved are:

- **`skills/<new-skill>.md`** – The canonical source file containing the command pattern, arguments, and workflow definition (e.g., [`skills/example-skill.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/example-skill.md))
- **[`scripts/sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-skills.py)** – The Codex adapter that transforms source Markdown into Codex-compatible packages using the `metadata_for` and `codex_body` functions
- **`codex-skills/<skill>/SKILL.md`** – The auto-generated Codex skill package (never edit manually)
- **`codex-prompts/<skill>.md`** – Optional slash-prompt wrappers for the `/` UI in Codex

Because the generation process is **stateless**, the sync script reads your source file, adds a front-matter block if missing, prepends a "Codex adapter note," and writes the result to the destination directory. This ensures Claude-Code and Codex remain in lock-step without manual duplication.

## Step-by-Step Guide to Adding a New Skill

### Create the Skill Source File

Create a new Markdown file in the `skills/` directory. The filename becomes the skill identifier.

```bash
cat > skills/my-new-skill.md <<'EOF'

# My New Skill

/my-new-skill $ARGUMENTS

## Workflow

- Use `Read` to fetch financial data.
- Run a Bash command calling `tools/financial_rigor.py`.
- Summarize results in a markdown table.

## Expected output

| Ticker | Price |
|--------|-------|
| AAPL   | $150  |
EOF

```

Key requirements for the source file:
- Use a top-level heading (`# My New Skill`) for the human-readable name

- Include the command pattern with arguments (e.g., `/my-new-skill $ARGUMENTS`)
- Define the workflow steps using standard Claude-Code syntax

### Structure the Markdown Content

The source file supports optional front-matter for metadata. If you omit it, the sync script automatically generates it based on the filename.

```markdown
---
name: my-new-skill
---

# My New Skill

/desired-ticker $ARGUMENTS

## Workflow

1. Fetch data from an API using `Read`.
2. Process with `python tools/financial_rigor.py $ARGUMENTS`.
3. Return formatted results.

```

The `metadata_for` function in [`scripts/sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-skills.py) extracts this information to build the Codex package manifest.

### Sync to Codex with the Adapter Script

After saving your source file, run the sync script to generate the Codex-compatible version:

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

# Or directly with Python:

python3 scripts/sync-codex-skills.py

```

The script scans all `skills/*.md` files, invokes the `codex_body` function to transform the content, and outputs to `codex-skills/<skill>/SKILL.md`. You will see output similar to:

```

Generated 20 Codex skills in codex-skills

```

### Generate Slash Prompts (Optional)

To make your skill discoverable via the `/` prompt UI in Codex, generate the slash prompts:

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

```

This creates [`codex-prompts/my-new-skill.md`](https://github.com/xbtlin/ai-berkshire/blob/main/codex-prompts/my-new-skill.md), which acts as a thin wrapper exposing the skill through the Codex interface.

### Test and Commit

Test the skill in both environments:

```bash

# Claude-Code

/my-new-skill AAPL

# Codex

my-new-skill AAPL

```

Finally, commit your changes. You should commit the new source file in `skills/` and optionally the generated files. If you prefer to generate files on-the-fly, you can add the generated directories to `.gitignore` and regenerate them during deployment.

## Key Files and Functions in the Sync Process

Understanding the generation pipeline helps you debug issues and extend functionality.

**[`scripts/sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-skills.py)**
This script contains two critical functions:
- **`metadata_for(filepath)`** – Parses the source Markdown to extract or generate front-matter metadata (name, description)
- **`codex_body(content, metadata)`** – Transforms the source content into a Codex-compatible format by prepending adapter notes and standardizing the structure

**[`scripts/install-codex-skills.sh`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/install-codex-skills.sh)**
Installs the generated Codex skills from `codex-skills/` into the user's `~/.codex/skills` directory, making them available to the Codex CLI.

**[`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py)**
An example utility module that illustrates how skills reference external tools. Your skill workflows can invoke any script in the `tools/` directory using standard Bash commands.

## Summary

- **Source files live in `skills/`** – Create a `.md` file with a top-level heading, command pattern, and workflow steps.
- **Run [`./scripts/sync-codex-skills.sh`](https://github.com/xbtlin/ai-berkshire/blob/main/./scripts/sync-codex-skills.sh)** – This executes [`scripts/sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-skills.py) to generate Codex-compatible packages via the `metadata_for` and `codex_body` functions.
- **Never edit generated files** – Only modify files in `skills/`; the stateless sync process ensures Codex stays synchronized.
- **Optional slash prompts** – Run [`./scripts/sync-codex-prompts.sh`](https://github.com/xbtlin/ai-berkshire/blob/main/./scripts/sync-codex-prompts.sh) to expose skills via the Codex `/` UI.
- **Install with [`./scripts/install-codex-skills.sh`](https://github.com/xbtlin/ai-berkshire/blob/main/./scripts/install-codex-skills.sh)** – Deploys skills to `~/.codex/skills` for local use.

## Frequently Asked Questions

### What is the difference between the source file and the generated Codex skill?

The source file in `skills/` is the human-readable Markdown you write and maintain. It contains the canonical workflow definition for Claude-Code. The generated Codex skill at `codex-skills/<skill>/SKILL.md` is a transformed version created by [`scripts/sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-skills.py) that includes additional front-matter metadata and adapter notes required by the Codex runtime. You should only edit the source file; the generated file is disposable and recreated on every sync.

### Do I need to manually edit the generated SKILL.md files?

No. The AI-Berkshire architecture is designed so that `skills/` is the single source of truth. The sync script is stateless, meaning it completely regenerates the Codex package from the source file each time it runs. Manually editing `codex-skills/<skill>/SKILL.md` would result in lost changes the next time someone runs [`./scripts/sync-codex-skills.sh`](https://github.com/xbtlin/ai-berkshire/blob/main/./scripts/sync-codex-skills.sh).

### How do I install the skills into Codex for local use?

Run the installation script [`./scripts/install-codex-skills.sh`](https://github.com/xbtlin/ai-berkshire/blob/main/./scripts/install-codex-skills.sh) after generating the skills. This copies the contents of `codex-skills/` into your `~/.codex/skills` directory, where the Codex CLI looks for available skills. You can then invoke any skill by name (e.g., `my-new-skill AAPL`) from the Codex prompt.

### Can I reference custom tools like financial_rigor.py in my new skill?

Yes. The workflow section of your skill Markdown supports standard Bash commands and tool invocations. You can reference any executable in the `tools/` directory, such as `python tools/financial_rigor.py $ARGUMENTS`, or any other script available in the repository. The AI-Berkshire runtime executes these commands in the context of the project root.