skill-sync
After improving skills locally across multiple sessions, pushing changes back to GitHub means cloning, diffing, and copying files for every skill. This skill automates that for your entire published portfolio at once.
Quick Start
You: /skill-sync
Claude: Scanning 18 registered skills...
Skill Repo Type Status
---
causal-impact-campaign wan-huiyan/causal-impact-campaign authored IN SYNC
permutation-validation wan-huiyan/permutation-validation authored DIRTY (SKILL.md)
field-notes wan-huiyan/field-notes fork IN SYNC
You: /skill-sync push permutation-validation
Claude: Cloning wan-huiyan/permutation-validation...
Copying SKILL.md...
Committed and pushed: "docs: sync permutation-validation from local skill updates"
Why a Claude Code Skill?
The sync workflow involves cloning repos, diffing tracked files, copying to correct paths (root AND nested skills/ copy), checking the version bump checklist, and pushing — across every dirty skill at once. Claude also handles the judgment calls: which files to track, whether a diff is meaningful, and whether a version bump is needed before pushing. A shell script can clone and copy; it can't read a SKILL.md and decide whether the version number needs bumping.
Installation
Claude Code (plugin install — recommended):
# Add the marketplace, then install the plugin
claude plugin marketplace add wan-huiyan/skill-sync
claude plugin install skill-sync@wan-huiyan-skill-sync
Claude Code (git clone):
git clone https://github.com/wan-huiyan/skill-sync.git ~/.claude/skills/skill-sync
Cursor (2.4+):
# Per-project rule (most reliable)
mkdir -p .cursor/rules
# Copy plugins/skill-sync/SKILL.md content into .cursor/rules/skill-sync.mdc with alwaysApply: true
# Or via npx skills CLI
npx skills add wan-huiyan/skill-sync --global
What You Get
| Command | What it does |
|---|
/skill-sync | Scan all registered skills, show sync status table |
/skill-sync init | Populate registry by matching gh repo list against local ~/.claude/skills/ |
/skill-sync push | Push all dirty authored skills to their GitHub repos |
/skill-sync push <name> | Push a single skill |
How It Works
- Registry (
~/.claude/skill-sync-registry.json) maps local skill directories to GitHub repos
- Init scans your GitHub repos via
gh repo list, matches against installed skills, detects forks vs authored
- Status clones each repo to
/tmp, diffs tracked files against local copies
- Push copies local files to cloned repo, commits, pushes, cleans up
Companion Skills
- publish-skill — First-time publishing (repo creation, README, screenshots, awesome-list). After publishing, run
/skill-sync init to register.
- schliff — Score and improve skill quality before syncing.
- skill-anonymizer — Scan for client-identifying data before pushing. New content added locally may introduce client names, amounts, or domain-specific details.
- data-provenance-verifier — Verify any new data files have provenance documentation before pushing.
Key Design Decisions
- Registry over auto-detection: A JSON registry is explicit and editable, vs scanning
.git/config or plugin.json which may be stale or missing
- Clone-copy-push over local git: Skills installed via
git clone may have dirty working trees, detached HEADs, or stale remotes. Cloning fresh to /tmp avoids all git state issues
- Authored vs fork distinction: Forks get a warning ("consider opening an upstream PR") instead of silent pushes that diverge from upstream
- Version bump checklist absorbed from publish-skill: Keeps all update-related guidance in one place instead of split across two skills
Limitations
- Requires
gh CLI authenticated with push access to your repos
- Does not auto-detect new skills — run
/skill-sync init after using /publish-skill
- Does not handle merge conflicts — if the remote has changes not in your local copy, push will fail and you'll need manual resolution
- Registry is per-machine — not synced across devices
Dependencies
