@skill-kit/sync

Cross-device Skill synchronization with cloud backends for Skill Kit.

Features

• Push local skills to cloud storage
• Pull skills from cloud to local
• Conflict detection and resolution (local-wins, remote-wins, latest-wins, manual)
• Offline queue for operations when network is unavailable
• Multiple backend support (Supabase, GitHub Gist)
• Selective sync with glob patterns
• Incremental sync based on content hash

Installation

npm install @skill-kit/sync
# or
pnpm add @skill-kit/sync

CLI Usage

Push Skills

# Push all skills to cloud
skill-sync push

# Push with options
skill-sync push --dir ~/.skill-kit/skills --force --dry-run

# Push specific skills
skill-sync push --include "workflow-*.md"

# Use GitHub Gist backend
skill-sync push --backend github-gist

Pull Skills

# Pull all skills from cloud
skill-sync pull

# Pull with conflict resolution
skill-sync pull --conflict latest-wins

# Force overwrite local
skill-sync pull --force

# Delete local skills not in remote
skill-sync pull --delete

Check Status

# Show sync status
skill-sync status

# JSON output
skill-sync status --json

Manage Offline Queue

# List queued operations
skill-sync queue --list

# Process queue
skill-sync queue --flush

# Clear queue
skill-sync queue --clear

Programmatic Usage

import { SyncEngine, createBackend, push, pull, syncStatus } from '@skill-kit/sync';

// Create and authenticate backend
const backend = createBackend('supabase');
await backend.authenticate({
  type: 'supabase',
  url: process.env.SUPABASE_URL,
  key: process.env.SUPABASE_KEY,
});

// Push skills
const pushResult = await push(backend, {
  skillsDir: '~/.skill-kit/skills',
  force: false,
  dryRun: false,
});

// Pull skills
const pullResult = await pull(backend, {
  skillsDir: '~/.skill-kit/skills',
  force: false,
});

// Check status
const status = await syncStatus(backend, {
  skillsDir: '~/.skill-kit/skills',
});

console.log(`Synced: ${status.synced}`);
console.log(`Modified locally: ${status.modifiedLocal}`);
console.log(`Conflicts: ${status.conflicts}`);

Environment Variables

Supabase Backend

SUPABASE_URL=https://your-project.supabase.co
SUPABASE_KEY=your-anon-key
# Optional user auth
[email protected]
SUPABASE_PASSWORD=password

GitHub Gist Backend

GITHUB_TOKEN=ghp_your_token
# Optional: specify existing gist
GITHUB_GIST_ID=abc123

Configuration

Add to your .skillkitrc.json:

{
  "sync": {
    "provider": "supabase",
    "autoSync": false
  }
}

Conflict Resolution Strategies

| Strategy | Behavior | | ------------- | ----------------------------------------- | | local-wins | Always keep local version | | remote-wins | Always keep remote version | | latest-wins | Keep the most recently modified version | | manual | Skip conflicts, require manual resolution |

API Reference

SyncEngine

const engine = new SyncEngine(backend, config);
await engine.push(options);
await engine.pull(options);
await engine.status();

Backends

// Supabase
const supabase = new SupabaseBackend();
await supabase.authenticate({ type: 'supabase', url, key });

// GitHub Gist
const gist = new GitHubGistBackend();
await gist.authenticate({ type: 'github', token });

OfflineQueue

const queue = new OfflineQueue();
await queue.load();

await queue.enqueue('push', skill);
await queue.flush();

License

MIT