skill-sync

Skill Sync — Keep Skills in Sync with GitHub

Detect which locally installed skills have drifted from their GitHub repos, then push updates with a single command.

When to Use

• After editing a local skill's SKILL.md, eval-suite.json, or references/
• To check which published skills have unpushed local changes
• To populate the registry after first-time publishing with /publish-skill
• To push accumulated skill updates across multiple repos at once

Companion Skills

• publish-skill — First-time publishing (repo creation, README, screenshots, awesome-list). After publishing, run /skill-sync init to register the new skill.
• 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 that weren't in the original publish.
• data-provenance-verifier — Verify any new data files (CSV, JSON, examples/) have provenance documentation before pushing.

Commands

/skill-sync (default: status)

Scan all registered skills and show a status table:

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
agent-review-panel       wan-huiyan/agent-review-panel      authored  DIRTY (SKILL.md, eval-suite.json)

/skill-sync init

Populate the registry by scanning GitHub repos + local skill directories:

1. Run gh repo list {username} --json name,isFork,url --limit 100
2. Match repo names against ~/.claude/skills/*/ directories
3. For each match, determine tracked files by merging both sources:
   • Local: list files in ~/.claude/skills/{name}/
   • Remote: fetch GitHub repo file listing via gh api repos/{repo}/contents --jq '.[].name'
   • Also check known subdirs on GitHub: references/, skills/{name}/, .claude-plugin/, docs/, tests/
   • Union of all found files = tracked_files (deduplicated, paths relative to repo root)
4. For forks: record upstream via gh repo view {repo} --json parent
5. Write registry to ~/.claude/skill-sync-registry.json

Why merge both sources: A file can exist in the GitHub repo but not locally (e.g. README.md generated by publish-skill but never pulled). Listing only the local dir silently omits these, causing them to never be synced.

/skill-sync push

Push ALL dirty authored skills to their GitHub repos.

/skill-sync push <skill-name>

Push a single skill.

/skill-sync validate or /skill-sync validate <skill-name>

Run the test suite before pushing. Acts as a pre-push quality gate.

For each dirty skill (or the named skill):

1. Check if tests/ directory and package.json exist in the local repo
2. If tests exist: run cd {repo} && npm test
3. If tests pass: report PASS, skill is ready for push
4. If tests fail: report FAIL with failure details, do NOT push
5. If no tests exist: report WARN "No tests found. Run ~/Documents/skill-test-templates/backfill.sh {repo} to generate tests, or push with --no-validate"

/skill-sync backfill-tests

Generate tests for all registered skills that don't have them yet.

For each skill in the registry that has eval-suite.json but no tests/ directory:

1. Run ~/Documents/skill-test-templates/backfill.sh {repo}
2. Run npm test to verify
3. If pass: commit test: add automated test suite + push to default branch
4. If fail: log the failure, skip, report to user

Templates location: ~/Documents/skill-test-templates/

Registry Format

Stored at ~/.claude/skill-sync-registry.json:

{
  "github_username": "wan-huiyan",
  "updated_at": "2026-04-02T10:00:00Z",
  "skills": {
    "causal-impact-campaign": {
      "repo": "wan-huiyan/causal-impact-campaign",
      "type": "authored",
      "tracked_files": ["SKILL.md", "eval-suite.json", "references/code_templates.md"]
    },
    "field-notes": {
      "repo": "wan-huiyan/field-notes",
      "type": "fork",
      "upstream": "wentingwang21/field-notes",
      "tracked_files": ["SKILL.md"]
    }
  }
}

type values:

• authored — user created this skill, push directly
• fork — user forked someone else's skill, warn about upstream PR when pushing

Sync Workflow (per skill)

Detecting drift

For each registered skill:

1. Clone repo to /tmp/skill-sync-{name} (shallow: --depth 1)
2. Compare each tracked file: diff local_file repo_file
3. Report status: IN SYNC, DIRTY (list changed files), or MISSING (local skill deleted)
4. Clean up /tmp clone after comparison

Pushing updates

For each dirty skill:

0. Pre-push validation: If tests/ and package.json exist in the repo, run npm test. If tests fail, stop and report. Skip with --no-validate flag.
1. Clone repo to /tmp/skill-sync-{name} (full clone for committing)
2. Copy tracked files from ~/.claude/skills/{name}/ to the cloned repo:
   • Root copy: SKILL.md → repo root SKILL.md
   • Nested copy: SKILL.md → skills/{name}/SKILL.md (if that path exists in repo)
   • Other files: copy to matching paths in repo
3. git add changed files
4. Commit with message: docs: sync {name} from local skill updates
5. git push origin main
6. Clean up /tmp clone
7. For forks: after pushing, warn: "This is a fork of {upstream}. Consider opening a PR to upstream."

Commit message convention

docs: sync {skill-name} from local skill updates

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Version Bump Checklist

When pushing a version update (not just content edits), ensure ALL copies are consistent:

1. ~/.claude/skills/{name}/SKILL.md — local installed copy (frontmatter version)
2. Repo root SKILL.md — matches local
3. Repo plugins/{name}/SKILL.md — nested/plugin copy (often forgotten, diverges silently)
4. .claude-plugin/plugin.json — version field + keywords
5. .claude-plugin/marketplace.json (or root marketplace.json) — version field per plugin entry
6. package.json — version field (if repo has npm tests)
7. eval-suite.json (or plugins/{name}/eval-suite.json) — version field
8. README.md — version history table
9. README.md — badge row version (if badges exist)
10. references/changelog.md — per-plugin changelog (if exists)
11. Root CHANGELOG.md — repo-level changelog (if exists alongside references/ copy)
12. ROADMAP.md — version history table (if exists)

Common miss: repos with a plugins/ layout have version in BOTH plugins/{name}/.claude-plugin/plugin.json AND root .claude-plugin/marketplace.json. The eval-suite.json version is also easy to miss — it lives next to SKILL.md but has its own independent version field. Run npm test after bumping — manifest consistency tests will catch any mismatches.

Badge version sync

Dynamic badges (github/v/release, github/license, github/last-commit) auto-update from GitHub API — no action needed on version bump. Just create a new GitHub release:

gh release create v${NEW_VER} --repo ${USERNAME}/${SKILL_NAME} \
  --title "v${NEW_VER}" --notes "Release notes here"

Static badges (eval assertions, papers, python version) need manual update:

# Update eval assertion count if eval-suite.json changed
ASSERTION_COUNT=$(python3 -c "import json; print(len(json.load(open('eval-suite.json')).get('assertions',[])))" 2>/dev/null)
if [ -n "$ASSERTION_COUNT" ]; then
  sed -i '' "s|badge/eval_assertions-[0-9]*_passed|badge/eval_assertions-${ASSERTION_COUNT}_passed|g" README.md
fi

# Update paper count if bibliography changed
PAPER_COUNT=$(grep -c '^\- \[' references/bibliography.md 2>/dev/null)
if [ -n "$PAPER_COUNT" ]; then
  sed -i '' "s|badge/grounded_in-[0-9]*%2B_papers|badge/grounded_in-${PAPER_COUNT}%2B_papers|g" README.md
fi

Detecting badge type: Dynamic badges contain github/v/release or github/license in the URL. Static badges contain badge/version- or badge/license-. If a repo still uses static version/license badges, suggest upgrading to dynamic ones.

Verify no stale version strings remain:

grep -rn "old_version" /tmp/skill-sync-{name}/

Common failure modes

• tracked_files missing GitHub-only files — init scanned only local dir; files created by publish-skill (README.md, marketplace.json, etc.) that were never pulled locally will be silently omitted. Fix: re-run /skill-sync init (which now merges local + remote) or manually add to registry.
• README and .claude-plugin/ lag behind SKILL.md — always update all in one commit
• Nested skills/ copy forgotten — diverges silently from root copy. The sync workflow copies to both locations automatically.
• Installed ~/.claude/skills/ copy N versions behind — if more than 1 version behind, do a full overwrite rather than incremental patching
• Metadata updated but SKILL.md forgotten — bump SKILL.md frontmatter version FIRST, then propagate to metadata. A repo where plugin.json says v1.5 but SKILL.md says v1.0 signals broken process.

Error Handling

• If gh CLI not authenticated: report error, suggest gh auth login
• If repo not found on GitHub: suggest running /publish-skill first
• If local skill directory missing: mark as MISSING in status, suggest removing from registry
• If push fails (permissions, conflicts): report error, suggest manual resolution
• If registry doesn't exist: suggest running /skill-sync init

Scope Boundaries

• Use this skill for ongoing sync of already-published skills
• Do NOT use for first-time publishing (use publish-skill), creating skills (use skill-creator), or improving quality (use schliff)
• Hand off to publish-skill if the skill has no GitHub repo yet

When NOT to sync: same name but divergent ON PURPOSE

Sync assumes two same-named copies should be identical and will overwrite one with the other. That's wrong when the two copies are meant to differ — e.g. a general skill in ~/.claude/skills/<name> and a domain-specialized fork published in a marketplace repo (different framing, examples, trigger scope). Syncing would clobber the specialization.

The fix is not to sync them — give them distinct names. Two skills with the same name but different bodies is a latent bug regardless of sync:

• Registry collision on install. Once the marketplace copy is /plugin install-ed while the personal copy exists, both land under one identifier — ambiguous which loads when invoked.
• claudeception dedupes by name — a future session treats them as one skill and may "update" the wrong copy.
• This skill's own drift detector flags them as out-of-sync forever.

So: a specialization gets its own name + a bidirectional See also cross-ref to the general one (e.g. code-reviewer-subagent-no-bash-blocked-on-pr-diff general ↔ overnight-review-panel-blocked-reviewer-reads-as-clean overnight). Mirrors the subagent-driven-development ↔ subagent-review-tier-calibration-for-overnight-pr-chains pattern. For which repo a skill should live in and copy-vs-cross-link, see skill-portfolio-repo-placement-scan. Only sync copies that are genuinely the SAME skill.