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

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 to generate the Codex-compatible package, and optionally generate slash prompts with 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)
• 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.

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.

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

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:

./scripts/sync-codex-prompts.sh

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

# 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 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 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 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 – This executes 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 to expose skills via the Codex / UI.
• Install with ./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 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.

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

Run the installation script ./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.

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