@wangkh/skill-sync-cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,299 @@
+# skill-sync-cli
+
+[中文使用说明](README.zh-CN.md)
+
+`skill-sync-cli` keeps a portable list of third-party agent skills and restores
+them on another machine by invoking the `skills` CLI.
+
+The manifest records the source and skill name. The actual download, parsing,
+installation, and per-agent linking remain delegated to `npx skills`.
+
+## Quick Start
+
+Requires Node.js 18.17+, npm, and Git. Once this package is published to npm,
+run these commands from any directory. Before the first release, use
+[a source checkout or local package](#run-before-the-first-release).
+
+Create your manifest:
+
+```bash
+npx @wangkh/skill-sync-cli init
+```
+
+This creates:
+
+```text
+Windows:   %USERPROFILE%/.config/skill-sync/skills.json
+macOS/Linux: ~/.config/skill-sync/skills.json
+```
+
+Edit this file to list your skills, then preview the installation commands:
+
+```bash
+npx @wangkh/skill-sync-cli plan
+```
+
+Sync the skills:
+
+```bash
+npx @wangkh/skill-sync-cli sync
+```
+
+Validate without downloading:
+
+```bash
+npx @wangkh/skill-sync-cli validate
+```
+
+Show which file will be used:
+
+```bash
+npx @wangkh/skill-sync-cli path
+```
+
+`init` preserves an existing manifest. Use `npx @wangkh/skill-sync-cli init --force`
+when you intend to replace it with the sample.
+
+To keep the manifest in its own Git repository, use
+`npx @wangkh/skill-sync-cli sync --config ./my-skills/skills.json`.
+See [the cross-machine workflow](#cross-machine-workflow).
+
+## Configuration
+
+`skill-sync-cli` reads one manifest per invocation. The default location is:
+
+```text
+Windows:     %USERPROFILE%/.config/skill-sync/skills.json
+macOS/Linux: ~/.config/skill-sync/skills.json
+```
+
+On Windows, this normally resolves to
+`C:\Users\<user>\.config\skill-sync\skills.json`.
+
+Use `--config <file>` (or `-c <file>`) to select a local JSON file for any command:
+
+```bash
+npx @wangkh/skill-sync-cli init --config ./my-skills/skills.json
+npx @wangkh/skill-sync-cli validate --config ./my-skills/skills.json
+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 path --config ./my-skills/skills.json
+```
+
+The option can appear before or after the command; `--config=path` also works.
+Relative paths resolve from the working directory, absolute paths work as given,
+and a leading `~/` expands to your home directory. Quote paths containing spaces.
+`path` prints the selected absolute filename. `init` creates its parent directories
+and preserves existing files unless `--force` is supplied.
+
+Pass `--config` each time you want to use that manifest. Omitting it selects the
+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.
+
+The `npx skills` package itself does not discover these files. This wrapper
+reads the selected manifest, then delegates each installation to `npx skills`.
+
+## Manifest
+
+```json
+{
+  "version": 1,
+  "cli": {
+    "package": "skills",
+    "version": "1.5.22"
+  },
+  "defaults": {
+    "agents": ["opencode"],
+    "scope": "global",
+    "copy": true
+  },
+  "skills": [
+    {
+      "name": "find-skills",
+      "source": "vercel-labs/skills",
+      "description": "Discover and install more skills"
+    },
+    {
+      "name": "agent-browser",
+      "source": "vercel-labs/agent-browser",
+      "description": "Browser automation",
+      "ref": "main",
+      "agents": ["opencode", "codex"],
+      "scope": "global"
+    }
+  ]
+}
+```
+
+Supported source strings are the same ones accepted by `skills add`, such as
+GitHub shorthand, GitHub/GitLab URLs, Git URLs, direct skill URLs, and archives.
+Local filesystem paths are rejected because they are not portable between
+machines.
+
+`ref` is optional. For reproducible installations, use a tag or commit SHA
+instead of a moving branch such as `main`.
+
+## Fields
+
+### `cli`
+
+Controls which `skills` package is executed. Pinning the version makes setup
+behavior repeatable:
+
+```json
+"cli": { "package": "skills", "version": "1.5.22" }
+```
+
+Use `"latest"` when you explicitly want the newest CLI.
+
+### `defaults`
+
+Defaults apply to every skill unless overridden on the skill entry:
+
+- `agents`: target agent names, default `opencode`
+- `scope`: `global` or `project`, default `global`
+- `copy`: use copies instead of symlinks, default `true`
+
+Copy mode is the safer default on Windows because it does not require
+Developer Mode or symlink privileges. Set `copy` to `false` when you want the
+canonical-copy-plus-symlink layout provided by `skills`.
+
+### `skills`
+
+Each entry requires:
+
+- `name`: the skill name passed to `skills add --skill`
+- `source`: the remote source passed to `skills add`
+
+Optional fields are `description`, `ref`, `enabled`, `agents`, `scope`, and `copy`.
+
+`description` records why you use a skill and appears in the installation plan.
+
+Disabled entries remain in the manifest but are skipped by `sync`.
+
+## Cross-Machine Workflow
+
+Create a dedicated configuration repository and initialize its manifest:
+
+```bash
+git init -b main my-skills
+npx @wangkh/skill-sync-cli init --config ./my-skills/skills.json
+```
+
+Edit `my-skills/skills.json`, then save it in Git:
+
+```bash
+git -C my-skills add skills.json
+git -C my-skills commit -m "chore: add skill manifest"
+```
+
+Push this repository to your Git hosting service. On another machine, install
+Node.js, npm, and Git, then clone the configuration repository and use its file
+directly. Replace the example URL with your repository:
+
+```bash
+git clone https://github.com/YOUR_NAME/my-skills.git my-skills
+npx @wangkh/skill-sync-cli plan --config ./my-skills/skills.json
+npx @wangkh/skill-sync-cli sync --config ./my-skills/skills.json
+```
+
+After committing and pushing future manifest edits, update each existing clone:
+
+```bash
+git -C my-skills pull --ff-only
+npx @wangkh/skill-sync-cli sync --config ./my-skills/skills.json
+```
+
+Git transfers the manifest between machines; `sync` installs the skills declared
+in the local file. Each machine can clone the repository into a different folder.
+
+The `skills` CLI will also maintain its own local lock files for update
+tracking. This tool's manifest is the portable declaration of what should be
+installed; it is intentionally separate from those machine-local state files.
+
+Sync reinstalls enabled entries and can overwrite installed skills with the same
+name. Removing or disabling an entry does not uninstall it. By default a failure
+stops the batch; `npx @wangkh/skill-sync-cli sync --continue-on-error` attempts the remaining
+entries and still exits with a failure status. Use `npx @wangkh/skill-sync-cli sync --dry-run` to
+preview without installing.
+
+For project-scoped skills, set:
+
+```json
+"defaults": {
+  "agents": ["opencode"],
+  "scope": "project",
+  "copy": true
+}
+```
+
+Project scope uses the command's working directory, independently of the manifest
+location. From the target application project, run:
+
+```bash
+npx @wangkh/skill-sync-cli sync --config /path/to/my-skills/skills.json
+```
+
+## Run Before the First Release
+
+From a source checkout, the following commands work without installing project
+dependencies:
+
+```bash
+npm run init
+npm run plan
+npm run sync
+```
+
+To select a manifest with an npm script, forward the option after `--`:
+
+```bash
+npm run plan -- --config ../my-skills/skills.json
+```
+
+`npm run sync` runs in this package's directory. For project scope in another
+directory, run `node /absolute/path/to/skill-sync-cli/bin/skill-sync.mjs sync`
+from the target project.
+
+To verify the packaged CLI before publishing:
+
+```bash
+npm run check
+npm run test:package
+```
+
+This creates `dist/wangkh-skill-sync-cli-0.1.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
+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
+```
+
+These manual commands use your normal user configuration directory. To select a
+repository manifest, append `--config /path/to/my-skills/skills.json` after the
+subcommand.
+
+## Security
+
+A skill is agent instructions, and may include scripts or references that
+change how an agent operates. Review third-party skills before adding them to
+the manifest. Prefer trusted repositories, HTTPS, and immutable commit refs.
+
+## Development
+
+```bash
+npm run check
+npm run test:package
+```
+
+See [the release notes for maintainers](RELEASING.md) for the planned repository,
+package details, and publication procedure. `npm publish` runs both checks through
+`prepublishOnly`.

package/README.zh-CN.md

@@ -0,0 +1,207 @@
+# skill-sync-cli
+
+用一份 JSON 清单记录常用开源 Skills 的名称、来源和用途，通过一个命令批量调用 `npx skills add` 安装。适合把个人清单保存在 dotfiles 仓库中，在新电脑上恢复环境。
+
+## 开始使用
+
+需要 Node.js 18.17+、npm 和 Git。首次运行时，npx 会获取本工具；执行安装时，再获取清单指定版本的 `skills` CLI。
+
+发布到 npm 后，可以在任意目录运行以下命令。首个版本发布前，使用下文的[源码或本地安装包](#发布前使用)。
+
+```bash
+# 新环境：创建初始清单；如果已有清单，跳过这一步
+npx @wangkh/skill-sync-cli init
+
+# 查看配置文件的位置
+npx @wangkh/skill-sync-cli path
+
+# 编辑清单后检查格式并预览安装命令
+npx @wangkh/skill-sync-cli validate
+npx @wangkh/skill-sync-cli plan
+
+# 批量安装已启用的 Skills
+npx @wangkh/skill-sync-cli sync
+```
+
+默认配置文件位于用户目录中：
+
+- Windows：`%USERPROFILE%\.config\skill-sync\skills.json`
+- macOS / Linux：`~/.config/skill-sync/skills.json`
+
+创建后，编辑这个文件填写自己常用的 Skills。`init` 默认保留已有文件；如果确实要用示例覆盖当前清单，可以运行 `npx @wangkh/skill-sync-cli init --force`。
+
+## 指定配置文件
+
+所有命令都支持 `--config <文件路径>`，可以直接使用独立 Git 仓库里的清单：
+
+```bash
+npx @wangkh/skill-sync-cli init --config ./my-skills/skills.json
+npx @wangkh/skill-sync-cli validate --config ./my-skills/skills.json
+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 path --config ./my-skills/skills.json
+```
+
+也支持 `-c <文件路径>` 和 `--config=文件路径`，参数可以放在子命令前或后。相对路径以运行命令的目录为基准，支持绝对路径和 `~/`；包含空格的路径需要加引号。
+
+`path` 显示本次选中的绝对路径。`init` 会创建所需的父目录，已有文件需要显式加 `--force` 才能覆盖。读取时，如果指定文件不存在或内容无效，命令会报错。
+
+每次使用仓库清单时都传入 `--config`；省略时使用默认用户配置。远程配置仓库先用 Git 克隆到本机，再把本地 JSON 文件路径交给这个参数。
+
+## 清单格式
+
+```json
+{
+  "version": 1,
+  "cli": {
+    "package": "skills",
+    "version": "1.5.22"
+  },
+  "defaults": {
+    "agents": ["opencode"],
+    "scope": "global",
+    "copy": true
+  },
+  "skills": [
+    {
+      "name": "find-skills",
+      "source": "vercel-labs/skills",
+      "description": "查找和安装更多 Skills"
+    },
+    {
+      "name": "agent-browser",
+      "source": "vercel-labs/agent-browser",
+      "description": "浏览器自动化",
+      "enabled": false
+    }
+  ]
+}
+```
+
+每个 Skill 的 `name`、`source` 必填，其他字段可选：
+
+| 字段 | 含义 |
+| --- | --- |
+| `name` | 上游 Skill 的准确名称，传给 `--skill` |
+| `source` | GitHub 的 `owner/repo`、远程 Git URL、Skill URL 或下载地址 |
+| `description` | 自己记录的用途说明，预览时显示 |
+| `enabled` | 是否安装，默认 `true`；设为 `false` 可暂时停用 |
+| `ref` | Git 仓库的分支、标签或 commit SHA，省略则使用上游默认版本 |
+| `agents` | 安装到哪些工具，如 `["opencode", "codex", "claude-code"]` |
+| `scope` | `global` 安装到用户目录，`project` 安装到运行命令的工作目录 |
+| `copy` | `true` 复制文件，`false` 使用上游 CLI 的符号链接方式 |
+
+`agents`、`scope`、`copy` 优先使用条目自己的值，其次使用 `defaults`，未配置时分别为 `["opencode"]`、`"global"`、`true`。
+
+同一仓库的多个 Skills 分别写成多个条目。查找准确名称可以运行：
+
+```bash
+npx --yes skills@1.5.22 add vercel-labs/agent-browser --list
+```
+
+`ref` 用于 Git 来源，会编码成 `source#ref`。对于已经包含分支的 `/tree/...` URL 或直接下载地址，在 `source` 中指定版本即可。固定 CLI 版本只固定安装工具；要固定某个 Skill 的内容，需要为 Git 来源指定 commit SHA。
+
+## 安装行为
+
+上面的第一个条目会生成：
+
+```bash
+npx --yes skills@1.5.22 add vercel-labs/skills --agent opencode --skill find-skills --global --copy --yes
+```
+
+两个 `--yes` 分别用于 npx 下载安装工具和 Skills 安装确认。`sync` 会按清单顺序安装；再次运行会重新安装或更新这些条目，可能覆盖目标位置同名 Skill 的内容。从清单移除或禁用一个条目后，已经安装的内容仍会保留。
+
+只预览，或者在单个 Skill 失败后继续处理其他条目：
+
+```bash
+npx @wangkh/skill-sync-cli sync --dry-run
+npx @wangkh/skill-sync-cli sync --continue-on-error
+```
+
+默认遇到安装失败就停止并返回非零退出码。使用 `--continue-on-error` 后会继续执行，其间发生失败仍返回非零退出码。
+
+使用 `scope: "project"` 时，安装目标是运行命令的目录，与清单所在目录相互独立。在目标应用项目目录运行：
+
+```bash
+npx @wangkh/skill-sync-cli sync --config /path/to/my-skills/skills.json
+```
+
+## 用独立 Git 仓库跨机器同步
+
+先创建一个保存配置的仓库，并生成清单：
+
+```bash
+git init -b main my-skills
+npx @wangkh/skill-sync-cli init --config ./my-skills/skills.json
+```
+
+编辑 `my-skills/skills.json` 后提交：
+
+```bash
+git -C my-skills add skills.json
+git -C my-skills commit -m "chore: add skill manifest"
+```
+
+把这个仓库推送到自己的 Git 托管平台。其他电脑安装 Node.js、npm 和 Git 后，克隆配置仓库并直接使用其中的清单。请替换下面的示例地址：
+
+```bash
+git clone https://github.com/YOUR_NAME/my-skills.git my-skills
+npx @wangkh/skill-sync-cli plan --config ./my-skills/skills.json
+npx @wangkh/skill-sync-cli sync --config ./my-skills/skills.json
+```
+
+以后修改清单并提交、推送后，在已经克隆仓库的电脑上执行：
+
+```bash
+git -C my-skills pull --ff-only
+npx @wangkh/skill-sync-cli sync --config ./my-skills/skills.json
+```
+
+Git 负责在机器之间传递清单，`sync` 根据本地清单安装 Skills。每台电脑可以把配置仓库放在不同目录，通过 `--config` 指向对应文件。
+
+清单是这个脚本定义的格式；脚本读取后逐项调用官方 `skills` CLI。上游的 `.skill-lock.json` 继续由官方 CLI 维护。
+
+## 发布前使用
+
+获取项目源码后，可以在源码目录直接运行，无需安装项目依赖：
+
+```bash
+npm run init
+npm run plan
+npm run sync
+```
+
+通过 npm 脚本指定配置时，把参数放在 `--` 后面：
+
+```bash
+npm run plan -- --config ../my-skills/skills.json
+```
+
+`npm run sync` 的工作目录是本项目目录。如果清单采用项目安装范围，需要在目标项目目录运行脚本的绝对路径：
+
+```powershell
+node "C:\path\to\skill-sync-cli\bin\skill-sync.mjs" sync
+```
+
+生成并验证可分发的安装包：
+
+```bash
+npm run check
+npm run test:package
+```
+
+命令会生成 `dist/wangkh-skill-sync-cli-0.1.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
+```
+
+这些手动命令默认使用正常的用户配置目录。使用仓库清单时，在子命令后加上 `--config "C:\path\to\my-skills\skills.json"`。
+
+维护者发布流程见 [RELEASING.md](RELEASING.md)。从源码运行 `npm publish` 时，会自动执行单元测试和安装包验证。
+
+参考：[skills 官方文档](https://github.com/vercel-labs/skills)、[示例清单](skills.json.example)、[JSON Schema](schemas/skills-sync.schema.json)。

package/RELEASING.md

@@ -0,0 +1,60 @@
+# 发布 0.1.0
+
+## 发布信息
+
+| 项目 | 值 |
+| --- | --- |
+| npm 包名 | `@wangkh/skill-sync-cli` |
+| 版本 | `0.1.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` 准备。
+
+## 生成并验证安装包
+
+在项目源码目录运行：
+
+```bash
+npm run check
+npm run test:package
+```
+
+`test:package` 会实际执行 `npm pack`，随后用独立的用户目录和 npm 缓存离线运行安装包。输出：
+
+- `dist/wangkh-skill-sync-cli-0.1.0.tgz`：可分发的 npm 安装包。
+- `dist/package-check.json`：包摘要、文件清单、执行环境和通过的检查。
+
+`dist/` 已加入 Git 忽略规则。修改代码或文档后，需要重新生成安装包，使报告对应最终内容。
+
+## 正式发布流程
+
+完成发布准备提交后，创建计划仓库并推送 `main`。例如，选择公开仓库时：
+
+```bash
+gh repo create yudaiyan/skill-sync-cli --public --source . --remote origin --push
+```
+
+确认 npm 登录身份，然后从项目源码目录发布：
+
+```bash
+npm whoami --registry=https://registry.npmjs.org/
+npm publish
+```
+
+`npm publish` 会执行 `prepublishOnly`，重新运行单元测试和安装包验证。npm 认证、双重验证及包名权限由 npm 处理。`publishConfig` 指向公共 npm 注册表。
+
+发布成功后，从其他目录检查 npm 上的版本和用户入口：
+
+```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
+```
+
+## 后续版本
+
+更新 `package.json` 的版本，CLI 的 `--version` 会读取同一版本号。同步修改文档中的安装包文件名，运行上述检查，再提交和发布。

package/bin/skill-sync.mjs

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+
+import { createRequire } from "node:module"
+import {
+  initCommand,
+  planCommand,
+  syncCommand,
+  validateCommand,
+} from "../src/commands.mjs"
+import { resolveConfigPath } from "../src/config.mjs"
+
+const { name: COMMAND_NAME, version: VERSION } = createRequire(import.meta.url)("../package.json")
+function help() {
+  console.log(`${COMMAND_NAME} ${VERSION}
+
+Sync skills declared in a JSON manifest by delegating downloads to npx skills.
+
+Usage:
+  npx ${COMMAND_NAME} <command> [options]
+  ${COMMAND_NAME} sync [options]
+  ${COMMAND_NAME} plan [options]
+  ${COMMAND_NAME} validate [options]
+  ${COMMAND_NAME} path [options]
+  ${COMMAND_NAME} init [options]
+
+Options:
+  -c, --config <file>      Use this JSON manifest (relative or absolute path)
+  --dry-run               Print commands without downloading anything
+  --continue-on-error     Continue after a skill installation fails
+  --force                 Replace the selected manifest with init
+  -h, --help              Show this help
+  -v, --version           Show the version
+
+Examples:
+  npx ${COMMAND_NAME} init
+  npx ${COMMAND_NAME} path
+  npx ${COMMAND_NAME} plan
+  npx ${COMMAND_NAME} sync
+  npx ${COMMAND_NAME} init --config ./my-skills/skills.json
+  npx ${COMMAND_NAME} sync --config ./my-skills/skills.json
+
+Without --config, use ~/.config/skill-sync/skills.json.
+Relative config paths and project installations use the current working directory.
+`)
+}
+
+function parseArgs(argv) {
+  const options = {
+    dryRun: false,
+    continueOnError: false,
+    force: false,
+    positional: [],
+  }
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index]
+    if (arg === "-h" || arg === "--help") {
+      options.help = true
+    } else if (arg === "-v" || arg === "--version") {
+      options.version = true
+    } else if (arg === "--dry-run") {
+      options.dryRun = true
+    } else if (arg === "--continue-on-error") {
+      options.continueOnError = true
+    } else if (arg === "--force") {
+      options.force = true
+    } else if (arg === "--config" || arg === "-c" || arg.startsWith("--config=")) {
+      if (options.configFile !== undefined) {
+        throw new Error("Specify --config only once")
+      }
+      const inline = arg.startsWith("--config=")
+      const value = inline ? arg.slice("--config=".length) : argv[++index]
+      if (value === undefined || value.trim() === "" || (!inline && value.startsWith("-"))) {
+        throw new Error("--config requires a file path")
+      }
+      options.configFile = value
+    } else if (arg.startsWith("-")) {
+      throw new Error(`Unknown option: ${arg}`)
+    } else {
+      options.positional.push(arg)
+    }
+  }
+
+  return options
+}
+
+async function main() {
+  const options = parseArgs(process.argv.slice(2))
+  const command = options.positional[0] ?? "help"
+
+  if (options.help) {
+    help()
+    return 0
+  }
+  if (options.version) {
+    console.log(VERSION)
+    return 0
+  }
+
+  if (command === "help") {
+    help()
+    return 0
+  }
+  if (options.positional.length > 1) {
+    throw new Error(`Unexpected argument: ${options.positional[1]}`)
+  }
+
+  const filename = resolveConfigPath(options.configFile)
+  if (command === "init") {
+    return initCommand(filename, options)
+  }
+
+  if (command === "path") {
+    console.log(filename)
+    return 0
+  }
+  if (command === "validate") return validateCommand(filename)
+  if (command === "plan") return planCommand(filename)
+  if (command === "sync") {
+    return syncCommand(filename, options)
+  }
+
+  throw new Error(`Unknown command: ${command}`)
+}
+
+try {
+  const code = await main()
+  process.exitCode = code
+} catch (error) {
+  console.error(`${COMMAND_NAME}: ${error.message}`)
+  process.exitCode = 1
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@wangkh/skill-sync-cli",
+  "version": "0.1.0",
+  "description": "Sync declared agent skills across machines through the skills CLI",
+  "author": "wkh",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yudaiyan/skill-sync-cli.git"
+  },
+  "homepage": "https://github.com/yudaiyan/skill-sync-cli#readme",
+  "bugs": {
+    "url": "https://github.com/yudaiyan/skill-sync-cli/issues"
+  },
+  "keywords": ["skills", "agent-skills", "cli", "dotfiles", "opencode", "codex"],
+  "type": "module",
+  "bin": {
+    "skill-sync-cli": "bin/skill-sync.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "schemas",
+    "README.md",
+    "README.zh-CN.md",
+    "RELEASING.md",
+    "skills.json.example",
+    "LICENSE"
+  ],
+  "scripts": {
+    "init": "node ./bin/skill-sync.mjs init",
+    "path": "node ./bin/skill-sync.mjs path",
+    "validate": "node ./bin/skill-sync.mjs validate",
+    "plan": "node ./bin/skill-sync.mjs plan",
+    "sync": "node ./bin/skill-sync.mjs sync",
+    "test": "node --test",
+    "check": "npm test",
+    "test:package": "node ./scripts/verify-package.mjs",
+    "prepublishOnly": "npm run check && npm run test:package"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "engines": {
+    "node": ">=18.17"
+  },
+  "license": "MIT"
+}

package/schemas/skills-sync.schema.json

@@ -0,0 +1,67 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "skill-sync-cli manifest",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["version", "skills"],
+  "properties": {
+    "version": {
+      "const": 1
+    },
+    "cli": {
+      "$ref": "#/$defs/cli"
+    },
+    "defaults": {
+      "$ref": "#/$defs/defaults"
+    },
+    "skills": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "$ref": "#/$defs/skill"
+      }
+    }
+  },
+  "$defs": {
+    "cli": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "package": { "type": "string", "minLength": 1 },
+        "version": { "type": "string", "minLength": 1 }
+      }
+    },
+    "defaults": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "agents": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "scope": { "enum": ["global", "project"] },
+        "copy": { "type": "boolean" }
+      }
+    },
+    "skill": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "source"],
+      "properties": {
+        "name": { "type": "string", "minLength": 1 },
+        "source": { "type": "string", "minLength": 1 },
+        "description": { "type": "string", "minLength": 1 },
+        "ref": { "type": "string", "minLength": 1 },
+        "enabled": { "type": "boolean" },
+        "agents": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "scope": { "enum": ["global", "project"] },
+        "copy": { "type": "boolean" }
+      }
+    }
+  }
+}

