Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Installation Guide

Most users should run this one-liner:

macOS / Linux:

curl -LsSf https://raw.githubusercontent.com/athola/skrills/HEAD/scripts/install.sh | sh

Windows PowerShell:

powershell -ExecutionPolicy Bypass -NoLogo -NoProfile -Command "iwr https://raw.githubusercontent.com/athola/skrills/HEAD/scripts/install.ps1 -UseBasicParsing | iex"

The installer:

  1. Downloads the correct binary for your system
  2. Installs it to ~/.codex/bin (or detects your setup)
  3. Registers skrills as an MCP server
  4. Syncs your Claude skills to Codex (if both exist)

Verify Installation

skrills --version
skrills doctor        # Check configuration

Alternative: Install from crates.io

If you have Rust installed:

cargo install skrills

Alternative: Build from Source

Clone and build locally:

git clone https://github.com/athola/skrills.git
cd skrills
cargo install --path crates/cli --force

Customizing Installation

The installer accepts environment variables to customize behavior:

VariablePurposeDefault
SKRILLS_CLIENTTarget codex or claudeAuto-detected
SKRILLS_BIN_DIRWhere to install the binary~/.codex/bin
SKRILLS_VERSIONInstall a specific versionLatest
SKRILLS_NO_MIRRORSkip syncing Claude skillsDisabled

Examples

Install for Claude Code only:

SKRILLS_CLIENT=claude SKRILLS_BIN_DIR="$HOME/.claude/bin" \
  curl -LsSf https://raw.githubusercontent.com/athola/skrills/HEAD/scripts/install.sh | sh

Install a specific version:

SKRILLS_VERSION=0.4.0 \
  curl -LsSf https://raw.githubusercontent.com/athola/skrills/HEAD/scripts/install.sh | sh

Skip syncing Claude skills to Codex:

SKRILLS_NO_MIRROR=1 \
  curl -LsSf https://raw.githubusercontent.com/athola/skrills/HEAD/scripts/install.sh | sh

What the Installer Configures

MCP Server Registration

The installer registers Skrills as an MCP server so your AI assistant can use it directly. This configuration is stored in ~/.codex/mcp_servers.json for the Codex MCP registry and ~/.codex/config.toml for Codex configuration.

Hooks (Claude Code only)

For Claude Code, the installer creates a hook at ~/.claude/hooks/prompt.on_user_prompt_submit. This hook integrates Skrills features into the Claude Code workflow.

Skill Mirroring

By default, the installer copies your Claude skills to ~/.codex/skills/ so Codex can discover them. You can skip this step by setting SKRILLS_NO_MIRROR=1.

Troubleshooting

“Command not found” after installation

Add the bin directory to your PATH:

# For Codex (default)
export PATH="$HOME/.codex/bin:$PATH"

# For Claude
export PATH="$HOME/.claude/bin:$PATH"

Add this line to your shell profile (~/.bashrc, ~/.zshrc, etc.) to make it permanent.

MCP server not recognized

Re-run the installer or manually register:

skrills setup --client codex --reinstall

Then run skrills doctor to verify.

Wrong platform binary

If the installer picks the wrong architecture, specify it explicitly:

SKRILLS_TARGET=x86_64-unknown-linux-gnu \
  curl -LsSf https://raw.githubusercontent.com/athola/skrills/HEAD/scripts/install.sh | sh

Find your target triple with:

rustc -vV | grep host

Development Setup

For contributors, the Makefile provides common targets:

make build         # Release build
make test          # Run tests
make lint          # Run linting
make book          # Build this documentation
make book-serve    # Live preview on localhost:3000

Next Steps