skillsyncai

v1.0.0

Published

2 months ago

The package manager for AI IDE + CLI intelligence

0High
0Medium
0Low

sourojitd

ai skills sync vscode cursor windsurf claude

The Problem

Every AI-powered IDE and CLI stores its intelligence in a different place:

Windsurf        →  .windsurf/rules/    .windsurf/skills/    .windsurf/workflows/
VS Code/Copilot →  .github/instructions/    .github/prompts/    .github/agents/
Claude Code     →  .claude/commands/    .claude/skills/
Devin           →  .devin/skills/

If your team uses more than one tool, you're copy-pasting files, writing glue scripts, and praying nothing drifts.

SkillSync fixes this. Store artifacts in one GitHub repo (or local folder), and SkillSync distributes them to every tool — with smart merging, caching, and conflict resolution.

✨ Features

 Quick Start

Option 1 — VS Code / Windsurf Extension

Install the .vsix from Releases
Open the SkillSync sidebar panel
Enter your artifact repo URL and pick your targets
Click Sync Now

Option 2 — CLI

npm install -g skillsyncai
skillsync config init      # creates .skillsync.yml
skillsync sync              # syncs everything

 Architecture

graph TB
    subgraph Interface["&#x1F310; Interface Layer"]
        CLI["CLI<br/><sub>commander.js</sub>"]
        EXT["VS Code Extension<br/><sub>webview + sidebar</sub>"]
        API["Library API<br/><sub>TypeScript</sub>"]
    end

    subgraph Engine["&#x2699; Orchestration"]
        SE["Sync Engine"]
        CM["Config Manager"]
    end

    subgraph Core["&#x1F527; Core Services"]
        GH["GitHub Client<br/><sub>retry + rate limiting</sub>"]
        CA["Cache<br/><sub>SHA-256 + atomic writes</sub>"]
        LG["Logger<br/><sub>chalk</sub>"]
    end

    subgraph Adapters["&#x1F50C; Adapters"]
        WS["Windsurf<br/><code>.windsurf/</code>"]
        VS["VS Code / Copilot<br/><code>.github/</code>"]
        CL["Claude Code<br/><code>.claude/</code>"]
        DV["Devin<br/><code>.devin/</code>"]
    end

    CLI --> SE
    EXT --> SE
    API --> SE
    SE --> CM
    SE --> GH
    SE --> CA
    SE --> LG
    SE --> WS
    SE --> VS
    SE --> CL
    SE --> DV

    style Interface fill:#1e1b4b,stroke:#6366f1,color:#e0e7ff
    style Engine fill:#1e1b4b,stroke:#8b5cf6,color:#e0e7ff
    style Core fill:#1e1b4b,stroke:#22d3ee,color:#e0e7ff
    style Adapters fill:#1e1b4b,stroke:#34d399,color:#e0e7ff

Sync Flow

sequenceDiagram
    participant U as User / Extension
    participant SE as Sync Engine
    participant GH as GitHub Client
    participant CA as Cache
    participant AD as Adapter

    U->>SE: sync(targets, options)
    SE->>GH: Fetch artifact tree
    GH-->>SE: File list + content
    SE->>CA: Compare SHA-256 hashes
    CA-->>SE: Changed files only
    loop For each target
        SE->>AD: Write files (merge/overwrite/skip)
        AD-->>SE: Result summary
    end
    SE->>CA: Update cache hashes
    SE-->>U: SyncResult

Data Flow

flowchart LR
    A["&#x1F4E6; GitHub Repo<br/><sub>or local folder</sub>"] -->|fetch| B["&#x1F504; Sync Engine"]
    B -->|diff| C["&#x1F4BE; Cache"]
    B -->|route| D["&#x1F50C; Adapters"]
    D --> E["&#x1F30A; .windsurf/"]
    D --> F["&#x1F4BB; .github/"]
    D --> G["&#x1F4AC; .claude/"]
    D --> H["&#x1F916; .devin/"]

 Repository Layout

Your central artifacts repo should be organized like this:

