@wangkh/skill-sync-cli 0.1.0 → 0.2.1

package/README.md

@@ -91,6 +91,18 @@ default user file. An explicit missing or invalid file produces an error when
 reading; it never falls back to another manifest. Clone a remote configuration
 repository first, then pass the path to its local JSON file.
 
+To bootstrap from a manifest that is already published online, pass its file URL
+to `init --from`. Gitee and GitHub `blob` page URLs are converted to raw file
+URLs automatically, and the download is validated before anything is written:
+
+```bash
+npx @wangkh/skill-sync-cli init --from https://gitee.com/ai_1024/skill-sync/blob/main/skills.json
+npx @wangkh/skill-sync-cli init --from https://gitee.com/ai_1024/skill-sync/blob/main/skills.json --config ./my-skills/skills.json
+```
+
+Without `--config`, the manifest is written to the default user location;
+existing files still require `--force`.
+
 The `npx skills` package itself does not discover these files. This wrapper
 reads the selected manifest, then delegates each installation to `npx skills`.
 
@@ -198,6 +210,9 @@ npx @wangkh/skill-sync-cli plan --config ./my-skills/skills.json
 npx @wangkh/skill-sync-cli sync --config ./my-skills/skills.json
 ```
 
+You can skip the clone and initialize directly from the published file URL with
+`npx @wangkh/skill-sync-cli init --from <url>`.
+
 After committing and pushing future manifest edits, update each existing clone:
 
 ```bash
@@ -218,6 +233,35 @@ 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`.
+
 For project-scoped skills, set:
 
 ```json
@@ -263,7 +307,7 @@ npm run check
 npm run test:package
 ```
 
-This creates `dist/wangkh-skill-sync-cli-0.1.0.tgz` and `dist/package-check.json`. The
+This creates `dist/wangkh-skill-sync-cli-0.2.0.tgz` and `dist/package-check.json`. The
 package check runs real npx commands offline, with a temporary home directory
 and a fresh npm cache. It verifies initialization, external manifests, previews, and
 error handling, then removes the temporary environment. The archive and report
@@ -272,9 +316,9 @@ remain in `dist/`.
 You can run that archive directly. Replace the path with its absolute location:
 
 ```bash
-npx --yes --package /absolute/path/wangkh-skill-sync-cli-0.1.0.tgz skill-sync-cli --help
-npx --yes --package /absolute/path/wangkh-skill-sync-cli-0.1.0.tgz skill-sync-cli init
-npx --yes --package /absolute/path/wangkh-skill-sync-cli-0.1.0.tgz skill-sync-cli plan
+npx --yes --package /absolute/path/wangkh-skill-sync-cli-0.2.0.tgz skill-sync-cli --help
+npx --yes --package /absolute/path/wangkh-skill-sync-cli-0.2.0.tgz skill-sync-cli init
+npx --yes --package /absolute/path/wangkh-skill-sync-cli-0.2.0.tgz skill-sync-cli plan
 ```
 
 These manual commands use your normal user configuration directory. To select a

package/README.zh-CN.md

@@ -48,6 +48,15 @@ npx @wangkh/skill-sync-cli path --config ./my-skills/skills.json
 
 每次使用仓库清单时都传入 `--config`；省略时使用默认用户配置。远程配置仓库先用 Git 克隆到本机，再把本地 JSON 文件路径交给这个参数。
 
+如果清单已经发布在 Gitee 或 GitHub 上，可以用 `init --from` 直接按链接初始化；`blob` 页面链接会自动转换为 raw 文件地址，下载后会先校验清单格式再写入：
+
+```bash
+npx @wangkh/skill-sync-cli init --from https://gitee.com/ai_1024/skill-sync/blob/main/skills.json
+npx @wangkh/skill-sync-cli init --from https://gitee.com/ai_1024/skill-sync/blob/main/skills.json --config ./my-skills/skills.json
+```
+
+不传 `--config` 时，清单写入默认用户配置位置；目标文件已存在时仍需显式加 `--force`。
+
 ## 清单格式
 
 ```json
