@wangkh/skill-sync-cli 0.2.1 → 0.2.3

package/README.md

@@ -248,9 +248,12 @@ 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:
+`sync` prefers direct connections and falls back automatically: it probes
+github.com with a 5-second timeout first, and when the probe fails, clones and
+update checks run through `https://gh-proxy.com/` for that run. A direct
+install that fails anyway gets one retry through the fallback mirror. Pass
+`--github-mirror <url>` (or set `SKILL_SYNC_GITHUB_MIRROR`) to force a specific
+mirror instead of the automatic fallback:
 
 ```bash
 npx @wangkh/skill-sync-cli sync --github-mirror https://gh-proxy.com/
@@ -262,6 +265,11 @@ 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
@@ -279,6 +287,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

@@ -124,7 +124,7 @@ npx --yes skills@1.5.22 add vercel-labs/skills --agent opencode --skill find-ski
 
 `sync` 会把每个分组的已安装版本记录在 `~/.config/skill-sync/state.json`。之后的运行会用 `git ls-remote` 检查远端版本（固定为 commit SHA 的 `ref` 无需检查），版本和已安装文件都没有变化时跳过该组，不再重复下载。检查更新失败但本地文件仍然存在时，会保留现有安装。需要强制重装时使用 `--force`。
 
-如果所在网络无法直接访问 GitHub，可以用 `--github-mirror <url>`（或环境变量 `SKILL_SYNC_GITHUB_MIRROR`）让 clone 和版本检查走镜像：
+`sync` 默认优先直连 GitHub、失败自动回退：先用 5 秒超时探测 github.com，探测失败时本次运行的 clone 和版本检查自动走 `https://gh-proxy.com/`；直连安装失败也会再用镜像重试一次。需要强制指定镜像时用 `--github-mirror <url>`（或环境变量 `SKILL_SYNC_GITHUB_MIRROR`）：
 
 ```bash
 npx @wangkh/skill-sync-cli sync --github-mirror https://gh-proxy.com/
@@ -132,6 +132,8 @@ 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
@@ -186,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

@@ -29,7 +29,7 @@ Options:
   --dry-run               Print commands without downloading anything
   --continue-on-error     Continue after a skill installation fails
   --retries <n>           Retry each failed install up to n times (default 2)
-  --github-mirror <url>   Clone GitHub sources through a mirror (sync only)
+  --github-mirror <url>   Force a GitHub mirror instead of the automatic fallback
   --force                 Replace the selected manifest with init, or reinstall with sync
   -h, --help              Show this help
   -v, --version           Show the version

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wangkh/skill-sync-cli",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Sync declared agent skills across machines through the skills CLI",
   "author": "wkh",
   "repository": {
@@ -27,6 +27,7 @@
     "bin",
     "src",
     "schemas",
+    "skills",
     "README.md",
     "README.zh-CN.md",
     "RELEASING.md",

package/skills/skill-sync/SKILL.md

@@ -0,0 +1,92 @@
+---
+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 access: `sync` probes github.com with a 5-second timeout and falls
+  back to `https://gh-proxy.com/` automatically; `--github-mirror <url>` forces
+  a specific mirror (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

@@ -15,8 +15,14 @@ import {
   runCommand,
   statusCode,
 } from "./runner.mjs"
-import { mirrorGitEnv } from "./mirror.mjs"
-import { gitUrlForSource, isCommitSha, probeRevision } from "./revision.mjs"
+import { DEFAULT_FALLBACK_MIRROR, mirrorGitEnv } from "./mirror.mjs"
+import {
+  checkGithubReachable,
+  gitUrlForSource,
+  isCommitSha,
+  isGithubSource,
+  probeRevision,
+} from "./revision.mjs"
 import {
   allInstalled,
   readState,
@@ -30,6 +36,9 @@ 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,
@@ -96,17 +105,26 @@ function resolveGroupRevision(skills, probe, probeOptions) {
   return probe(url, ref, probeOptions)
 }
 
-async function runWithRetries(execute, command, { cwd, env, retries, retryDelayMs, label }) {
+async function runWithRetries(execute, command, { cwd, env, fallbackEnv, retries, retryDelayMs, label }) {
+  let result
   for (let attempt = 0; ; attempt += 1) {
-    const result = execute(command, { cwd, env })
+    result = execute(command, { cwd, env })
     const code = statusCode(result)
-    if (code === 0 || result.signal || attempt >= retries) return result
+    if (code === 0 || result.signal || attempt >= retries) break
 
     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)
   }
+
+  // Direct connections can work for the reachability probe and still time out
+  // later; one mirror attempt covers that case.
+  if (statusCode(result) !== 0 && !result.signal && fallbackEnv) {
+    console.error(`[${label}] retrying via fallback mirror`)
+    result = execute(command, { cwd, env: fallbackEnv })
+  }
+  return result
 }
 
 export async function planCommand(manifestFilename) {
@@ -137,7 +155,6 @@ export async function syncCommand(manifestFilename, options = {}) {
   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.")
@@ -151,6 +168,30 @@ export async function syncCommand(manifestFilename, options = {}) {
     command: commandForGroup(group, manifest.cli),
   }))
 
+  // Route GitHub traffic for this run: an explicit mirror always wins;
+  // otherwise probe github.com briefly and fall back to the default mirror
+  // when it does not answer.
+  let gitEnv = mirrorGitEnv(options.githubMirror)
+  let fallbackEnv = null
+  if (!options.githubMirror && !options.dryRun && groups.some((group) => isGithubSource(group.skills[0].source))) {
+    const check = options.checkGithub ?? checkGithubReachable
+    if (check()) {
+      console.log("# GitHub reachable; using direct connections")
+      fallbackEnv = mirrorGitEnv(DEFAULT_FALLBACK_MIRROR)
+    } else {
+      gitEnv = mirrorGitEnv(DEFAULT_FALLBACK_MIRROR)
+      console.log(`# GitHub unreachable; using fallback mirror ${DEFAULT_FALLBACK_MIRROR}`)
+    }
+  }
+
+  const resolveRevision = (group) => {
+    let revision = resolveGroupRevision(group.skills, probe, { env: gitEnv })
+    if (revision.status === "error" && fallbackEnv) {
+      revision = resolveGroupRevision(group.skills, probe, { env: fallbackEnv })
+    }
+    return revision
+  }
+
   const stateFilename = options.stateFile ?? statePath(home)
   const state = await readState(stateFilename)
 
@@ -171,18 +212,28 @@ export async function syncCommand(manifestFilename, options = {}) {
 
     const key = stateKey(group.skills)
     const entry = stateEntry(state, filename, key)
-    const installedHere = allInstalled(group.skills, {
+    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 })
+      revision = resolveRevision(group)
       if (revision.status === "known" && entry.revision === revision.revision) {
         console.log(`# unchanged (${revision.revision.slice(0, 7)}); skipping, use --force to reinstall`)
         skipped += 1
@@ -202,9 +253,10 @@ export async function syncCommand(manifestFilename, options = {}) {
     if (group.skills.length === 1) {
       const skill = group.skills[0]
       printDescriptions(group.skills)
-      const result = await runWithRetries(execute, group.command, {
+      const result = await runWithRetries(executeTolerant, group.command, {
         cwd: options.cwd,
         env: gitEnv,
+        fallbackEnv,
         retries,
         retryDelayMs,
         label: skill.name,
@@ -219,7 +271,11 @@ export async function syncCommand(manifestFilename, options = {}) {
       // 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 = execute(group.command, { cwd: options.cwd, env: gitEnv })
+      let batch = executeTolerant(group.command, { cwd: options.cwd, env: gitEnv })
+      if (statusCode(batch) !== 0 && !batch.signal && fallbackEnv) {
+        console.error(`[${sourceLabel(group.skills)}] batch install failed; retrying via fallback mirror`)
+        batch = executeTolerant(group.command, { cwd: options.cwd, env: fallbackEnv })
+      }
       if (statusCode(batch) !== 0) {
         if (batch.signal) {
           failures += group.skills.length
@@ -229,9 +285,10 @@ export async function syncCommand(manifestFilename, options = {}) {
         } else {
           console.error(`[${sourceLabel(group.skills)}] batch install failed; retrying each skill individually`)
           for (const skill of group.skills) {
-            const result = await runWithRetries(execute, commandFor(skill, manifest.cli), {
+            const result = await runWithRetries(executeTolerant, commandFor(skill, manifest.cli), {
               cwd: options.cwd,
               env: gitEnv,
+              fallbackEnv,
               retries,
               retryDelayMs,
               label: skill.name,
@@ -251,7 +308,7 @@ export async function syncCommand(manifestFilename, options = {}) {
     }
 
     if (!groupFailed) {
-      if (!revision) revision = resolveGroupRevision(group.skills, probe, { env: gitEnv })
+      if (!revision) revision = resolveRevision(group)
       if (revision.status === "known") {
         setStateEntry(state, filename, key, {
           revision: revision.revision,

package/src/mirror.mjs

@@ -1,4 +1,5 @@
 export const GITHUB_BASE = "https://github.com/"
+export const DEFAULT_FALLBACK_MIRROR = "https://gh-proxy.com/"
 
 export function normalizeMirror(mirror) {
   if (mirror === undefined || mirror === null || mirror === "") return undefined

package/src/revision.mjs

@@ -53,3 +53,21 @@ export function probeRevision(url, ref, { timeoutMs = 10000, env = process.env }
   if (!COMMIT_SHA.test(revision)) return { status: "unknown" }
   return { status: "known", revision: revision.toLowerCase() }
 }
+
+const GITHUB_CHECK_URL = "https://github.com/octocat/Hello-World.git"
+
+export function isGithubSource(source) {
+  if (SHORTHAND.test(source) && !source.split("/").some((part) => part.startsWith("."))) return true
+  if (/^git@github\.com:/i.test(source)) return true
+  try {
+    return /(^|\.)github\.com$/i.test(new URL(source).hostname)
+  } catch {
+    return false
+  }
+}
+
+// A short direct probe decides whether sync runs against github.com or the
+// fallback mirror for this run.
+export function checkGithubReachable({ timeoutMs = 5000 } = {}) {
+  return probeRevision(GITHUB_CHECK_URL, "HEAD", { timeoutMs }).status === "known"
+}

package/src/runner.mjs

@@ -89,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
@@ -97,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,