@wangkh/skill-sync-cli 0.2.1 → 0.2.2

package/README.md

@@ -262,6 +262,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 +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

@@ -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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wangkh/skill-sync-cli",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "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,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

@@ -30,6 +30,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,
@@ -171,11 +174,21 @@ 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.
@@ -202,7 +215,7 @@ 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,
         retries,
@@ -219,7 +232,7 @@ 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 })
+      const batch = executeTolerant(group.command, { cwd: options.cwd, env: gitEnv })
       if (statusCode(batch) !== 0) {
         if (batch.signal) {
           failures += group.skills.length
@@ -229,7 +242,7 @@ 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,
               retries,

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,