@@ -111,6 +120,18 @@ 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`。
+
 只预览，或者在单个 Skill 失败后继续处理其他条目：
 
 ```bash
@@ -120,6 +141,8 @@ npx @wangkh/skill-sync-cli sync --continue-on-error
 
 默认遇到安装失败就停止并返回非零退出码。使用 `--continue-on-error` 后会继续执行，其间发生失败仍返回非零退出码。
 
+失败的安装会自动重试，默认 2 次并带有短暂退避；可以用 `--retries <n>` 调整次数，`--retries 0` 表示不重试。中断信号不会被重试。
+
 使用 `scope: "project"` 时，安装目标是运行命令的目录，与清单所在目录相互独立。在目标应用项目目录运行：
 
 ```bash
@@ -150,6 +173,8 @@ npx @wangkh/skill-sync-cli plan --config ./my-skills/skills.json
 npx @wangkh/skill-sync-cli sync --config ./my-skills/skills.json
 ```
 
+也可以不克隆，直接用 `npx @wangkh/skill-sync-cli init --from <文件链接>` 按链接初始化。
+
 以后修改清单并提交、推送后，在已经克隆仓库的电脑上执行：
 
 ```bash
@@ -190,14 +215,14 @@ npm run check
 npm run test:package
 ```
 
-命令会生成 `dist/wangkh-skill-sync-cli-0.1.0.tgz` 和验证报告 `dist/package-check.json`。安装包验证通过真实 npx 命令离线执行，使用临时用户目录和全新的 npm 缓存，检查初始化、外部清单、预览和错误处理。验证结束后清理临时环境，保留安装包及报告。
+命令会生成 `dist/wangkh-skill-sync-cli-0.2.0.tgz` 和验证报告 `dist/package-check.json`。安装包验证通过真实 npx 命令离线执行，使用临时用户目录和全新的 npm 缓存，检查初始化、外部清单、预览和错误处理。验证结束后清理临时环境，保留安装包及报告。
 
 也可以直接用 npx 运行安装包。请把路径替换为安装包的实际绝对路径：
 
 ```powershell
-npx --yes --package "C:\path\to\wangkh-skill-sync-cli-0.1.0.tgz" skill-sync-cli --help
-npx --yes --package "C:\path\to\wangkh-skill-sync-cli-0.1.0.tgz" skill-sync-cli init
-npx --yes --package "C:\path\to\wangkh-skill-sync-cli-0.1.0.tgz" skill-sync-cli plan
+npx --yes --package "C:\path\to\wangkh-skill-sync-cli-0.2.0.tgz" skill-sync-cli --help
+npx --yes --package "C:\path\to\wangkh-skill-sync-cli-0.2.0.tgz" skill-sync-cli init
+npx --yes --package "C:\path\to\wangkh-skill-sync-cli-0.2.0.tgz" skill-sync-cli plan
 ```
 
 这些手动命令默认使用正常的用户配置目录。使用仓库清单时，在子命令后加上 `--config "C:\path\to\my-skills\skills.json"`。

package/RELEASING.md

@@ -1,18 +1,18 @@
-# 发布 0.1.0
+# 发布 0.2.0
 
 ## 发布信息
 
 | 项目 | 值 |
 | --- | --- |
 | npm 包名 | `@wangkh/skill-sync-cli` |
-| 版本 | `0.1.0` |
+| 版本 | `0.2.0` |
 | 命令入口 | `npx @wangkh/skill-sync-cli`；安装后的可执行命令为 `skill-sync-cli` |
 | 计划 GitHub 仓库 | `https://github.com/yudaiyan/skill-sync-cli` |
 | 默认上游 CLI | `skills@1.5.22` |
 | 默认配置位置 | `~/.config/skill-sync/skills.json` |
 | 仓库清单 | `--config /path/to/my-skills/skills.json`，也支持 `-c` |
 
