skillsync-cli

Sync coding agent skills from a Canonical Skill Registry (CSR) to Claude Code, Codex CLI, Gemini CLI, OpenCode CLI, and Cursor.

Installation

npm install -g @dallasdotjs/skillsync-cli
# or
pnpm add -g @dallasdotjs/skillsync-cli

Quick Start

# Initialize a new skill registry in the current directory
skillsync init

# Validate the registry
skillsync doctor

# List all skills
skillsync list

# Apply skills to all platforms
skillsync apply

Commands

Most commands are available under grouped nouns (recommended), with backward-compatible aliases:

• skillsync skills list|show|add|status (aliases: list, show, add, status)
• skillsync adapters list|check (aliases: adapters, adapters --check)
• skillsync profile list|show (alias: profile)
• skillsync templates list|show (alias: templates)

skillsync init

Initialize a new Canonical Skill Registry in the current directory.

skillsync init
skillsync init --template basic

skillsync skills list (alias: skillsync list)

List all skills in the registry.

skillsync list                    # List all skills
skillsync list --tags workflow    # Filter by tag
skillsync list --json             # JSON output

skillsync skills show <skill-id> (alias: skillsync show)

Display a skill's metadata and content.

skillsync show my-skill              # Show skill details
skillsync show my-skill --content-only | pbcopy  # Copy content

skillsync doctor

Validate registry schema and check target paths.

skillsync doctor              # Validate registry
skillsync doctor --fix        # Auto-fix simple issues

skillsync judge <skill-id>

Rate a skill using an AI judge rubric.

Notes:

• Requires ANTHROPIC_API_KEY.
• Requires explicit consent via --agree-to-send-content before sending content to the AI provider.
• Use --write to cache results to skills/<id>/judge.json for future runs.

skillsync judge my-skill --agree-to-send-content
skillsync judge my-skill --agree-to-send-content --write
skillsync judge my-skill --agree-to-send-content --min-score 7
skillsync judge my-skill --json

skillsync apply

Render skills and write to all target platforms.

skillsync apply                          # Apply all
skillsync apply --adapter claude-code    # Apply to one platform
skillsync apply --dry-run                # Preview changes
skillsync apply --force                  # Overwrite without confirmation

skillsync adapters list|check (alias: skillsync adapters)

List configured adapters and their target paths.

skillsync adapters              # List all adapters
skillsync adapters --check      # Verify target paths

Global Options

| Flag | Description | |------|-------------| | -h, --help | Show help | | --version | Print version | | -q, --quiet | Suppress non-essential output | | -v, --verbose | Show detailed output | | --json | Output in JSON format | | --plain | Output in plain, stable text format | | -C, --registry <path> | Path to CSR folder (default: . or $SKILLSYNC_REGISTRY) | | --profile <name> | Profile name to use (default: active) | | --no-input | Disable prompts and fail if input is required | | --no-color | Disable colored output |

Registry Structure

A Canonical Skill Registry follows this structure:

my-registry/
├── skills/
│   └── my-skill/
│       ├── skill.yaml      # Metadata
│       └── content.md      # Skill content
├── adapters/
│   ├── claude-code.yaml
│   ├── codex-cli.yaml
│   └── ...
├── profiles/
│   └── default.yaml
└── config.yaml

skill.yaml

name: My Skill
description: A helpful skill for coding agents
tags:
  - workflow
  - automation
version: "1.0.0"
triggers:
  - "when working with APIs"

content.md

The actual skill content in Markdown format.

Environment Variables

| Variable | Description | |----------|-------------| | SKILLSYNC_REGISTRY | Default CSR path | | ANTHROPIC_API_KEY | Enables AI generation and judging | | NO_COLOR | Disable colors |

Exit Codes

| Code | Meaning | Examples | |------|---------|----------| | 0 | Success | Command completed successfully | | 1 | Generic failure | Unexpected error, apply errors | | 2 | Invalid usage | Missing required args, validation failed | | 3 | External error | API failure, network error, filesystem error | | 4 | Resource not found | Skill, adapter, template, or profile not found; doctor validation errors | | 5 | Quality gate failure | Judge score below --min-score |

Supported Platforms

• Claude Code - ~/.claude/skills/<id>/SKILL.md
• Codex CLI - ~/.codex/skills/<id>.md
• Gemini CLI - ~/.gemini/skills/<id>.md
• OpenCode CLI - ~/.opencode/skills/<id>.md
• Cursor - .cursor/rules/<id>.mdc
• Windsurf - .windsurf/rules/<id>.md
• Aider - .aider/skillsync/<id>.md (add via --read / .aider.conf.yml)

Development

# Install dependencies
pnpm install

# Build
pnpm build

# Run tests
pnpm test

# Type check
pnpm typecheck

# Lint
pnpm lint

License

MIT