Skill Sync

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

1. Registry (~/.claude/skill-sync-registry.json) maps local skill directories to GitHub repos
2. Init scans your GitHub repos via gh repo list, matches against installed skills, detects forks vs authored
3. Status clones each repo to /tmp, diffs tracked files against local copies
4. 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

• Required: gh CLI (GitHub CLI) — for repo listing, cloning, pushing
• Required: git — for clone, diff, commit, push operations
• Optional: jq — for registry JSON manipulation (falls back to Python)

Quality Checklist

• Detects all skills with matching GitHub repos
• Distinguishes authored vs forked skills
• Shows per-file diff status (not just "dirty")
• Copies to both root and skills/{name}/ paths in repo
• Includes version bump checklist for major updates
• Warns about upstream PRs for forked skills
• Cleans up /tmp clones after operations

Related Skills

• publish-skill — First-time skill publishing (skill-sync is its companion for ongoing maintenance)
• schliff — Score and improve skill quality before syncing
• skill-anonymizer — Scan for client-identifying data before pushing updates
• data-provenance-verifier — Verify data files have provenance documentation

Version History

Version	Date	Changes
1.0.0	2026-04-02	Initial release: init, status, push commands. Registry format. Version bump checklist absorbed from publish-skill.

License

MIT