package/skills.json.example

@@ -0,0 +1,24 @@
+{
+  "version": 1,
+  "cli": {
+    "package": "skills",
+    "version": "1.5.22"
+  },
+  "defaults": {
+    "agents": ["opencode"],
+    "scope": "global",
+    "copy": true
+  },
+  "skills": [
+    {
+      "name": "find-skills",
+      "source": "vercel-labs/skills",
+      "description": "查找和安装更多 Skills"
+    },
+    {
+      "name": "agent-browser",
+      "source": "vercel-labs/agent-browser",
+      "description": "网页浏览、表单操作和浏览器自动化"
+    }
+  ]
+}

package/src/commands.mjs

@@ -0,0 +1,134 @@
+import { access, mkdir, writeFile } from "node:fs/promises"
+import path from "node:path"
+import {
+  readManifest,
+  normalizeManifest,
+  DEFAULT_SKILLS_CLI,
+} from "./manifest.mjs"
+import {
+  commandFor,
+  displayCommand,
+  runCommand,
+  statusCode,
+} from "./runner.mjs"
+
+const SAMPLE_MANIFEST = {
+  version: 1,
+  cli: {
+    package: "skills",
+    version: DEFAULT_SKILLS_CLI,
+  },
+  defaults: {
+    agents: ["opencode"],
+    scope: "global",
+    copy: true,
+  },
+  skills: [
+    {
+      name: "find-skills",
+      source: "vercel-labs/skills",
+      description: "查找和安装更多 Skills",
+    },
+  ],
+}
+
+function enabledSkills(manifest) {
+  return manifest.skills.filter((skill) => skill.enabled)
+}
+
+export async function validateCommand(manifestFilename) {
+  const { path: filename, manifest } = await readManifest(manifestFilename)
+  const enabled = enabledSkills(manifest)
+  for (const skill of enabled) commandFor(skill, manifest.cli)
+  console.log(`Valid manifest: ${filename}`)
+  console.log(`Declared skills: ${manifest.skills.length}`)
+  console.log(`Enabled skills: ${enabled.length}`)
+  return 0
+}
+
+export async function planCommand(manifestFilename) {
+  const { path: filename, manifest } = await readManifest(manifestFilename)
+  const skills = enabledSkills(manifest)
+
+  console.log(`Manifest: ${filename}`)
+  if (skills.length === 0) {
+    console.log("No enabled skills.")
+    return 0
+  }
+
+  for (const skill of skills) {
+    if (skill.description) console.log(`# ${skill.name}: ${skill.description}`)
+    console.log(displayCommand(commandFor(skill, manifest.cli)))
+  }
+  return 0
+}
+
+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) }))
+
+  if (skills.length === 0) {
+    console.log("No enabled skills.")
+    return 0
+  }
+
+  console.log(`Syncing ${skills.length} skill${skills.length === 1 ? "" : "s"} from ${filename}`)
+  let failures = 0
+
+  for (const { skill, command } of commands) {
+    console.log(`\n[${skill.name}] ${skill.source}${skill.ref ? ` @ ${skill.ref}` : ""}`)
+    if (skill.description) console.log(skill.description)
+
+    if (options.dryRun) {
+      console.log(displayCommand(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
+    }
+  }
+
+  if (failures > 0) {
+    console.error(`Sync failed for ${failures} skill${failures === 1 ? "" : "s"}.`)
+    return 1
+  }
+
+  if (!options.dryRun) console.log("\nSync complete.")
+  return 0
+}
+
+export async function initCommand(manifestFilename, { force = false } = {}) {
+  const filename = path.resolve(manifestFilename)
+  if (!force) {
+    try {
+      await access(filename)
+      throw new Error(`Manifest already exists: ${filename} (use --force to replace it)`)
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error
+    }
+  }
+
+  await mkdir(path.dirname(filename), { recursive: true })
+  await writeFile(filename, `${JSON.stringify(SAMPLE_MANIFEST, null, 2)}\n`, {
+    encoding: "utf8",
+    flag: force ? "w" : "wx",
+  })
+  console.log(`Created ${filename}`)
+  return 0
+}
+
+export function sampleManifest() {
+  return normalizeManifest(SAMPLE_MANIFEST)
+}

package/src/config.mjs

@@ -0,0 +1,21 @@
+import os from "node:os"
+import path from "node:path"
+
+export const USER_CONFIG_RELATIVE_PATH = [".config", "skill-sync", "skills.json"]
+
+export function configPath(home = os.homedir()) {
+  return path.join(home, ...USER_CONFIG_RELATIVE_PATH)
+}
+
+export function resolveConfigPath(filename, { cwd = process.cwd(), userHome = os.homedir() } = {}) {
+  if (filename === undefined) return configPath(userHome)
+  if (typeof filename !== "string" || filename.trim() === "") {
+    throw new Error("--config requires a file path")
+  }
+  if (/^[a-z][a-z0-9+.-]*:\/\//i.test(filename) || filename.startsWith("git@")) {
+    throw new Error("--config expects a local file path. Clone the configuration repository first.")
+  }
+  if (filename === "~") return userHome
+  if (/^~[\\/]/.test(filename)) return path.resolve(userHome, filename.slice(2))
+  return path.resolve(cwd, filename)
+}

package/src/manifest.mjs

@@ -0,0 +1,228 @@
+import { readFile } from "node:fs/promises"
+import path from "node:path"
+
+export const MANIFEST_VERSION = 1
+export const DEFAULT_SKILLS_CLI = "1.5.22"
+export const DEFAULT_AGENTS = ["opencode"]
+export const DEFAULT_SCOPE = "global"
+export const DEFAULT_COPY = true
+
+function fail(message) {
+  throw new Error(`Invalid skills manifest: ${message}`)
+}
+
+function isPlainObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+}
+
+function assertString(value, label, { allowEmpty = false } = {}) {
+  if (typeof value !== "string" || (!allowEmpty && value.trim() === "")) {
+    fail(`${label} must be a non-empty string`)
+  }
+  return value.trim()
+}
+
+function assertStringArray(value, label) {
+  if (!Array.isArray(value) || value.length === 0) {
+    fail(`${label} must be a non-empty array of strings`)
+  }
+
+  const result = value.map((item, index) =>
+    assertString(item, `${label}[${index}]`),
+  )
+
+  if (new Set(result).size !== result.length) {
+    fail(`${label} must not contain duplicate values`)
+  }
+
+  return result
+}
+
+function assertBoolean(value, label) {
+  if (typeof value !== "boolean") fail(`${label} must be a boolean`)
+  return value
+}
+
+function isLocalSource(source) {
+  return (
+    source === "." ||
+    source === ".." ||
+    source.startsWith("./") ||
+    source.startsWith("../") ||
+    source.startsWith("/") ||
+    /^[a-zA-Z]:[\\/]/.test(source)
+  )
+}
+
+function validateSource(source, label) {
+  if (isLocalSource(source)) {
+    fail(`${label} is a local path; use a remote Git, URL, or archive source`)
+  }
+
+  if (/\r|\n|\0/.test(source)) {
+    fail(`${label} contains a control character`)
+  }
+
+  return source
+}
+
+function validateRef(ref, label) {
+  if (/[\r\n\0#]/.test(ref)) {
+    fail(`${label} contains an invalid character`)
+  }
+  return ref
+}
+
+function normalizeDefaults(rawDefaults) {
+  if (rawDefaults === undefined) return {
+    agents: [...DEFAULT_AGENTS],
+    scope: DEFAULT_SCOPE,
+    copy: DEFAULT_COPY,
+  }
+
+  if (!isPlainObject(rawDefaults)) fail("defaults must be an object")
+
+  const agents = rawDefaults.agents === undefined
+    ? [...DEFAULT_AGENTS]
+    : assertStringArray(rawDefaults.agents, "defaults.agents")
+  const scope = rawDefaults.scope === undefined
+    ? DEFAULT_SCOPE
+    : assertString(rawDefaults.scope, "defaults.scope")
+  const copy = rawDefaults.copy === undefined
+    ? DEFAULT_COPY
+    : assertBoolean(rawDefaults.copy, "defaults.copy")
+
+  if (scope !== "global" && scope !== "project") {
+    fail('defaults.scope must be "global" or "project"')
+  }
+
+  return { agents, scope, copy }
+}
+
+function normalizeCli(rawCli) {
+  if (rawCli === undefined) {
+    return { package: "skills", version: DEFAULT_SKILLS_CLI }
+  }
+
+  if (!isPlainObject(rawCli)) fail("cli must be an object")
+
+  const packageName = rawCli.package === undefined
+    ? "skills"
+    : assertString(rawCli.package, "cli.package")
+  const version = rawCli.version === undefined
+    ? DEFAULT_SKILLS_CLI
+    : assertString(rawCli.version, "cli.version")
+
+  if (/\s|[;&|<>`$]/.test(packageName)) {
+    fail("cli.package contains shell-like characters")
+  }
+
+  if (/\s|[;&|<>`$]/.test(version)) {
+    fail("cli.version contains shell-like characters")
+  }
+
+  return { package: packageName, version }
+}
+
+function normalizeSkill(rawSkill, index, defaults) {
+  if (!isPlainObject(rawSkill)) fail(`skills[${index}] must be an object`)
+
+  const name = assertString(rawSkill.name, `skills[${index}].name`)
+  const source = validateSource(
+    assertString(rawSkill.source, `skills[${index}].source`),
+    `skills[${index}].source`,
+  )
+  const ref = rawSkill.ref === undefined
+    ? undefined
+    : validateRef(assertString(rawSkill.ref, `skills[${index}].ref`), `skills[${index}].ref`)
+  const description = rawSkill.description === undefined
+    ? undefined
+    : assertString(rawSkill.description, `skills[${index}].description`)
+  const enabled = rawSkill.enabled === undefined
+    ? true
+    : assertBoolean(rawSkill.enabled, `skills[${index}].enabled`)
+  const agents = rawSkill.agents === undefined
+    ? [...defaults.agents]
+    : assertStringArray(rawSkill.agents, `skills[${index}].agents`)
+  const scope = rawSkill.scope === undefined
+    ? defaults.scope
+    : assertString(rawSkill.scope, `skills[${index}].scope`)
+  const copy = rawSkill.copy === undefined
+    ? defaults.copy
+    : assertBoolean(rawSkill.copy, `skills[${index}].copy`)
+
+  if (scope !== "global" && scope !== "project") {
+    fail(`skills[${index}].scope must be "global" or "project"`)
+  }
+
+  const unknownKeys = Object.keys(rawSkill).filter((key) =>
+    !["name", "source", "description", "ref", "enabled", "agents", "scope", "copy"].includes(key),
+  )
+  if (unknownKeys.length > 0) {
+    fail(`skills[${index}] contains unknown field(s): ${unknownKeys.join(", ")}`)
+  }
+
+  return { name, source, description, ref, enabled, agents, scope, copy }
+}
+
+export function normalizeManifest(raw) {
+  if (!isPlainObject(raw)) fail("root value must be an object")
+
+  if (raw.version !== MANIFEST_VERSION) {
+    fail(`version must be ${MANIFEST_VERSION}`)
+  }
+
+  if (!Array.isArray(raw.skills) || raw.skills.length === 0) {
+    fail("skills must be a non-empty array")
+  }
+
+  const defaults = normalizeDefaults(raw.defaults)
+  const cli = normalizeCli(raw.cli)
+  const skills = raw.skills.map((skill, index) =>
+    normalizeSkill(skill, index, defaults),
+  )
+
+  const identities = new Set()
+  for (const skill of skills) {
+    const identity = JSON.stringify([
+      skill.source,
+      skill.ref ?? null,
+      skill.name,
+      skill.scope,
+      skill.agents,
+    ])
+    if (identities.has(identity)) {
+      fail(`duplicate skill declaration: ${skill.name} from ${skill.source}`)
+    }
+    identities.add(identity)
+  }
+
+  return { version: MANIFEST_VERSION, cli, defaults, skills }
+}
+
+export async function readManifest(filename) {
+  const absolutePath = path.resolve(filename)
+  let text
+  try {
+    text = await readFile(absolutePath, "utf8")
+  } catch (error) {
+    throw new Error(`Cannot read manifest ${absolutePath}: ${error.message}`)
+  }
+
+  let raw
+  try {
+    raw = JSON.parse(text)
+  } catch (error) {
+    throw new Error(`Cannot parse manifest ${absolutePath}: ${error.message}`)
+  }
+
+  return { path: absolutePath, manifest: normalizeManifest(raw) }
+}
+
+export function sourceWithRef(source, ref) {
+  if (!ref) return source
+  if (source.includes("#")) {
+    throw new Error(`Source already contains a ref fragment; remove ref or use one source ref: ${source}`)
+  }
+  return `${source}#${encodeURIComponent(ref)}`
+}

package/src/runner.mjs

@@ -0,0 +1,86 @@
+import { spawnSync } from "node:child_process"
+import { existsSync } from "node:fs"
+import path from "node:path"
+import { sourceWithRef } from "./manifest.mjs"
+
+function npxExecutable() {
+  return process.platform === "win32" ? "npx.cmd" : "npx"
+}
+
+function packageSpec(cli) {
+  if (!cli.version || cli.version === "latest") return cli.package
+  if (cli.package.startsWith("@")) {
+    const slash = cli.package.indexOf("/")
+    const at = cli.package.indexOf("@", slash)
+    if (at !== -1) return cli.package
+  }
+  if (cli.package.includes("@")) return cli.package
+  return `${cli.package}@${cli.version}`
+}
+
+export function commandFor(skill, cli) {
+  const args = ["--yes", packageSpec(cli), "add", sourceWithRef(skill.source, skill.ref)]
+
+  for (const agent of skill.agents) {
+    args.push("--agent", agent)
+  }
+
+  args.push("--skill", skill.name)
+
+  if (skill.scope === "global") args.push("--global")
+  if (skill.copy) args.push("--copy")
+  args.push("--yes")
+
+  return { executable: npxExecutable(), args }
+}
+
+function quoteForDisplay(value) {
+  if (/^[a-zA-Z0-9_./:@%+=,-]+$/.test(value)) return value
+  return process.platform === "win32"
+    ? `'${value.replaceAll("'", "''")}'`
+    : `'${value.replaceAll("'", "'\\''")}'`
+}
+
+export function displayCommand(command) {
+  return [command.executable, ...command.args].map(quoteForDisplay).join(" ")
+}
+
+function windowsNpxCli(env) {
+  const searchPath = Object.entries(env).find(([key]) => key.toLowerCase() === "path")?.[1] ?? ""
+  const candidates = [
+    env.npm_execpath && path.join(path.dirname(env.npm_execpath), "npx-cli.js"),
+    ...searchPath.split(path.delimiter).filter(Boolean).map((directory) =>
+      path.join(directory.replace(/^"|"$/g, ""), "node_modules", "npm", "bin", "npx-cli.js"),
+    ),
+    path.join(path.dirname(process.execPath), "node_modules", "npm", "bin", "npx-cli.js"),
+  ]
+  const filename = candidates.find((candidate) => candidate && existsSync(candidate))
+  if (!filename) {
+    throw new Error("Cannot find npm's npx-cli.js. Install Node.js with npm, then run npm run sync.")
+  }
+  return filename
+}
+
+export function runCommand(command, { cwd, env = process.env, timeout } = {}) {
+  try {
+    // Windows cannot spawn .cmd files directly. Run npx's JS entry point so
+    // manifest values stay literal arguments and never pass through a shell.
+    const useNode = process.platform === "win32" && command.executable === "npx.cmd"
+    return spawnSync(useNode ? process.execPath : command.executable,
+      useNode ? [windowsNpxCli(env), ...command.args] : command.args, {
+        cwd,
+        env,
+        timeout,
+        stdio: "inherit",
+        windowsHide: true,
+      })
+  } catch (error) {
+    return { status: null, error }
+  }
+}
+
+export function statusCode(result) {
+  if (typeof result.status === "number") return result.status
+  if (result.error) return 1
+  return 1
+}