-2026-09-10 首次发布时，npm 公共注册表拒绝了非作用域包名 `skill-sync-cli`，理由是它与已存在的 `skillsync-cli` 过于相似，并建议改用 `@wangkh/skill-sync-cli`；当前包名已采用该建议，发布需要 npm 账号的 2FA。GitHub CLI 登录账号为 `yudaiyan`，仓库地址按 `https://github.com/yudaiyan/skill-sync-cli` 准备。
+0.1.0 已于 2026-09-10 发布到 npm；首次尝试非作用域包名 `skill-sync-cli` 时被拒（与已存在的 `skillsync-cli` 过于相似），随后改用 `@wangkh/skill-sync-cli`。发布需要 npm 账号的 2FA。GitHub 仓库已创建：`https://github.com/yudaiyan/skill-sync-cli`。0.2.0 新增 `init --from <url>`，支持从 Gitee / GitHub 文件链接初始化清单。
 
 ## 生成并验证安装包
 
@@ -25,22 +25,17 @@ npm run test:package
 
 `test:package` 会实际执行 `npm pack`，随后用独立的用户目录和 npm 缓存离线运行安装包。输出：
 
-- `dist/wangkh-skill-sync-cli-0.1.0.tgz`：可分发的 npm 安装包。
+- `dist/wangkh-skill-sync-cli-0.2.0.tgz`：可分发的 npm 安装包。
 - `dist/package-check.json`：包摘要、文件清单、执行环境和通过的检查。
 
 `dist/` 已加入 Git 忽略规则。修改代码或文档后，需要重新生成安装包，使报告对应最终内容。
 
 ## 正式发布流程
 
-完成发布准备提交后，创建计划仓库并推送 `main`。例如，选择公开仓库时：
-
-```bash
-gh repo create yudaiyan/skill-sync-cli --public --source . --remote origin --push
-```
-
-确认 npm 登录身份，然后从项目源码目录发布：
+确认改动已提交并推送 `main`，然后确认 npm 登录身份，从项目源码目录发布：
 
 ```bash
+git push origin main
 npm whoami --registry=https://registry.npmjs.org/
 npm publish
 ```
@@ -51,8 +46,8 @@ npm publish
 
 ```bash
 npm view @wangkh/skill-sync-cli version
-npx --yes @wangkh/skill-sync-cli@0.1.0 --version
-npx --yes @wangkh/skill-sync-cli@0.1.0 --help
+npx --yes @wangkh/skill-sync-cli@0.2.0 --version
+npx --yes @wangkh/skill-sync-cli@0.2.0 --help
 ```
 
 ## 后续版本

package/bin/skill-sync.mjs

@@ -25,9 +25,12 @@ Usage:
 
 Options:
   -c, --config <file>      Use this JSON manifest (relative or absolute path)
+  --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
 
@@ -38,6 +41,7 @@ Examples:
   npx ${COMMAND_NAME} sync
   npx ${COMMAND_NAME} init --config ./my-skills/skills.json
   npx ${COMMAND_NAME} sync --config ./my-skills/skills.json
+  npx ${COMMAND_NAME} init --from https://gitee.com/ai_1024/skill-sync/blob/main/skills.json
 
 Without --config, use ~/.config/skill-sync/skills.json.
 Relative config paths and project installations use the current working directory.
@@ -62,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=")) {
@@ -74,6 +88,26 @@ 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")
+      }
+      const inline = arg.startsWith("--from=")
+      const value = inline ? arg.slice("--from=".length) : argv[++index]
+      if (value === undefined || value.trim() === "" || (!inline && value.startsWith("-"))) {
+        throw new Error("--from requires a URL")
+      }
+      options.from = value
     } else if (arg.startsWith("-")) {
       throw new Error(`Unknown option: ${arg}`)
     } else {
@@ -104,6 +138,9 @@ async function main() {
   if (options.positional.length > 1) {
     throw new Error(`Unexpected argument: ${options.positional[1]}`)
   }
+  if (options.from !== undefined && command !== "init") {
+    throw new Error("--from is only supported by init")
+  }
 
   const filename = resolveConfigPath(options.configFile)
   if (command === "init") {
@@ -117,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.1.0",
+  "version": "0.2.1",
   "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"

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,10 +9,27 @@ 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
 
 const SAMPLE_MANIFEST = {
   version: 1,
@@ -46,6 +65,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)
@@ -56,9 +119,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
 }
@@ -67,36 +132,138 @@ 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 installedHere = allInstalled(group.skills, {
+      global: group.skills[0].scope === "global",
+      cwd,
+      home,
+    })
+    // 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(execute, 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 = execute(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(execute, 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}`)
+        }
+      }
     }
   }
 
