copilot-skill-sync

Codex stores skills in ~/.codex/skills/. Claude stores commands in ~/.claude/commands/. GitHub Copilot reads neither. copilot-skill-sync bridges the gap: it consolidates skills from all your AI runtimes into a single ~/.copilot/skills/ directory that Copilot and other compatible tools can load directly.

Features

Features

• Sync skills from Codex (~/.codex/skills/) and Claude (~/.claude/commands/)
• Incremental sync via SHA256 checksums — unchanged skills are skipped
• Three context modes: inject context inline (eager), copy flat (lazy), or skip (none)
• Multiple runtime profiles from a single config file
• Dry-run and force-rebuild modes
• Standalone binaries — no Python required on the target machine

---

Installation

From binary (recommended)

Download the binary for your platform from the latest release:

Platform	File
macOS Apple Silicon	copilot-skill-sync-macos-arm64
macOS Intel	copilot-skill-sync-macos-x86_64
Linux x86_64	copilot-skill-sync-linux-x86_64
Windows x64	copilot-skill-sync-windows-x64.exe

macOS / Linux:

chmod +x copilot-skill-sync-macos-arm64
mv copilot-skill-sync-macos-arm64 /usr/local/bin/copilot-skill-sync

Windows: rename the .exe and add it to a directory in your PATH.

From source

Requires Python 3.13+.

git clone https://github.com/chrystiamjr/copilot-skill-sync.git
cd copilot-skill-sync
pip install -e .

---

Quick start

# 1. Detect installed runtimes and write config
copilot-skill-sync init

# 2. Sync all enabled profiles
copilot-skill-sync sync

# 3. Check what was written
ls ~/.copilot/skills/

---

Configuration

Config file: ~/.config/copilot-skill-sync/config.toml

output_dir = "~/.copilot/skills"
context_mode = "lazy"          # global default: eager | lazy | none

[[profiles]]
name = "codex-default"
runtime = "codex"
enabled = true
source_dir = "~/.codex/skills"
context_file = "~/.codex/AGENTS.md"
# context_mode = "eager"       # per-profile override (optional)

[[profiles]]
name = "claude-default"
runtime = "claude"
enabled = false
source_dir = "~/.claude/commands"
context_file = "~/.claude/CLAUDE.md"

Precedence chain

CLI flag > profile.context_mode > config.context_mode > default (lazy)

For all other fields:

CLI flag > profile config > runtime defaults

context_mode

Value	Behavior
lazy	Context file copied flat into the output dir (default)
eager	Context file content injected into each SKILL.md after YAML frontmatter
none	Context file ignored entirely

---

CLI reference

init

Detect installed runtimes and write (or merge) the config file.

copilot-skill-sync init
copilot-skill-sync init --runtime codex
copilot-skill-sync init --output-dir ~/my/skills

Merges new profiles into an existing config — existing profiles are never modified.

sync

Consolidate skills from all enabled profiles into the output directory.

copilot-skill-sync sync
copilot-skill-sync sync --profile codex-default
copilot-skill-sync sync --dry-run
copilot-skill-sync sync --force

Flag	Description
--profile <name>	Limit to one profile by name
--runtime codex|claude	Limit to profiles of this runtime
--source-dir <path>	Override source directory
--context-file <path>	Override context file path
--output-dir <path>	Override output directory
--context-mode eager|lazy|none	Override context mode
--force	Ignore checksums and rebuild all skills
--dry-run	Preview without writing any files

config show

Print the resolved effective config as TOML (paths expanded, defaults applied).

copilot-skill-sync config show

Global flags

Flag	Description
--version, -V	Show version and exit
--help	Show help

---

Output contract

After sync, the output directory contains:

~/.copilot/skills/
  <skill-name>/
    SKILL.md           consolidated skill file
    *.md               loose files (Codex only)
  AGENTS.md            context file copy (lazy mode, Codex)
  skills.json          registry with skill metadata
  .checksums           incremental sync state (one name:sha256 per line)

skills.json shape:

{
  "version": "1",
  "synced_at": "2025-01-01T00:00:00+00:00",
  "skills": [
    {
      "name": "my-skill",
      "profile": "codex-default",
      "sha256": "abc123...",
      "lines": 42,
      "size_bytes": 1024,
      "synced_at": "2025-01-01T00:00:00+00:00"
    }
  ]
}

---

Exit codes

Code	Meaning
0	Success
1	User error (invalid flag, missing directory, invalid config)
2	Unexpected internal error

Set COPILOT_SKILL_SYNC_DEBUG=1 to print full stack traces on internal errors.

---

Development

# Install with dev dependencies
pip install -e ".[dev]"

# Lint
ruff check src tests

# Tests
pytest tests/ -q

See AGENTS.md for architecture, module map, and coding conventions.

---

License

MIT