my-ai-artifacts/
│
├── .windsurf/
│   ├── rules/                         # Coding rules & guidelines
│   ├── skills/                        # Reusable AI skills
│   └── workflows/                     # Multi-step workflows (YAML)
│
├── .github/
│   ├── instructions/                  # Copilot coding instructions
│   │   └── typescript.instructions.md
│   ├── prompts/                       # Copilot prompt files
│   │   └── review.prompt.md
│   └── agents/                        # Copilot agent definitions
│
├── .claude/
│   ├── commands/                      # Claude Code slash commands
│   └── skills/                        # Claude Code skills
│
└── .devin/
    └── skills/                        # Devin automation skills

See test-artifacts/ for a working example with real files.

 VS Code / Windsurf Extension

The extension gives you a full GUI right inside your editor.

Settings

| Setting | Description | |:--------|:------------| | Source | Public repo URL, private repo URL + PAT, or local folder path | | Targets | Toggle each target: Windsurf, VS Code/Copilot, Claude Code, Devin | | Strategy | merge (default) · overwrite · skip-existing | | Sync on Startup | Auto-sync when the editor opens | | Sync Interval | Periodic sync in minutes (0 = disabled) |

Commands

| Command | Shortcut | Description | |:--------|:---------|:------------| | SkillSync: Sync All | — | Sync all enabled targets | | SkillSync: Sync Target... | — | Pick a single target to sync | | SkillSync: Show Status | — | Last sync time, cache stats, target status | | SkillSync: Detect Environments | — | Scan for installed IDEs and CLIs | | SkillSync: Open Config | — | Open the config file | | SkillSync: Clean Cache | — | Clear the local sync cache |

 CLI Reference

`skillsync sync`

skillsync sync [options]

| Flag | Description | |:-----|:------------| | --target <name> | Sync only one target (windsurf vscode claude devin) | | --force | Force overwrite, ignoring cache | | --dry-run | Preview changes without writing to disk | | --verbose | Show file-level details | | --strategy <s> | Override merge strategy | | --categories <c> | Filter by category (e.g. skills,prompts) |

$ skillsync sync --verbose

SkillSync AI v1.0.0
Source: github.com/team/ai-artifacts (main)

Fetching artifacts...
  Found 12 files across 4 targets

  Windsurf (.windsurf/)
    + rules/typescript-best-practices.md
    + rules/code-review-checklist.md
    + rules/git-commit-standards.md

  VS Code / Copilot (.github/)
    + instructions/typescript.instructions.md
    + prompts/review.prompt.md
    + prompts/test.prompt.md

  Claude Code (.claude/)
    + commands/review-code.md
    + commands/generate-tests.md
    + skills/api-design-patterns.md

  Devin (.devin/)
    + skills/debugging-workflow.md
    + skills/project-setup.md

Sync complete! 12 files across 4 targets in 847ms

$ skillsync sync --target=claude --force

$ skillsync sync --dry-run

`skillsync detect`

$ skillsync detect

Detected environments:
  ✓ Windsurf       /Applications/Windsurf.app
  ✓ VS Code        /Applications/Visual Studio Code.app
  ✓ Claude Code    /usr/local/bin/claude
  ✓ Devin          ~/.local/share/devin

`skillsync status`

$ skillsync status

SkillSync Status
  Last sync:   2 minutes ago
  Source:      github.com/team/ai-artifacts
  Strategy:    merge
  Cache:       12 files (48 KB)

Targets:
  ● Windsurf        synced    3 files
  ● VS Code/Copilot synced    3 files
  ● Claude Code     synced    3 files
  ● Devin           synced    2 files

`skillsync config`

| Subcommand | Description | |:-----------|:------------| | init | Create .skillsync.yml in the current directory | | show | Display resolved configuration | | set <key> <value> | Set a config value | | path | Print config file locations |

`skillsync clean`

skillsync clean --confirm

 Sync Strategies