@@ -105,11 +272,16 @@ 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
 }
 
-export async function initCommand(manifestFilename, { force = false } = {}) {
+export async function initCommand(manifestFilename, { force = false, from, fetchImpl } = {}) {
   const filename = path.resolve(manifestFilename)
   if (!force) {
     try {
@@ -120,12 +292,25 @@ export async function initCommand(manifestFilename, { force = false } = {}) {
     }
   }
 
+  let text = `${JSON.stringify(SAMPLE_MANIFEST, null, 2)}\n`
+  let source
+  if (from !== undefined) {
+    const downloaded = await downloadManifest(from, { fetchImpl })
+    source = downloaded.url
+    try {
+      normalizeManifest(JSON.parse(downloaded.text))
+    } catch (error) {
+      throw new Error(`Remote manifest at ${source} is invalid: ${error.message}`)
+    }
+    text = downloaded.text.endsWith("\n") ? downloaded.text : `${downloaded.text}\n`
+  }
+
   await mkdir(path.dirname(filename), { recursive: true })
-  await writeFile(filename, `${JSON.stringify(SAMPLE_MANIFEST, null, 2)}\n`, {
+  await writeFile(filename, text, {
     encoding: "utf8",
     flag: force ? "w" : "wx",
   })
-  console.log(`Created ${filename}`)
+  console.log(source ? `Created ${filename} from ${source}` : `Created ${filename}`)
   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/remote.mjs

@@ -0,0 +1,51 @@
+const MAX_MANIFEST_BYTES = 1024 * 1024
+
+export function normalizeManifestUrl(input) {
+  let parsed
+  try {
+    parsed = new URL(input)
+  } catch {
+    return input
+  }
+
+  if (parsed.hostname === "gitee.com") {
+    const match = parsed.pathname.match(/^\/([^/]+)\/([^/]+)\/blob\/(.+)$/)
+    if (match) return `${parsed.origin}/${match[1]}/${match[2]}/raw/${match[3]}`
+  }
+
+  if (parsed.hostname === "github.com") {
+    const match = parsed.pathname.match(/^\/([^/]+)\/([^/]+)\/blob\/(.+)$/)
+    if (match) return `https://raw.githubusercontent.com/${match[1]}/${match[2]}/${match[3]}`
+  }
+
+  return input
+}
+
+export async function downloadManifest(url, { fetchImpl = fetch, timeoutMs = 20000 } = {}) {
+  if (typeof url !== "string" || !/^https?:\/\//i.test(url)) {
+    throw new Error("--from requires an http(s) URL")
+  }
+
+  const normalized = normalizeManifestUrl(url)
+  let response
+  try {
+    response = await fetchImpl(normalized, {
+      redirect: "follow",
+      signal: AbortSignal.timeout(timeoutMs),
+      headers: { "user-agent": "skill-sync-cli" },
+    })
+  } catch (error) {
+    throw new Error(`Cannot download manifest from ${normalized}: ${error.message}`)
+  }
+
+  if (!response.ok) {
+    throw new Error(`Cannot download manifest from ${normalized}: HTTP ${response.status}`)
+  }
+
+  const text = await response.text()
+  if (Buffer.byteLength(text, "utf8") > MAX_MANIFEST_BYTES) {
+    throw new Error(`Remote manifest is too large (limit ${MAX_MANIFEST_BYTES} bytes): ${normalized}`)
+  }
+
+  return { url: normalized, text: text.replace(/^\uFEFF/, "") }
+}

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()]
+}
 
-  for (const agent of skill.agents) {
+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 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"

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)))
+}