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

> Deploy updated skills in the ai-berkshire environment by editing Markdown files, syncing packages, installing them, and restarting your Claude or Codex client. Follow our complete guide.

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

---

**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`](https://github.com/xbtlin/ai-berkshire/blob/main/./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`](https://github.com/xbtlin/ai-berkshire/blob/main/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`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/install-codex-skills.sh) to copy packages into `$HOME/.codex/skills` and restart the client.

According to [`AGENTS.md`](https://github.com/xbtlin/ai-berkshire/blob/main/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.

```bash

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

```bash
python3 scripts/sync-codex-skills.py

```

This script, located at [`scripts/sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/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:

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

```bash
./scripts/install-codex-skills.sh

```

The [`scripts/install-codex-skills.sh`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/install-codex-skills.sh) script performs four critical operations:

1. Re-runs [`sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/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.

```bash
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`](https://github.com/xbtlin/ai-berkshire/blob/main/./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:

```bash

# 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`](https://github.com/xbtlin/ai-berkshire/blob/main/./scripts/install-codex-skills.sh), and restarting the client.
- The [`scripts/sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-skills.py) file generates Codex-compatible packages from Claude source files.
- The [`scripts/install-codex-skills.sh`](https://github.com/xbtlin/ai-berkshire/blob/main/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`](https://github.com/xbtlin/ai-berkshire/blob/main/AGENTS.md) and [`README_EN.md`](https://github.com/xbtlin/ai-berkshire/blob/main/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`](https://github.com/xbtlin/ai-berkshire/blob/main/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`](https://github.com/xbtlin/ai-berkshire/blob/main/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`](https://github.com/xbtlin/ai-berkshire/blob/main/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.