How to Install Codex Skills Locally Using install-codex-skills.sh

Execute bash scripts/install-codex-skills.sh from the repository root to generate Codex-compatible skill definitions from Claude command files and deploy them to $CODEX_HOME/skills (defaulting to $HOME/.codex/skills).

The install-codex-skills.sh script in the xbtlin/ai-berkshire repository automates the deployment of AI Berkshire's financial analysis skills into your local Codex environment. This utility bridges the gap between the canonical Claude command definitions and Codex's expected format, ensuring both interfaces remain synchronized with a single source of truth. Learning how to install Codex skills locally using install-codex-skills.sh eliminates manual file manipulation and maintains consistent tooling across your development workflow.

Prerequisites and Setup

Before executing the installer, ensure you have the following:

• Bash shell (version 4.0+ recommended)
• Python 3 installed and available as python3 in your PATH
• The ai-berkshire repository cloned locally with read permissions

The script requires no external dependencies beyond standard Unix utilities (mkdir, rm, cp, chmod) and the Python standard library used by the generator.

Understanding the Installation Pipeline

The script performs a four-stage pipeline to ensure idempotent, clean installations. Each stage references specific implementation details in scripts/install-codex-skills.sh.

Step 1: Repository Resolution

First, the script calculates the absolute path to the repository root to ensure all subsequent operations use canonical paths:

ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"

This line, located at line 4 of install-codex-skills.sh, guarantees the script functions correctly regardless of your current working directory.

Step 2: Destination Configuration

The script determines the installation target using the optional CODEX_HOME environment variable:

DEST="${CODEX_HOME:-$HOME/.codex}/skills"

As implemented at line 5, this parameter defaults to $HOME/.codex/skills when CODEX_HOME is unset, providing sensible defaults while allowing customization.

Step 3: Skill Generation

The script invokes the Python converter to generate Codex-specific skill packages from the canonical Markdown sources:

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

This execution (line 7) processes all files in skills/*.md, adds Codex-specific frontmatter, and writes the results to codex-skills/<skill-name>/SKILL.md. The generator ensures the Claude command definitions serve as the single source of truth.

Step 4: Deployment and Permissions

The deployment logic iterates through generated skill directories, removes stale versions, and copies fresh content:

mkdir -p "$DEST"
for skill_dir in "$ROOT/codex-skills"/*/; do
    name=$(basename "$skill_dir")
    rm -rf "$DEST/$name"
    cp -r "$skill_dir" "$DEST/"
done

This loop (lines 10-15 in the source) guarantees idempotency by deleting existing skill directories before copying. Finally, the script ensures utility scripts are executable:

chmod +x "$ROOT"/tools/*.py "$ROOT"/tools/*.sh 2>/dev/null || true

Located at line 17, this command sets executable permissions on Python and shell utilities in the tools/ directory, suppressing errors if no matching files exist.

Customizing the Installation Location

You can redirect the installation destination without modifying the script by setting the CODEX_HOME environment variable:

export CODEX_HOME=/custom/path/to/codex
bash scripts/install-codex-skills.sh

The script respects this variable as implemented at line 5, writing skills to /custom/path/to/codex/skills instead of the default location.

Complete Installation Example

Execute the following from the repository root:

# Optional: specify custom destination

export CODEX_HOME=$HOME/.my-codex

# Run the installer

bash scripts/install-codex-skills.sh

Expected output:

Installed Codex skills to /home/user/.my-codex/
Run ./scripts/install-codex-prompts.sh if you want slash-command prompts.
Restart Codex to pick up new skills.

After execution, restart your Codex client to load the newly installed skills from the destination directory.

Key Files in the Architecture

Understanding the relationship between these files clarifies the installation process:

• scripts/install-codex-skills.sh — The main bash orchestrator that coordinates the entire installation pipeline.
• scripts/sync-codex-skills.py — Python generator that transforms canonical skills/*.md files into Codex-compatible packages in codex-skills/*/SKILL.md.
• skills/ — Directory containing the source of truth Claude command definitions in Markdown format.
• codex-skills/ — Generated directory containing transformed skill packages ready for Codex consumption.
• tools/ — Supporting utilities (e.g., financial_rigor.py) that the installation script makes executable.

Summary

• Single-command installation: Run bash scripts/install-codex-skills.sh from the repository root to deploy all skills.
• Configurable destination: Set CODEX_HOME to override the default $HOME/.codex/skills location.
• Idempotent operation: The script removes existing skill directories before copying, preventing stale file accumulation.
• Automatic generation: The installer calls sync-codex-skills.py to ensure Codex packages reflect the latest Claude command definitions.
• Permission handling: Tool scripts in tools/ receive executable permissions automatically during installation.

Frequently Asked Questions

What happens if CODEX_HOME is not set?

The script defaults to installing skills in $HOME/.codex/skills, as defined by the parameter expansion ${CODEX_HOME:-$HOME/.codex} at line 5 of install-codex-skills.sh. This ensures the installer works out-of-the-box for standard Codex configurations while remaining customizable.

Why does the script delete existing skills before copying?

The rm -rf "$DEST/$name" command within the copy loop (lines 10-15) ensures idempotency by eliminating previous versions before deploying fresh copies. This prevents orphaned files from outdated skill versions conflicting with current implementations.

Do I need to rerun the script after updating the repository?

Yes. The script generates skill definitions from the current state of skills/*.md via sync-codex-skills.py. After pulling updates to the ai-berkshire repository, rerun install-codex-skills.sh to regenerate and reinstall the Codex-compatible packages, then restart Codex to load changes.

Which file permissions does the script modify?

The installer sets executable permissions on all *.py and *.sh files in the tools/ directory using chmod +x, as implemented at line 17. This ensures supporting utilities like financial_rigor.py can execute directly when invoked by Codex skills.

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