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

To implement a new skill for AI-Berkshire, create a Markdown file in skills/<skill-name>.md, run ./scripts/sync-codex-skills.sh to generate the Codex-compatible package, and optionally run ./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): 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 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.

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:

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:

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

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

Test the skill invocation in both environments:

# Claude-Code

/example-skill AAPL

# Codex

example-skill AAPL

The workflow automatically picks up any references to agents, tools like 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: The canonical skill definition you edit manually.
• scripts/sync-codex-skills.py: The adapter containing metadata_for() and codex_body() functions for stateless generation.
• codex-skills/example-skill/SKILL.md: The auto-generated Codex runtime file—never edit directly.
• tools/financial_rigor.py: Example utility demonstrating how skills reference custom tools.
• 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 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 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. 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 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) 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.

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