graph LR
    subgraph Merge["&#x1F91D; merge — default"]
        M1["Write new files"]
        M2["Update changed files"]
        M3["Preserve local-only"]
        M4["Log conflicts"]
    end

    subgraph Overwrite["&#x1F4E5; overwrite"]
        O1["Backup existing"]
        O2["Replace all managed"]
        O3["Exact remote state"]
    end

    subgraph Skip["&#x1F6E1; skip-existing"]
        S1["Write new files only"]
        S2["Never touch existing"]
        S3["Safe onboarding"]
    end

    style Merge fill:#1e1b4b,stroke:#34d399,color:#e0e7ff
    style Overwrite fill:#1e1b4b,stroke:#fbbf24,color:#e0e7ff
    style Skip fill:#1e1b4b,stroke:#22d3ee,color:#e0e7ff

| Strategy | Behavior | |:---------|:---------| | merge | Write new files, update changed files with content-aware merging, preserve local-only files. Deep JSON/YAML key-level merge. Default and recommended. | | overwrite | Replace all managed files with remote versions. Creates timestamped backups first. Best for CI/CD. | | skip-existing | Only write files that don't already exist locally. Great for onboarding new team members. |

How merging works

| File type | Strategy | |:----------|:---------| | Markdown / text | SHA-256 hash comparison. Remote wins if local unchanged since last sync. Both changed = local preserved + conflict logged. | | JSON | Deep key-level merge. Remote keys added/updated; local-only keys preserved. | | YAML | Same deep-merge logic with YAML-specific parsing and serialization. |

⚙ Configuration

Project config — `.skillsync.yml`

repo:
  owner: your-org
  repo: ai-artifacts
  branch: main

targets:
  windsurf:  { enabled: true,  strategy: merge }
  vscode:    { enabled: true,  strategy: merge }
  claude:    { enabled: true,  strategy: merge }
  devin:     { enabled: true,  strategy: merge }

syncInterval: 30        # minutes (0 to disable)
syncOnStartup: true

Global config — `~/.skillsync/config.yml`

User-wide defaults applied when no project config exists.

Resolution order

CLI flags  →  Project config  →  Global config  →  Built-in defaults
  (highest)                                           (lowest)

Environment variables

| Variable | Description | |:---------|:------------| | GITHUB_TOKEN | Personal access token for private repos | | SKILLSYNC_CONFIG | Override config file path | | SKILLSYNC_CACHE_DIR | Override cache directory | | SKILLSYNC_LOG_LEVEL | debug · info · warn · error |

 Programmatic API

import { SyncEngine, ConfigManager, AdapterRegistry } from 'skillsyncai';

const config = await ConfigManager.load();
const engine = new SyncEngine(config);

// Sync all targets
const results = await engine.syncAll();

// Sync a specific target
const result = await engine.sync('claude', { force: true });

// Detect installed environments
const detected = await AdapterRegistry.detect();

 Development

git clone https://github.com/sourojitdhua/SkillSync.git
cd SkillSync

npm install
npm run build           # compile TypeScript
npm test                # run tests with Vitest
npm run dev             # watch mode

Building the extension

npm run build
cp -r dist/* extension-pkg/
cd extension-pkg && npx @vscode/vsce package --no-dependencies

Install the resulting .vsix:

windsurf --install-extension extension-pkg/skillsync-ai-1.0.0.vsix
code --install-extension extension-pkg/skillsync-ai-1.0.0.vsix

Project structure

src/
├── index.ts                    # Library entry point
├── cli/index.ts                # CLI (commander)
├── config/index.ts             # Multi-source config manager
├── sync-engine/index.ts        # Main sync orchestrator
├── github-client/index.ts      # GitHub API client
├── cache/index.ts              # Local cache with atomic writes
├── utils/
│   ├── logger.ts               # Chalk-based logger
│   └── environment.ts          # IDE/CLI detection
├── adapters/
│   ├── base.ts                 # Abstract base adapter
│   ├── windsurf.ts             # Windsurf adapter
│   ├── vscode.ts               # VS Code / Copilot adapter
│   ├── claude.ts               # Claude Code adapter (JSON-aware merge)
│   ├── devin.ts                # Devin adapter
│   └── index.ts                # Adapter registry
├── extension/
│   ├── extension.ts            # VS Code extension entry point
│   └── package.json            # Extension manifest
└── types/index.ts              # TypeScript interfaces

欄 Contributing

Contributions are welcome!

Fork the repo
Create a feature branch (git checkout -b feature/my-feature)
Commit your changes
Open a Pull Request