Skill Sync

Skill Sync

When To Use

Use this skill when the user wants to:

• scan local skills across Codex, Claude, Hermes, OpenClaw, OpenCode, workspace ./skills, and shared roots
• see which skills are shared, duplicate, compatible, specific, or mixed
• check skill drift: which skills are still pristine, which are dirty (locally edited), which are local-only
• choose one canonical source and replace duplicate copies with symlinks
• preview or apply convergence onto one preferred root such as ~/.agents/skills
• export a portable layout manifest and import the same topology on another machine
• restore a previous dedupe or import run

Typical trigger phrases: "sync my skills", "同步我的 skills", "check skill drift", "检查 skill 漂移", "dedupe my skills", "skill 大扫除", "audit my skill installs".

Do not use this skill when:

• the task is only about one host and no cross-host comparison or symlink management is needed
• the user wants to install a brand-new skill from a catalog or registry (that is distribution, e.g. carl-skills; skill-sync manages local copies after installation)
• the user wants to edit the content of a single skill

Fast Path

Scan the machine and get the hygiene score plus recommended actions:

python3 scripts/skill_sync.py

List only shared and host-specific skills:

python3 scripts/skill_sync.py --status shared,specific --list-names

Record the current state as the pristine baseline (do this once after installing skills):

python3 scripts/skill_sync.py --record-baseline

Check drift against the recorded baseline (report-only, never mutates):

python3 scripts/skill_sync.py --check-drift

Inspect one conflicting portable skill:

python3 scripts/skill_sync.py --diff rapid-ocr

Preview safe dedupe:

python3 scripts/skill_sync.py --dedupe --strategy strict

Preview a single-root convergence plan:

python3 scripts/skill_sync.py --adopt-root agents

Apply convergence with backups:

python3 scripts/skill_sync.py --adopt-root agents --apply

Restore the latest run:

python3 scripts/skill_sync.py --restore latest
python3 scripts/skill_sync.py --restore latest --apply

Workflow

1. Scan first. Run python3 scripts/skill_sync.py and read the hygiene score and recommended actions.
2. Record a baseline when the setup is in a known-good state. Run --record-baseline so future runs can tell pristine copies from local edits.
3. Check drift before touching anything. Run --check-drift and review every dirty skill with --diff <skill> before deciding what wins.
4. Review risky groups before mutation. Use --status compatible --list-names, --status mixed --list-names, and --diff <skill>.
5. Preview convergence. Use --dedupe --strategy strict for identical groups, or --adopt-root <platform> to converge around one root.
6. Apply only when the plan looks right. Add --apply to execute symlink creation or replacement. Dirty copies are skipped unless the user explicitly confirms with --allow-dirty.
7. Export or import machine layouts when needed. Use --export-manifest and --import-manifest for cross-machine reuse.
8. Restore from backup if needed. Use --restore <run-id|latest> and add --apply to roll back.

Drift Model

Once a baseline is recorded (~/.skill-sync/baselines.json), every skill falls into one of three states:

• pristine: every portable copy matches the recorded baseline. Safe to dedupe or replace with a newer version.
• dirty: at least one copy differs from the baseline. The user edited it locally. Never overwrite without showing the diff and getting explicit confirmation (--allow-dirty).
• local-only: no baseline recorded. Treat as the user's original work: back it up, never auto-overwrite, never assume an upstream exists.

After the user reviews a dirty skill and decides the local version is the new truth, re-run --record-baseline --skill <name> to accept it as the new pristine state.

Safety Rules

• The script always scans and reports before mutation.
• --check-drift and --record-baseline never modify any skill; they only read and write ~/.skill-sync/baselines.json.
• It only auto-links portable directory-based skills that contain SKILL.md.
• It never overwrites an existing destination without first moving it into ~/.skill-sync/backups/<run-id>/originals/....
• It never replaces a dirty copy (one that differs from its recorded baseline) unless --allow-dirty is passed after the user reviewed the diff.
• --strategy strict only dedupes identical portable skills.
• --strategy prefer-latest and --strategy trust-high may select the newest portable copy when content differs.
• --restore latest --apply replays the last backup manifest in reverse.
• This skill never installs hooks, cron jobs, or scheduled tasks on its own. If the user wants a recurring drift check, point them to the hook recipe in the README and let them configure it themselves.

Roots Scanned

• <current-workdir>/skills
• ~/.codex/skills
• ~/.agents/skills
• ~/.claude/skills
• ~/.hermes/skills
• ~/.claude/skills/anthropic-skills/skills
• ~/.config/opencode/skills
• ~/.openclaw/skills
• ~/.openclaw/extensions/*/skills

Status Model

• shared: the same real directory is visible from multiple hosts, usually through symlinks
• duplicate: multiple hosts have the same portable skill content, but not via the same real path yet
• compatible: multiple hosts have portable SKILL.md skills with the same name, but different content
• specific: the skill appears on only one host
• mixed: the same skill name exists on multiple hosts, but with different formats or incompatible content

If you need the detection details or compatibility notes, read references/compatibility.md.