@wangkh/skill-sync-cli 0.2.0 → 0.2.2

package/README.md

@@ -233,6 +233,40 @@ stops the batch; `npx @wangkh/skill-sync-cli sync --continue-on-error` attempts
 entries and still exits with a failure status. Use `npx @wangkh/skill-sync-cli sync --dry-run` to
 preview without installing.
 
+Entries that share `source`, `ref`, `agents`, `scope`, and `copy` are installed
+with a single `skills add` call (`--skill name-a name-b`), so the repository is
+fetched once. When a batched call fails, `sync` falls back to installing each
+entry in that batch individually, which identifies the failing name. Failed
+installs are retried up to `--retries <n>` times (default 2) with a short
+backoff; interruptions are never retried.
+
+`sync` records the installed revision per group in
+`~/.config/skill-sync/state.json`. On later runs it checks the remote with
+`git ls-remote` (immutable commit refs need no check) and skips groups whose
+revision and installed files are unchanged, so unchanged skills are not
+downloaded again. If the update check cannot reach the remote but the previous
+install is still present, the current copy is kept. Use `--force` to reinstall
+regardless.
+
+On networks that cannot reach GitHub directly, pass `--github-mirror <url>`
+(or set `SKILL_SYNC_GITHUB_MIRROR`) to route GitHub clones and update checks
+through a mirror:
+
+```bash
+npx @wangkh/skill-sync-cli sync --github-mirror https://gh-proxy.com/
+```
+
+The mirror is injected as a git `insteadOf` rewrite for the commands this tool
+runs, so your global git configuration is not changed. Free public mirrors seen
+working include `https://gh-proxy.com/`, `https://ghproxy.net/`, and
+`https://ghfast.top/`. To speed up the `skills` CLI download itself on a fresh
+machine, configure an npm registry mirror such as `https://registry.npmmirror.com`.
+
+Child `skills` commands run with `DO_NOT_TRACK=1`, so telemetry stays off. A
+known Windows exit crash in the `skills` CLI after a completed install is
+tolerated: when the files are in place, `sync` treats the group as installed
+instead of failing.
+
 For project-scoped skills, set:
 
 ```json
@@ -250,6 +284,21 @@ location. From the target application project, run:
 npx @wangkh/skill-sync-cli sync --config /path/to/my-skills/skills.json
 ```
 
+## Agent Skill
+
+The repository ships an agent skill (`skills/skill-sync/SKILL.md`) that teaches
+an agent how to use this CLI. Install it from the repository:
+
+```bash
+npx skills add yudaiyan/skill-sync-cli
+```
+
+Or declare it in the manifest and let `sync` install it:
+
+```json
+{ "name": "skill-sync", "source": "yudaiyan/skill-sync-cli" }
+```
+
 ## Run Before the First Release
 
 From a source checkout, the following commands work without installing project

package/README.zh-CN.md

@@ -120,6 +120,20 @@ npx --yes skills@1.5.22 add vercel-labs/skills --agent opencode --skill find-ski
 
 两个 `--yes` 分别用于 npx 下载安装工具和 Skills 安装确认。`sync` 会按清单顺序安装；再次运行会重新安装或更新这些条目，可能覆盖目标位置同名 Skill 的内容。从清单移除或禁用一个条目后，已经安装的内容仍会保留。
 
