Skill Sync

Skill Sync

Use skill-sync as the default interface for local skill-harness maintenance.

Core Workflow

1. Inspect harness detection and discovered skill sources.
2. Run a doctor pass before making changes.
3. Create a backup before risky cleanup or restore work.
4. Execute or restore.
5. Verify the resulting symlinks or restored content.

Start with:

skill-sync harnesses
skill-sync sources
skill-sync doctor
skill-sync doctor --verbose

Apply changes:

skill-sync execute
skill-sync sync

Or explicitly:

skill-sync execute

Backup Workflow

Create a backup:

skill-sync backup create

List backups:

skill-sync backup list

Dry-run a restore:

skill-sync backup restore <backup-id> --dry-run

Restore:

skill-sync backup restore <backup-id>

Agent-Friendly Usage

Use JSON when the output will be consumed by another tool or agent:

skill-sync doctor --json
skill-sync sources --json
skill-sync harnesses --json
skill-sync execute --json

Bare skill-sync prints a high-signal landing/help view. Default human output is concise. Add --verbose when you need the full per-entry plan and orphan listing.

Safety Rules

• Prefer doctor before execute.
• If doctor reports a conflict due to an existing unmanaged install (common case: a skill folder already exists in a harness root like ~/.hermes/skills/<skill>), resolve by either:
  • removing the unmanaged directory/file and re-running execute, or
  • restoring via skill-sync backup restore <backup-id>. Do not leave mixed symlink + real directories behind.
• Use --home for isolated testing against a fake home directory.
• Use --projects-root when you need to constrain discovery to a specific source tree.
• Project-root sources are authoritative. Harness-installed skills act as fallback sources when no project-root source exists for the same slug.
• If a harness-native skill should not fan out globally, add skill-sync-scope: local-only to its frontmatter. Use skill-sync-install-on: [harness-a, harness-b] for explicit multi-harness targeting.

Source: light-merlin-dark/skill-sync — distributed by TomeVault.