skill-sync

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

Action	Trigger	Description
setup	"set up skill-sync", "bootstrap skills"	Detect install, scaffold manifest from existing skills
sync	"sync skills", "update skills"	Resolve, plan, and apply skill changes
status	"skill status", "check skills"	Report installed skill health and drift
validate	"validate skills", "check manifest"	Validate manifest, skills, config, compatibility
diff	"preview changes", "what would sync do"	Preview sync changes without applying
doctor	"diagnose skills", "skill health"	Run comprehensive health diagnostics
pin	"pin skill", "lock skill version"	Lock a skill to its current source revision
unpin	"unpin skill", "unlock skill"	Remove a revision pin, allow updates
prune	"prune skills", "remove unused skills"	Remove skills not declared in manifest
promote	"promote changes", "push skill changes"	Guide pushing local modifications upstream

---

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:

Flag	Short	Description
--json	-j	Machine-readable JSON output
--project <path>	-p	Project root (default: current directory)
--help	-h	Show help text

---

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}