+`source`、`ref`、`agents`、`scope`、`copy` 相同的多个条目会合并成一次 `skills add`（一个 `--skill` 后跟多个名称），仓库只获取一次。合并安装失败时，会回退为逐个安装，便于定位具体失败的条目。
+
+`sync` 会把每个分组的已安装版本记录在 `~/.config/skill-sync/state.json`。之后的运行会用 `git ls-remote` 检查远端版本（固定为 commit SHA 的 `ref` 无需检查），版本和已安装文件都没有变化时跳过该组，不再重复下载。检查更新失败但本地文件仍然存在时，会保留现有安装。需要强制重装时使用 `--force`。
+
+如果所在网络无法直接访问 GitHub，可以用 `--github-mirror <url>`（或环境变量 `SKILL_SYNC_GITHUB_MIRROR`）让 clone 和版本检查走镜像：
+
+```bash
+npx @wangkh/skill-sync-cli sync --github-mirror https://gh-proxy.com/
+```
+
+镜像通过 git 的 `insteadOf` 重写注入，只对本次命令生效，不会修改全局 git 配置。实测可用的免费公益镜像包括 `https://gh-proxy.com/`、`https://ghproxy.net/`、`https://ghfast.top/`。新机器上如果 `skills` CLI 下载慢，可以配置 npm 镜像源 `https://registry.npmmirror.com`。
+
+wrapper 会以 `DO_NOT_TRACK=1` 运行 `skills` CLI（关闭遥测）。它在 Windows 上安装完成后偶发退出崩溃（0xC0000409）；只要文件已就位，`sync` 会把该组视为安装成功，不再误判失败。
+
 只预览，或者在单个 Skill 失败后继续处理其他条目：
 
 ```bash
@@ -129,6 +143,8 @@ npx @wangkh/skill-sync-cli sync --continue-on-error
 
 默认遇到安装失败就停止并返回非零退出码。使用 `--continue-on-error` 后会继续执行，其间发生失败仍返回非零退出码。
 
+失败的安装会自动重试，默认 2 次并带有短暂退避；可以用 `--retries <n>` 调整次数，`--retries 0` 表示不重试。中断信号不会被重试。
+
 使用 `scope: "project"` 时，安装目标是运行命令的目录，与清单所在目录相互独立。在目标应用项目目录运行：
 
 ```bash
@@ -172,6 +188,20 @@ Git 负责在机器之间传递清单，`sync` 根据本地清单安装 Skills
 
 清单是这个脚本定义的格式；脚本读取后逐项调用官方 `skills` CLI。上游的 `.skill-lock.json` 继续由官方 CLI 维护。
 
+## 给 agent 用的 skill
+
+仓库自带一个 agent skill（`skills/skill-sync/SKILL.md`），用来告诉 agent 如何使用本 CLI。可以直接安装：
+
+```bash
+npx skills add yudaiyan/skill-sync-cli
+```
+
+也可以加进清单，交给 `sync` 安装：
+
+```json
+{ "name": "skill-sync", "source": "yudaiyan/skill-sync-cli" }
+```
+
 ## 发布前使用
 
 获取项目源码后，可以在源码目录直接运行，无需安装项目依赖：

package/bin/skill-sync.mjs

@@ -28,7 +28,9 @@ Options:
   --from <url>             Initialize from a remote manifest URL (init only)
   --dry-run               Print commands without downloading anything
   --continue-on-error     Continue after a skill installation fails
-  --force                 Replace the selected manifest with init
+  --retries <n>           Retry each failed install up to n times (default 2)
+  --github-mirror <url>   Clone GitHub sources through a mirror (sync only)
+  --force                 Replace the selected manifest with init, or reinstall with sync
   -h, --help              Show this help
   -v, --version           Show the version
 
