Sync Guide

Skrills synchronizes skills, commands, MCP server configurations, and preferences between Claude Code and Codex CLI. This enables you to maintain a single source of truth while using both CLIs.

Sync Direction

By default, sync operations copy from Claude Code to Codex CLI. Use --from codex to reverse the direction.

# Claude → Codex (default)
skrills sync-all

# Codex → Claude
skrills sync-all --from codex

What Gets Synced

Skills

Skills are copied between skill directories:

• Claude: ~/.claude/skills/
• Codex: ~/.codex/skills/ (discovery root; skills must be **/SKILL.md)

Codex skills are disabled by default; enable them in ~/.codex/config.toml:

[features]
skills = true

skrills sync                # Skills only
skrills sync-all            # Everything including skills

Slash Commands

Commands are synced byte-for-byte, preserving non-UTF-8 content:

• Claude: ~/.claude/commands/
• Codex: ~/.codex/prompts/

skrills sync-commands --from claude
skrills sync-commands --skip-existing-commands  # Don't overwrite existing

MCP Server Configurations

MCP server definitions are synchronized between configuration files:

skrills sync-mcp-servers --from claude

User Preferences

Preferences and settings are synchronized:

skrills sync-preferences --from claude

Sync-All Command

The most common workflow is to sync everything at once:

skrills sync-all --from claude --skip-existing-commands

Options:

• --from: Source side (claude or codex)
• --dry-run: Preview changes without writing
• --skip-existing-commands: Preserve local commands
• --validate: Run validation after sync
• --autofix: Auto-fix validation issues

Preview Changes

Before syncing, preview what will change:

skrills sync-status --from claude

This shows:

• Files that would be added
• Files that would be updated
• Configuration differences

Mirror Command

The mirror command is a comprehensive sync that also updates AGENTS.md:

skrills mirror --skip-existing-commands

Use --dry-run to preview:

skrills mirror --dry-run

MCP Tools

When running as an MCP server, these sync tools are available:

Environment Variables

• SKRILLS_MIRROR_SOURCE: Override mirror source root (default ~/.claude)

Best Practices

1. Use dry-run first: Always preview changes before syncing.
2. Sync regularly: Keep configurations in sync to avoid drift.
3. Validate after sync: Run skrills validate after syncing to catch issues.
4. Protect local commands: Use --skip-existing-commands to preserve customizations.
5. One direction: Pick a primary CLI and always sync from it to maintain consistency.