name: skill-sync description: This skill should be used when the user asks to "sync skills", "set up skill-sync", "check skill status", "validate skills", "preview skill changes", "diagnose skills", "pin a skill", "unpin a skill", "prune skills", or "promote skill changes". version: 0.1.0 tools: Bash, Read, Write, Edit

skill-sync Workflow

Manage AI agent skills across projects — sync, validate, and maintain shared skill libraries.

Project Configuration

skill-sync uses skill-sync.yaml at the project root as the manifest. Run skill-sync doctor to check configuration health.

Key files:

• skill-sync.yaml — manifest: sources, skills, targets, install mode, config overrides
• skill-sync.lock — integrity checksums (auto-generated)
• skill.yaml — per-skill package descriptor (inside each skill directory)
• skill-sync.config.yaml — merged runtime config (auto-generated in each target directory)

Repo Hygiene

Treat synced skill directories and generated sync artifacts as repository content unless they are explicitly ignored by .gitignore.

• Before skill-sync sync begins, check git status --short.
• If skill directories, skill-sync.yaml, skill-sync.lock, or generated skill-sync.config.yaml files have uncommitted changes and those paths are not ignored by .gitignore, stop and get them committed before syncing.
• After skill-sync sync ends, review the tracked changes it produced and commit them before moving on to unrelated work.
• If a skill path should stay local-only, add it to .gitignore before syncing rather than leaving it dirty.

Actions

Setup

Input: Empty (auto-detect), or project path

Bootstraps skill-sync in a project that already has skills but no skill-sync.yaml.

Steps:

1. Check for skill-sync installation:

   skill-sync --version
   

   If not found, instruct the user to install: npm install -g skill-sync

2. Scan for existing skill directories:

   find .claude/skills -name "SKILL.md" -maxdepth 3 2>/dev/null
   find .codex/skills -name "SKILL.md" -maxdepth 3 2>/dev/null
   

3. Detect sources without assuming a machine-global path:

   • inspect the discovered project-local skill directories first
   • if an existing skill-sync.yaml or other project config is present, reuse its declared sources
   • if the upstream source cannot be inferred from the repo itself, ask the user which shared directory or repository should back the generated manifest

4. Generate skill-sync.yaml manifest with discovered skills, sources, and targets. Use mirror as the default install mode. Include all target directories found (.claude/skills, .codex/skills).

5. Run initial sync to establish the lock file:

   skill-sync sync --dry-run --json
   

   Show the plan to the user. If approved:

   skill-sync sync
   

6. Verify setup:

   skill-sync doctor --json
   

Sync

Input: Empty, --dry-run, --force, or --json

skill-sync sync              # Resolve, plan, apply
skill-sync sync --dry-run    # Preview without applying
skill-sync sync --force      # Override conflict checks
skill-sync sync --json       # Machine-readable output

Behavior:

• Resolves skills from sources in manifest order (first match wins)
• Follows transitive dependencies from skill.yaml
• Detects drift and reports conflicts before overwrite
• Materializes to all configured targets
• Updates skill-sync.lock and generates skill-sync.config.yaml
• Requires commit hygiene: unless managed skill paths are ignored by .gitignore, commit pending skill changes before sync and commit resulting tracked changes after sync

If conflicts are reported, explain the options:

1. skill-sync promote — push local changes upstream first
2. skill-sync sync --force — overwrite local modifications

Status

Input: Empty or --json

skill-sync status            # Human-readable report
skill-sync status --json     # Structured output

Shows per-target: installed skills, install mode, lockfile alignment (clean, modified, missing, extra), file-level drift details.

Validate

Input: Empty, --exit-code, or --json

skill-sync validate                  # Check everything
skill-sync validate --exit-code      # Exit 1 on errors (for CI)
skill-sync validate --json           # Structured output

Checks: manifest structure, source definitions, SKILL.md presence and frontmatter, portability constraints, compatibility declarations, config override validity.

Diff

Input: Empty or --json

skill-sync diff              # Preview what sync would change
skill-sync diff --json       # Structured output

Equivalent to skill-sync sync --dry-run. Shows installs, updates, removals, and conflicts without applying.

Doctor

Input: Empty or --json

skill-sync doctor            # Comprehensive diagnostics
skill-sync doctor --json     # Structured output

Checks: manifest validity, lock file presence, source availability, target directory existence, drift detection, portability validation.

Pin

Input: Skill name (required)

skill-sync pin <skill-name>

Locks a skill to its current git revision. Only works for git sources. Records the commit SHA in skill-sync.yaml overrides so future syncs use that exact revision.

Unpin

Input: Skill name (required)

skill-sync unpin <skill-name>

Removes a revision pin, allowing the skill to float and receive updates on future syncs.

Prune

Input: Empty, --dry-run, or --json

skill-sync prune             # Remove undeclared skills
skill-sync prune --dry-run   # Preview what would be removed

Removes installed skills not declared in the manifest, including untracked directories in targets that are not in the lock file.

Promote

Input: Empty or --json

skill-sync promote           # Show promotion guidance
skill-sync promote --json    # Structured output

In v0, promotion is a manual workflow:

1. skill-sync status — identify modified skills
2. skill-sync diff — review changes
3. Copy modified files from target directory back to source
4. skill-sync sync — confirm source and target are in sync

Global Flags

All commands support:

Output Format

## skill-sync {Action}

### Summary
{what was done}

### Details
{action-specific content — plan, diagnostics, validation results}

### Status
- Installed: X skills
- Updated: Y skills
- Conflicts: Z (if any)

### Next Steps
- {recommendation}