@@ -64,6 +66,16 @@ function parseArgs(argv) {
       options.dryRun = true
     } else if (arg === "--continue-on-error") {
       options.continueOnError = true
+    } else if (arg === "--retries" || arg.startsWith("--retries=")) {
+      if (options.retries !== undefined) {
+        throw new Error("Specify --retries only once")
+      }
+      const inline = arg.startsWith("--retries=")
+      const value = inline ? arg.slice("--retries=".length) : argv[++index]
+      if (value === undefined || !/^\d+$/.test(value)) {
+        throw new Error("--retries requires a non-negative integer")
+      }
+      options.retries = Number(value)
     } else if (arg === "--force") {
       options.force = true
     } else if (arg === "--config" || arg === "-c" || arg.startsWith("--config=")) {
@@ -76,6 +88,16 @@ function parseArgs(argv) {
         throw new Error("--config requires a file path")
       }
       options.configFile = value
+    } else if (arg === "--github-mirror" || arg.startsWith("--github-mirror=")) {
+      if (options.githubMirror !== undefined) {
+        throw new Error("Specify --github-mirror only once")
+      }
+      const inline = arg.startsWith("--github-mirror=")
+      const value = inline ? arg.slice("--github-mirror=".length) : argv[++index]
+      if (value === undefined || value.trim() === "" || (!inline && value.startsWith("-"))) {
+        throw new Error("--github-mirror requires a URL")
+      }
+      options.githubMirror = value
     } else if (arg === "--from" || arg.startsWith("--from=")) {
       if (options.from !== undefined) {
         throw new Error("Specify --from only once")
@@ -132,7 +154,10 @@ async function main() {
   if (command === "validate") return validateCommand(filename)
   if (command === "plan") return planCommand(filename)
   if (command === "sync") {
-    return syncCommand(filename, options)
+    return syncCommand(filename, {
+      ...options,
+      githubMirror: options.githubMirror ?? process.env.SKILL_SYNC_GITHUB_MIRROR,
+    })
   }
 
   throw new Error(`Unknown command: ${command}`)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wangkh/skill-sync-cli",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Sync declared agent skills across machines through the skills CLI",
   "author": "wkh",
   "repository": {
@@ -11,7 +11,14 @@
   "bugs": {
     "url": "https://github.com/yudaiyan/skill-sync-cli/issues"
   },
-  "keywords": ["skills", "agent-skills", "cli", "dotfiles", "opencode", "codex"],
+  "keywords": [
+    "skills",
+    "agent-skills",
+    "cli",
+    "dotfiles",
+    "opencode",
+    "codex"
+  ],
   "type": "module",
   "bin": {
     "skill-sync-cli": "bin/skill-sync.mjs"
@@ -20,6 +27,7 @@
     "bin",
     "src",
     "schemas",
+    "skills",
     "README.md",
     "README.zh-CN.md",
     "RELEASING.md",

package/skills/skill-sync/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: skill-sync
+description: >-
+  Manage the user's portable agent-skill manifest with the skill-sync CLI
+  (@wangkh/skill-sync-cli). Use when the user wants to sync, back up, or
+  restore agent skills across machines ("同步我的 skills", "恢复 skill 环境",
+  "新电脑安装 skills"), add or remove a skill in their manifest
+  ("把 skill 加到清单"), preview or validate the manifest, or install skills
+  when GitHub is unreachable. Also use when a skill installation fails and the
+  user asks why or how to retry.
+---
+
+# skill-sync
+
+`@wangkh/skill-sync-cli` keeps a portable JSON manifest of third-party agent
+skills and installs them through the official `skills` CLI. The manifest is the
+single source of truth; the tool only writes it during `init`.
+
+## When to use
+
+- Sync or restore skills on a machine: `sync`
+- Add a skill to the manifest after finding it: edit the manifest, then `sync`
+- Preview or validate before installing: `plan`, `validate`
+- GitHub is blocked or slow: run `sync --github-mirror https://gh-proxy.com/`
+- An install failed: check retries, the mirror, or `--continue-on-error`
+
+## Commands
+
+Run through npx so no global install is needed:
+
+```bash
+npx @wangkh/skill-sync-cli init      # create the manifest (keeps an existing one)
+npx @wangkh/skill-sync-cli path      # print the manifest path in use
+npx @wangkh/skill-sync-cli validate  # parse and validate without network
+npx @wangkh/skill-sync-cli plan      # print the exact skills commands
+npx @wangkh/skill-sync-cli sync      # install or update declared skills
+```
+
+Useful options:
+
+| Option | Meaning |
+| --- | --- |
+| `-c, --config <file>` | Use another manifest file (all commands) |
+| `--from <url>` | `init` from a published manifest URL |
+| `--dry-run` | Preview without installing |
+| `--continue-on-error` | Keep going after a failure; exit code stays non-zero |
+| `--retries <n>` | Retry failed installs (default 2) |
+| `--github-mirror <url>` | Route GitHub clones and update checks through a mirror |
+| `--force` | `init`: replace the file; `sync`: reinstall even if unchanged |
+
+## Manifest
+
+Default location:
+
+- Windows: `%USERPROFILE%\.config\skill-sync\skills.json`
+- macOS/Linux: `~/.config/skill-sync/skills.json`
+
+Skill entries require `name` (the upstream skill name) and `source`
+(`owner/repo`, Git URL, skill URL, or archive). Optional fields are
+`description`, `ref`, `enabled`, `agents`, `scope`, and `copy`; shared
+defaults live under `defaults`, and the `skills` CLI version is pinned under
+`cli`.
+
+To add a skill, append an entry and run `sync`. Confirm the upstream name
+first:
+
+```bash
+npx --yes skills@1.5.22 add <owner>/<repo> --list
+```
+
+## Behavior worth knowing
+
+- Entries sharing `source`, `ref`, `agents`, `scope`, and `copy` install with
+  one `skills add` call; a failed batch falls back to installing each skill.
+- `sync` records revisions in `~/.config/skill-sync/state.json` and skips
+  groups whose revision and installed files are unchanged. `--force`
+  overrides the skip.
+- When the update check cannot reach the remote but the installed copy still
+  exists, `sync` keeps it instead of failing.
+- GitHub unreachable: `--github-mirror https://gh-proxy.com/` (alternatives:
+  `https://ghproxy.net/`, `https://ghfast.top/`). For the `skills` CLI
+  download itself, configure an npm registry mirror such as
+  `https://registry.npmmirror.com`.
+
+## Security
+
+A skill is agent instructions and may run scripts; review third-party skills
+before adding them. Prefer trusted repositories and immutable commit refs.
+
+Full documentation lives in the project README and
+`schemas/skills-sync.schema.json`.

package/src/commands.mjs

@@ -1,5 +1,7 @@
 import { access, mkdir, writeFile } from "node:fs/promises"
+import os from "node:os"
 import path from "node:path"
+import { setTimeout as sleep } from "node:timers/promises"
 import {
   readManifest,
   normalizeManifest,
@@ -7,12 +9,31 @@ import {
 } from "./manifest.mjs"
 import {
   commandFor,
+  commandForGroup,
   displayCommand,
+  groupSkills,
   runCommand,
   statusCode,
 } from "./runner.mjs"
+import { mirrorGitEnv } from "./mirror.mjs"
+import { gitUrlForSource, isCommitSha, probeRevision } from "./revision.mjs"
+import {
+  allInstalled,
+  readState,
+  setStateEntry,
+  stateEntry,
+  stateKey,
+  statePath,
+  writeState,
+} from "./state.mjs"
 import { downloadManifest } from "./remote.mjs"
 
+export const DEFAULT_RETRIES = 2
+const DEFAULT_RETRY_DELAY_MS = 2000
+// The skills CLI occasionally aborts on exit after a completed install on
+// Windows (libuv teardown assertion). These are the observed exit codes.
+const POST_INSTALL_CRASH_CODES = new Set([3221226505, -1073740791])
+
 const SAMPLE_MANIFEST = {
   version: 1,
   cli: {
@@ -47,6 +68,50 @@ export async function validateCommand(manifestFilename) {
   return 0
 }
 
+function sourceLabel(group) {
+  const { source, ref } = group[0]
+  return `${source}${ref ? ` @ ${ref}` : ""}`
+}
+
+function groupLabel(group) {
+  if (group.length === 1) return `[${group[0].name}] ${sourceLabel(group)}`
+  return `[${sourceLabel(group)}] ${group.length} skills: ${group.map((skill) => skill.name).join(", ")}`
+}
+
+function printDescriptions(group) {
+  for (const skill of group) {
+    if (!skill.description) continue
+    console.log(group.length === 1 ? skill.description : `# ${skill.name}: ${skill.description}`)
+  }
+}
+
+function reportFailure(label, result) {
+  if (result.error) console.error(result.error.message)
+  if (result.signal) console.error(`[${label}] terminated by ${result.signal}`)
+  console.error(`[${label}] failed with exit code ${statusCode(result)}`)
+}
+
+function resolveGroupRevision(skills, probe, probeOptions) {
+  const { source, ref } = skills[0]
+  if (isCommitSha(ref)) return { status: "known", revision: ref.toLowerCase() }
+  const url = gitUrlForSource(source)
+  if (!url) return { status: "unknown" }
+  return probe(url, ref, probeOptions)
+}
+
+async function runWithRetries(execute, command, { cwd, env, retries, retryDelayMs, label }) {
+  for (let attempt = 0; ; attempt += 1) {
+    const result = execute(command, { cwd, env })
+    const code = statusCode(result)
+    if (code === 0 || result.signal || attempt >= retries) return result
+
+    const delayMs = retryDelayMs * (attempt + 1)
+    const delayText = delayMs > 0 ? ` in ${Math.round(delayMs / 1000)}s` : ""
+    console.error(`[${label}] attempt ${attempt + 1}/${retries + 1} failed with exit code ${code}; retrying${delayText}`)
+    if (delayMs > 0) await sleep(delayMs)
+  }
+}
+
 export async function planCommand(manifestFilename) {
   const { path: filename, manifest } = await readManifest(manifestFilename)
   const skills = enabledSkills(manifest)
@@ -57,9 +122,11 @@ export async function planCommand(manifestFilename) {
     return 0
   }
 
-  for (const skill of skills) {
-    if (skill.description) console.log(`# ${skill.name}: ${skill.description}`)
-    console.log(displayCommand(commandFor(skill, manifest.cli)))
+  for (const group of groupSkills(skills)) {
+    for (const skill of group) {
+      if (skill.description) console.log(`# ${skill.name}: ${skill.description}`)
+    }
+    console.log(displayCommand(commandForGroup(group, manifest.cli)))
   }
   return 0
 }
@@ -68,36 +135,148 @@ export async function syncCommand(manifestFilename, options = {}) {
   const { path: filename, manifest } = await readManifest(manifestFilename)
   const skills = enabledSkills(manifest)
   const execute = options.run ?? runCommand
-
-  // Resolve the full plan before installing so invalid refs cannot cause a
-  // partially applied manifest.
-  const commands = skills.map((skill) => ({ skill, command: commandFor(skill, manifest.cli) }))
+  const retries = options.retries ?? DEFAULT_RETRIES
+  const retryDelayMs = options.retryDelayMs ?? DEFAULT_RETRY_DELAY_MS
+  const home = options.home ?? os.homedir()
+  const cwd = options.cwd ?? process.cwd()
+  const probe = options.probe ?? probeRevision
+  const gitEnv = mirrorGitEnv(options.githubMirror)
 
   if (skills.length === 0) {
     console.log("No enabled skills.")
     return 0
   }
 
+  // Resolve the full plan before installing so invalid refs cannot cause a
+  // partially applied manifest.
+  const groups = groupSkills(skills).map((group) => ({
+    skills: group,
+    command: commandForGroup(group, manifest.cli),
+  }))
+
+  const stateFilename = options.stateFile ?? statePath(home)
+  const state = await readState(stateFilename)
+
   console.log(`Syncing ${skills.length} skill${skills.length === 1 ? "" : "s"} from ${filename}`)
   let failures = 0
+  let skipped = 0
+  let stopped = false
 
-  for (const { skill, command } of commands) {
-    console.log(`\n[${skill.name}] ${skill.source}${skill.ref ? ` @ ${skill.ref}` : ""}`)
-    if (skill.description) console.log(skill.description)
+  for (const group of groups) {
+    if (stopped) break
 
+    console.log(`\n${groupLabel(group.skills)}`)
     if (options.dryRun) {
-      console.log(displayCommand(command))
+      printDescriptions(group.skills)
+      console.log(displayCommand(group.command))
       continue
     }
 
-    const result = execute(command, { cwd: options.cwd })
-    const code = statusCode(result)
-    if (code !== 0) {
-      failures += 1
-      if (result.error) console.error(result.error.message)
-      if (result.signal) console.error(`[${skill.name}] terminated by ${result.signal}`)
-      console.error(`[${skill.name}] failed with exit code ${code}`)
-      if (result.signal || !options.continueOnError) break
+    const key = stateKey(group.skills)
+    const entry = stateEntry(state, filename, key)
+    const installScope = {
+      global: group.skills[0].scope === "global",
+      cwd,
+      home,
+    }
+    const installedHere = allInstalled(group.skills, installScope)
+    // A completed install followed by the known exit crash counts as success.
+    const executeTolerant = (command, runOptions) => {
+      const result = execute(command, runOptions)
+      if (POST_INSTALL_CRASH_CODES.has(statusCode(result)) && allInstalled(group.skills, installScope)) {
+        console.error(`[${sourceLabel(group.skills)}] the skills CLI crashed after installing (known Windows bug); treating the install as complete`)
+        return { status: 0 }
+      }
+      return result
+    }
+    // Only a previous install can be skipped, so check the remote before
+    // installing only when there is a record and the files are still present.
+    // A first install records the revision afterwards.
+    let revision = null
+
+    if (!options.force && entry && installedHere) {
+      revision = resolveGroupRevision(group.skills, probe, { env: gitEnv })
+      if (revision.status === "known" && entry.revision === revision.revision) {
+        console.log(`# unchanged (${revision.revision.slice(0, 7)}); skipping, use --force to reinstall`)
+        skipped += 1
+        continue
+      }
+      // The remote cannot be checked right now, but the group was installed
+      // before and its files are still present, so keep the current copy.
+      if (revision.status === "error") {
+        console.error(`[${sourceLabel(group.skills)}] update check failed (${revision.message}); keeping the installed copy`)
+        skipped += 1
+        continue
+      }
+    }
+
+    let groupFailed = false
+
+    if (group.skills.length === 1) {
+      const skill = group.skills[0]
+      printDescriptions(group.skills)
+      const result = await runWithRetries(executeTolerant, group.command, {
+        cwd: options.cwd,
+        env: gitEnv,
+        retries,
+        retryDelayMs,
+        label: skill.name,
+      })
+      if (statusCode(result) !== 0) {
+        failures += 1
+        groupFailed = true
+        reportFailure(skill.name, result)
+        if (result.signal || !options.continueOnError) stopped = true
+      }
+    } else {
+      // A batched command shares one fetch. Since a failure could come from a
+      // single bad name or a transient error, retry each entry individually
+      // when the batch does not succeed.
+      const batch = executeTolerant(group.command, { cwd: options.cwd, env: gitEnv })
+      if (statusCode(batch) !== 0) {
+        if (batch.signal) {
+          failures += group.skills.length
+          groupFailed = true
+          reportFailure(sourceLabel(group.skills), batch)
+          stopped = true
+        } else {
+          console.error(`[${sourceLabel(group.skills)}] batch install failed; retrying each skill individually`)
+          for (const skill of group.skills) {
+            const result = await runWithRetries(executeTolerant, commandFor(skill, manifest.cli), {
+              cwd: options.cwd,
+              env: gitEnv,
+              retries,
+              retryDelayMs,
+              label: skill.name,
+            })
+            if (statusCode(result) !== 0) {
+              failures += 1
+              groupFailed = true
+              reportFailure(skill.name, result)
+              if (result.signal || !options.continueOnError) {
+                stopped = true
+                break
+              }
+            }
+          }
+        }
+      }
+    }
+
+    if (!groupFailed) {
+      if (!revision) revision = resolveGroupRevision(group.skills, probe, { env: gitEnv })
+      if (revision.status === "known") {
+        setStateEntry(state, filename, key, {
+          revision: revision.revision,
+          skills: group.skills.map((skill) => skill.name),
+          installedAt: new Date().toISOString(),
+        })
+        try {
+          await writeState(stateFilename, state)
+        } catch (error) {
+          console.error(`skill-sync: cannot write state ${stateFilename}: ${error.message}`)
+        }
+      }
     }
   }
 
@@ -106,7 +285,12 @@ export async function syncCommand(manifestFilename, options = {}) {
     return 1
   }
 
-  if (!options.dryRun) console.log("\nSync complete.")
+  if (!options.dryRun) {
+    const skippedText = skipped > 0
+      ? ` Skipped ${skipped} unchanged group${skipped === 1 ? "" : "s"}.`
+      : ""
+    console.log(`\nSync complete.${skippedText}`)
+  }
   return 0
 }
 

package/src/mirror.mjs

@@ -0,0 +1,36 @@
+export const GITHUB_BASE = "https://github.com/"
+
+export function normalizeMirror(mirror) {
+  if (mirror === undefined || mirror === null || mirror === "") return undefined
+  if (typeof mirror !== "string") throw new Error("GitHub mirror must be a URL")
+
+  let url
+  try {
+    url = new URL(mirror.trim())
+  } catch {
+    throw new Error(`Invalid GitHub mirror URL: ${mirror}`)
+  }
+  if (url.protocol !== "https:" && url.protocol !== "http:") {
+    throw new Error(`GitHub mirror must be an http(s) URL: ${mirror}`)
+  }
+  url.hash = ""
+  url.search = ""
+  const href = url.toString()
+  return href.endsWith("/") ? href : `${href}/`
+}
+
+// Git rewrites https://github.com/... to <mirror>https://github.com/... through
+// the GIT_CONFIG_* environment variables, so the rewrite applies to every git
+// process this tool starts without touching the user's global configuration.
+export function mirrorGitEnv(mirror, baseEnv = process.env) {
+  const normalized = normalizeMirror(mirror)
+  if (!normalized) return undefined
+
+  const env = { ...baseEnv }
+  const parsed = Number.parseInt(env.GIT_CONFIG_COUNT ?? "0", 10)
+  const start = Number.isInteger(parsed) && parsed >= 0 ? parsed : 0
+  env.GIT_CONFIG_COUNT = String(start + 1)
+  env[`GIT_CONFIG_KEY_${start}`] = `url.${normalized}${GITHUB_BASE}.insteadOf`
+  env[`GIT_CONFIG_VALUE_${start}`] = GITHUB_BASE
+  return env
+}

package/src/revision.mjs

@@ -0,0 +1,55 @@
+import { spawnSync } from "node:child_process"
+
+const COMMIT_SHA = /^[0-9a-f]{40}$/i
+const SHORTHAND = /^[a-zA-Z0-9_.-]+\/[a-zA-Z0-9_.-]+$/
+const KNOWN_GIT_HOSTS = /(^|\.)(github\.com|gitlab\.com|bitbucket\.org|gitee\.com)$/i
+
+export function isCommitSha(ref) {
+  return typeof ref === "string" && COMMIT_SHA.test(ref)
+}
+
+// Returns a URL git ls-remote can probe, or null when the source is not a
+// plain Git repository (direct downloads, archives, unknown hosts).
+export function gitUrlForSource(source) {
+  if (SHORTHAND.test(source) && !source.split("/").some((part) => part.startsWith("."))) {
+    return `https://github.com/${source}.git`
+  }
+  if (/^git@[^:]+:.+/.test(source)) return source
+
+  let url
+  try {
+    url = new URL(source)
+  } catch {
+    return null
+  }
+  if (url.protocol !== "https:" && url.protocol !== "http:") return null
+  if (!url.pathname.endsWith(".git") && !KNOWN_GIT_HOSTS.test(url.hostname)) return null
+
+  const tree = url.pathname.indexOf("/tree/")
+  if (tree !== -1) url.pathname = url.pathname.slice(0, tree)
+  if (!url.pathname.endsWith(".git")) url.pathname += ".git"
+  url.search = ""
+  url.hash = ""
+  return url.toString()
+}
+
+export function probeRevision(url, ref, { timeoutMs = 10000, env = process.env } = {}) {
+  const result = spawnSync("git", ["ls-remote", url, ref ?? "HEAD"], {
+    encoding: "utf8",
+    timeout: timeoutMs,
+    windowsHide: true,
+    env: { ...env, GIT_TERMINAL_PROMPT: "0" },
+  })
+
+  if (result.error) return { status: "error", message: result.error.message }
+  if (result.status !== 0) {
+    const message = (result.stderr || "").trim() || `git ls-remote exited with code ${result.status}`
+    return { status: "error", message }
+  }
+
+  const line = (result.stdout || "").split(/\r?\n/).find((entry) => entry.trim() !== "")
+  if (!line) return { status: "unknown" }
+  const revision = line.trim().split(/\s+/)[0]
+  if (!COMMIT_SHA.test(revision)) return { status: "unknown" }
+  return { status: "known", revision: revision.toLowerCase() }
+}

package/src/runner.mjs

@@ -18,22 +18,50 @@ function packageSpec(cli) {
   return `${cli.package}@${cli.version}`
 }
 
-export function commandFor(skill, cli) {
-  const args = ["--yes", packageSpec(cli), "add", sourceWithRef(skill.source, skill.ref)]
+function groupKey(skill) {
+  return JSON.stringify([
+    skill.source,
+    skill.ref ?? null,
+    skill.agents,
+    skill.scope,
+    skill.copy,
+  ])
+}
+
+// skills add accepts multiple names after one --skill, so entries that share
+// every command-level flag can be installed with a single call (one fetch).
+export function groupSkills(skills) {
+  const groups = new Map()
+  for (const skill of skills) {
+    const key = groupKey(skill)
+    const group = groups.get(key)
+    if (group) group.push(skill)
+    else groups.set(key, [skill])
+  }
+  return [...groups.values()]
+}
+
+export function commandForGroup(skills, cli) {
+  const [{ source, ref, agents, scope, copy }] = skills
+  const args = ["--yes", packageSpec(cli), "add", sourceWithRef(source, ref)]
 
-  for (const agent of skill.agents) {
+  for (const agent of agents) {
     args.push("--agent", agent)
   }
 
-  args.push("--skill", skill.name)
+  args.push("--skill", ...skills.map((skill) => skill.name))
 
-  if (skill.scope === "global") args.push("--global")
-  if (skill.copy) args.push("--copy")
+  if (scope === "global") args.push("--global")
+  if (copy) args.push("--copy")
   args.push("--yes")
 
   return { executable: npxExecutable(), args }
 }
 
+export function commandFor(skill, cli) {
+  return commandForGroup([skill], cli)
+}
+
 function quoteForDisplay(value) {
   if (/^[a-zA-Z0-9_./:@%+=,-]+$/.test(value)) return value
   return process.platform === "win32"
@@ -61,6 +89,13 @@ function windowsNpxCli(env) {
   return filename
 }
 
+// The skills CLI can crash on exit on some Windows setups (a libuv teardown
+// assertion) while its telemetry flush is pending. DO_NOT_TRACK disables that
+// flush so the process exits cleanly; it is also a privacy default.
+export function childEnv(env = process.env) {
+  return { ...env, DO_NOT_TRACK: "1" }
+}
+
 export function runCommand(command, { cwd, env = process.env, timeout } = {}) {
   try {
     // Windows cannot spawn .cmd files directly. Run npx's JS entry point so
@@ -69,7 +104,7 @@ export function runCommand(command, { cwd, env = process.env, timeout } = {}) {
     return spawnSync(useNode ? process.execPath : command.executable,
       useNode ? [windowsNpxCli(env), ...command.args] : command.args, {
         cwd,
-        env,
+        env: childEnv(env),
         timeout,
         stdio: "inherit",
         windowsHide: true,

package/src/state.mjs

@@ -0,0 +1,63 @@
+import { existsSync } from "node:fs"
+import { mkdir, readFile, writeFile } from "node:fs/promises"
+import os from "node:os"
+import path from "node:path"
+
+export const STATE_VERSION = 1
+export const STATE_FILENAME = "state.json"
+
+export function statePath(home = os.homedir()) {
+  return path.join(home, ".config", "skill-sync", STATE_FILENAME)
+}
+
+// The key covers everything that changes the installed result except the
+// remote revision, so a new skill name or flag in the same group forces a
+// fresh install.
+export function stateKey(skills) {
+  const { source, ref, agents, scope, copy } = skills[0]
+  return JSON.stringify([
+    source,
+    ref ?? null,
+    agents,
+    scope,
+    copy,
+    skills.map((skill) => skill.name),
+  ])
+}
+
+export async function readState(filename) {
+  try {
+    const parsed = JSON.parse(await readFile(filename, "utf8"))
+    if (parsed?.version === STATE_VERSION && parsed.manifests && typeof parsed.manifests === "object") {
+      return parsed
+    }
+  } catch {
+    // A missing or unreadable state file only disables skipping.
+  }
+  return { version: STATE_VERSION, manifests: {} }
+}
+
+export async function writeState(filename, state) {
+  await mkdir(path.dirname(filename), { recursive: true })
+  await writeFile(filename, `${JSON.stringify(state, null, 2)}\n`, "utf8")
+}
+
+export function stateEntry(state, manifestFilename, key) {
+  return state.manifests[manifestFilename]?.[key]
+}
+
+export function setStateEntry(state, manifestFilename, key, entry) {
+  if (!state.manifests[manifestFilename]) state.manifests[manifestFilename] = {}
+  state.manifests[manifestFilename][key] = entry
+}
+
+// skills installs a canonical copy under .agents/skills for both global and
+// project scope, independently of the target agents and copy/symlink mode.
+export function canonicalSkillPath(name, { global: isGlobal, cwd, home }) {
+  const base = isGlobal ? home : cwd
+  return path.join(base, ".agents", "skills", name)
+}
+
+export function allInstalled(skills, options) {
+  return skills.every((skill) => existsSync(canonicalSkillPath(skill.name, options)))
+}