How to Deploy Updated Skills in the AI-Berkshire Environment: A Complete Guide

To deploy updated skills in the ai-berkshire environment, edit the Markdown files in skills/, run python3 scripts/sync-codex-skills.py to regenerate Codex-compatible packages, execute ./scripts/install-codex-skills.sh to copy them to $HOME/.codex/skills, and restart your Claude or Codex client.

Deploying updated skills in the xbtlin/ai-berkshire repository requires a specific pipeline to propagate changes from source Markdown files to the client runtime. The process bridges Claude (primary source) and Codex (execution environment) by converting skill definitions into installable packages. Understanding this workflow ensures that your command modifications become immediately available in the / menu or via direct invocation.

The Three-Stage Deployment Pipeline

The repository implements a supervised deployment pipeline consisting of three distinct stages:

1. Source modification – Edit files under skills/*.md (the single source of truth).
2. Package regeneration – Run scripts/sync-codex-skills.py to create codex-skills/<skill-name>/SKILL.md with injected metadata.
3. Client installation – Execute scripts/install-codex-skills.sh to copy packages into $HOME/.codex/skills and restart the client.

According to AGENTS.md, any change to files in skills/ necessitates running the sync script to maintain compatibility between environments.

Step-by-Step Deployment Process

Edit the Canonical Skill Source

Begin by modifying the relevant Markdown file in the skills/ directory. These files contain the command definitions, usage instructions, and parameters that both Claude and Codex interpret.

# Example: editing the investment-research skill

vim skills/investment-research.md

The skills/ directory serves as the single source of truth for all skill definitions. Never edit files directly in codex-skills/; those are generated artifacts.

Regenerate Codex Skill Packages

Run the synchronization script to convert Claude-format Markdown into Codex-compatible skill packages:

python3 scripts/sync-codex-skills.py

This script, located at scripts/sync-codex-skills.py, processes each skills/*.md file by extracting front-matter, adding Codex-adapter metadata, and writing the results to codex-skills/<skill-name>/SKILL.md. The implementation iterates through source files and reconstructs them with appropriate metadata headers:

for source in sorted(CLAUDE_SKILLS.glob("*.md")):
    name = source.stem
    source_text = source.read_text(encoding="utf-8")
    target_dir = CODEX_SKILLS / name
    target = target_dir / "SKILL.md"
    content = metadata_for(name, source.name, source_text) + \
              codex_body(name, source.name, source_text)
    target_dir.mkdir(parents=True, exist_ok=True)
    target.write_text(content, encoding="utf-8")

Install the Updated Skills

Execute the installation script to copy the regenerated packages into your local Codex configuration:

./scripts/install-codex-skills.sh

The scripts/install-codex-skills.sh script performs four critical operations:

1. Re-runs sync-codex-skills.py to ensure the latest source versions are packaged.
2. Creates the destination directory $HOME/.codex/skills (or uses $CODEX_HOME/skills if set).
3. Removes any existing skill folders with matching names to prevent stale artifacts.
4. Copies the generated codex-skills/* directories into the client skill path.

ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
DEST="${CODEX_HOME:-$HOME/.codex}/skills"

python3 "$ROOT/scripts/sync-codex-skills.py"
mkdir -p "$DEST"

for skill_dir in "$ROOT"/codex-skills/*; do
  [ -d "$skill_dir" ] || continue
  name="$(basename "$skill_dir")"
  rm -rf "$DEST/$name"
  cp -R "$skill_dir" "$DEST/$name"
done

Optionally, install slash prompts for Claude-like entry points by running ./scripts/install-codex-prompts.sh, which copies codex-prompts/*.md into $HOME/.codex/prompts.

Restart the Client

Finally, reload the skill registry by restarting your client:

# For Codex

codex --restart

# Or for Claude, quit and relaunch

The new commands appear in the / menu or can be invoked directly using Use <skill-name> ... syntax.

Key Implementation Details

How sync-codex-skills.py Works

The Python script acts as a transpiler between Claude and Codex formats. It reads the canonical Markdown, preserves the instructional content, and wraps it with Codex-specific metadata headers required for the client to recognize the file as an executable skill. This ensures behavioral parity across different AI coding assistants while maintaining one authoritative source.

How install-codex-skills.sh Works

The Bash installer functions as a deployment agent. By checking the $CODEX_HOME environment variable before defaulting to $HOME/.codex, it supports custom installation paths. The script's aggressive cleanup (rm -rf) of existing skill directories ensures that deletions in the source (skills/) propagate correctly to the client, preventing orphaned commands.

Summary

• Deploying updated skills in the ai-berkshire environment requires editing skills/*.md, running python3 scripts/sync-codex-skills.py, executing ./scripts/install-codex-skills.sh, and restarting the client.
• The scripts/sync-codex-skills.py file generates Codex-compatible packages from Claude source files.
• The scripts/install-codex-skills.sh file copies these packages to $HOME/.codex/skills after cleaning old versions.
• Always modify files in skills/ rather than codex-skills/ to maintain source integrity.
• Documentation in AGENTS.md and README_EN.md provides additional context on the compatibility rules and quick-start commands.

Frequently Asked Questions

What files should I edit to update a skill?

Edit the Markdown files located in the skills/ directory (e.g., skills/investment-research.md). These are the canonical sources that define command behavior, parameters, and instructions. Never edit files in codex-skills/ directly, as those are auto-generated artifacts that get overwritten when you run the synchronization script.

Why do I need to run both the sync script and the install script?

The sync script (scripts/sync-codex-skills.py) translates Claude-format Markdown into Codex-compatible packages with proper metadata headers, while the install script (scripts/install-codex-skills.sh) handles file system operations to deploy these packages into the client's skill directory. The sync script focuses on content transformation, whereas the install script manages deployment logistics and environment setup, including creating directories and removing stale versions.

Where are the installed skills stored locally?

By default, skills install to $HOME/.codex/skills/. If you have set the CODEX_HOME environment variable, the script uses $CODEX_HOME/skills instead. Each skill occupies its own subdirectory (e.g., ~/.codex/skills/investment-research/SKILL.md). You can verify the installation by listing this directory after running the install script.

How do I verify that my skill update was deployed successfully?

After restarting the client, open the command menu (usually by typing /) and look for your skill name in the available commands list. Alternatively, attempt to invoke the skill directly using the Use <skill-name> syntax. If the client recognizes the command and displays your updated instructions or parameters, the deployment succeeded. If changes don't appear, ensure you ran both the sync and install scripts, and that no other process has locked the $HOME/.codex/skills directory.

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