manage-skills

开始操作前

1. **先解析 CLI，然后使用它打印的路径。**运行一次（POSIX shell）：

   D="$HOME/.skills-manager/bin"
   B="$D/skills-manager-cli"; [ -e "$B" ] || B="$B.exe"   # .exe on Windows
   if [ -s "$D/.version" ] && [ -x "$B" ]; then
     echo "$B"
   elif [ -s "$D/.version" ] || [ -e "$B" ]; then
     echo BRIDGE_BROKEN
   else
     P="$(command -v skills-manager-cli 2>/dev/null || true)"
     [ -x "$P" ] && echo "$P"
   fi
   

   将打印出的路径代入下面每条命令中，替换示例里的 $SM。不要将 $SM 保留为 shell 变量：每次运行命令都会启动一个新的 shell，因此这里设置的变量到下一条命令时就不存在了。

   三种结果：

   • ~/.skills-manager/bin 下的路径——桌面应用发布了这份副本，并且只有在验证通过后才会出现 .version 标记，因此它始终与用户正在运行的应用匹配。使用它。
   • BRIDGE_BROKEN——应用留下了东西，但状态不一致：可能是没有标记的二进制文件，也可能是有标记但旁边没有二进制文件。两种情况都是副本只完成了一半时留下的。**停止。**不要去找另一个 CLI：那个二进制文件可能早于某个安全修复，而且这台机器上有一个桌面应用，其版本无法与这里的任何内容匹配。请用户打开一次 Skills Manager 应用，它会重新发布该文件。
   • 来自 PATH 的路径——这里从未发布过文件，因此无需担心有过时副本：这是一台仅安装 CLI 的机器（服务器安装、独立下载或手动构建的二进制文件）。使用它，但请注意，如果也安装了桌面应用，它可能比桌面应用旧。

   如果完全没有打印任何内容，则此技能不适用——改用 find-skills，或告知用户安装 Skills Manager。

2. **自行解析输出时，始终传入 --json。**美化格式的输出供用户查看；JSON 供你使用。错误会在 stderr 中包含 ok=false、稳定的 code 和 message，并以非零退出码结束。

"$SM" --json skills list

部署被拒绝时

如果部署会覆盖不属于我们的内容，系统会直接拒绝——不会删除这些路径上的任何内容，也不会应用批次中的其他更改。 该失败可供机器读取，因此请报告实际路径，而不是那句话：

{"ok": false, "code": "TARGET_CONFLICT", "kind": "target_conflict",
 "message": "Refusing to deploy: 1 of 2 target(s) …",
 "details": {"conflicts": [{"path": "/Users/me/.claude/skills/db",
                            "reason": "is not a managed deployment"}]}}

告知用户是哪个路径造成阻碍，并说明其内容未被改动，然后提供两种解决方法：将其纳入库中（skills adopt），或将其移到别处后重试。绝不要替用户删除它。

心智模型

所有 Agent 共用一个中央库 ~/.skills-manager/skills/。每项技能都包含源元数据、预设归属、标签，以及在 Agent 目录中的零个或多个实际部署。预设是一组可重复使用的技能；可以同时部署多个预设。

请区分以下三种状态：

• 库：安装/移除决定 Skills Manager 是否管理这项技能。
• 预设归属：presets add-skill/remove-skill 仅整理库中的内容。
• 部署：skills deploy/undeploy 和 presets deploy/undeploy 控制 Agent 实际能看到什么。

在内部，预设仍以场景的形式存储，以兼容旧版 Git Backup。CLI 和 UI 将它们称为预设。

安装

# From skills.sh marketplace
"$SM" skills install vercel-labs/agent-skills@react-best-practices

# Any git URL (use /tree/branch/subpath form when the skill lives in a sub-directory)
"$SM" skills install https://github.com/anthropics/skills.git
"$SM" skills install https://github.com/foo/bar/tree/main/skills/baz

# Local folder
"$SM" skills install ./my-skill

# Force a source type when the ref is ambiguous
"$SM" skills install foo/bar --skillssh
"$SM" skills install ./looks-like/owner-repo --local

默认仅安装到库中——技能会进入数据库，但尚不会出现在任何 Agent 中。建议明确执行后续部署，以确保范围清晰：

"$SM" skills deploy <skill> --agent claude_code --agent codex

--sync 和 --sync-preset 仍是旧版快捷方式，用于独占的活动预设工作流。

引用解析是确定性的，不会猜测路径是否存在：

1. 以 ./、../、/ 或 ~/ 开头 → 本地路径
2. 包含 ://、以 .git 结尾，或以 git@ 开头 → Git URL
3. 匹配 owner/repo、owner/repo/skill 或 owner/repo@skill → skillssh
4. 否则 → 报错；传入 --local / --git / --skillssh 以消除歧义

安装后务必使用 skills list 或 skills show <name> 进行验证，以确认技能已安装，并向用户报告预设/同步状态。

搜索

"$SM" --json skills search "react performance" --limit 5

每个结果都有 install_ref（可直接粘贴到 skills install）、installs（受欢迎程度的参考指标）和 skills_sh_url。安装前展示排名前 1–3 的结果及其安装次数——安装量超过 10K 的技能经过了实战检验；低于 100 的则需要仔细检查源代码仓库。

更新 / 检查

# Re-fetch one skill (git/skillssh re-clones, local/import re-imports source dir)
"$SM" skills update <skill-name-or-id>

# Re-fetch all eligible skills
"$SM" skills update --all

# Just probe remote revisions, don't touch files
"$SM" skills check --all

check 是 update 的试运行搭档。从本地文件夹安装的技能会与该文件夹进行比较，而不是与任何 Git 远程仓库比较：update_available 表示该文件夹自导入后发生了更改，source_missing 表示该文件夹已不存在。每次都会执行此项检查；在一小时内免去 Git 远程仓库往返请求的缓存（使用 --force 可绕过）不适用于此检查。网站技能没有可供比较的对象，因此会返回 skipped: true。

更新会彻底替换技能目录，因此目录中有而新版本没有的内容都会被删除。CLI 检测到这种情况时，不会应用任何更改，而是报告相关路径：

{ "name": "ppt-master", "refreshed": false,
  "held_back_removals": ["library: templates/mine.pptx"] }

如果没有任何内容被保留，则完全不包含该字段；因此，应检查该字段是否存在，而不是检查数组是否为空。refreshed: false 且存在 held_back_removals 并不代表失败，也不需要重试——技能未被改动，仍是旧版本。向用户展示列出的路径并征求确认。没有 CLI 标志可以覆盖此操作；只有桌面应用可以确认并继续，因为只有用户本人才能判断这些文件是否可以丢弃。路径会带有其所在位置前缀（library，或已部署副本对应的 Agent 键）。

请注意，此机制无法保护以下内容：如果用户编辑过的文件也存在于新版本中，系统会报告该文件仍然存在，因为路径并未消失——更新会悄悄覆盖用户的修改。请提醒在技能目录中保留本地修改的用户。

移除

# Always preview first when removing more than one
"$SM" skills remove <skill> --dry-run

# --yes is required for the actual delete; --json mode does NOT auto-confirm
"$SM" skills remove <skill> --yes

移除操作会删除中央库中的副本、所有 Agent 上的同步目标以及数据库记录。除非重新安装，否则无法恢复。

部署 / 取消部署

"$SM" skills deploy <skill> --agent claude_code
"$SM" skills undeploy <skill> --agent codex
"$SM" skills deploy <skill-a> <skill-b> --agent codex --dry-run
"$SM" skills deploy <skill> --agent claude_code --agent codex
"$SM" --json skills status <skill>

这些命令会更改实际托管的部署，但不会删除中央库中的副本，也不会更改预设成员关系。skills enable/disable 是已弃用的兼容命令，不会更改部署；切勿使用。

无论命令指定一个还是多个技能，skills deploy 和 skills undeploy 都必须至少指定一个明确的 --agent。skills status 也会报告由已注销自定义 Agent 遗留的目标记录，因此过时的部署仍然可见，并可在记录存在时通过明确指定取消部署来清理。

旧版独占同步

# Sync current active preset to all enabled agents
"$SM" skills sync

# Preview the target list — safe, no writes
"$SM" skills sync --dry-run

# Switch the one legacy active preset, then sync
"$SM" skills sync --preset "Web Dev"

# Only sync to a single agent (useful when one agent's directory got out of sync)
"$SM" skills sync --tool claude_code

采用其他位置已安装的技能

如果技能已位于某个 Agent 的目录中（例如通过 npx skills add 安装，或手动执行 git clone 获取），但尚未加入中央库，则可将其导入：

# Dry-run scan first — lists candidates without writing
"$SM" skills adopt ~/.claude/skills --dry-run

# Adopt everything found — each becomes source_type=local (can't auto-update from git)
"$SM" skills adopt ~/.claude/skills

# Adopt a single skill and pin it to a git source so `update` works later
"$SM" skills adopt ~/.claude/skills/react-best-practices \
  --git-url https://github.com/vercel-labs/agent-skills/tree/main/react-best-practices

# Or pass --git-subpath explicitly when the URL is just the repo root
"$SM" skills adopt ~/.claude/skills/react-best-practices \
  --git-url https://github.com/vercel-labs/agent-skills \
  --git-subpath react-best-practices

# Skill lives at the repo root? Pass an empty subpath
"$SM" skills adopt ~/.claude/skills/my-skill \
  --git-url https://github.com/me/my-skill --git-subpath ""

adopt 会自动排除数据库中已有的内容以及已作为同步目标的内容，因此可以安全地重复运行。--git-url 必须包含子路径（/tree/branch/path），或者同时指定明确的 --git-subpath——否则后续 update 会重新克隆错误的目录，因此 CLI 不会尝试猜测。

--git-url 仅在采用技能时生效，此时该目录仍未受管理。技能进入库后，请使用下文的 set-source。

将技能重新指向 git 源

# Preview: resolves the source and reports whether content differs. It clones to
# a temp dir, but writes nothing to the library or the DB.
"$SM" --json skills set-source <skill> --git-url you/skills --subpath my-skill --dry-run

# A GitHub /tree/ URL carries the branch and subpath already
"$SM" skills set-source <skill> --git-url https://github.com/you/skills/tree/main/my-skill

以下说明如何将 local 技能改为由 git 提供支持，以便 update 生效，以及如何纠正指向错误仓库的技能。此操作会原位更新记录，因此技能 ID 会保留，与其关联的标签、预设成员关系和各 Agent 部署也都会保持不变。

• 此处的标志是 --subpath，而非 --git-subpath——后者用于 adopt。如果技能位于仓库根目录，请传入 --subpath ""，且仓库根目录本身必须包含 SKILL.md。
• --branch 会覆盖 URL 中指定的分支。
• 报告包含 content_changed——它是一个布尔值，不是文件列表。它会将新来源与当前为库副本记录的哈希值进行比较，而不是重新计算磁盘上目录的哈希值，因此之后在中心副本中所做的编辑不会被识别为差异。当它为 false 时，库副本不会被更改，这些编辑也会保留；无论结果如何，复制模式的部署都会重新同步。

--force 具有破坏性，且没有任何机制会保护用户的文件。 如果存在内容差异，不使用此标志时操作会被拒绝。使用后，整个技能目录都会被替换——先暂存，再交换，并删除旧副本——因此库副本中任何新来源未包含的内容都会丢失。与 skills update 不同，此路径不会检查 held_back_removals：不会保留任何内容，也不会询问。--dry-run 无法告知你具体哪些文件会受到影响，只能说明存在差异。绝不要替用户传入 --force——报告 content_changed: true，说明继续操作会整体覆盖库副本，并由用户决定。

标签

"$SM" skills tag add <skill> web frontend
"$SM" skills tag remove <skill> frontend
"$SM" skills tag set <skill> web frontend
"$SM" skills tag rename frontend web
"$SM" skills tag delete obsolete --dry-run
"$SM" skills tag delete obsolete --yes
"$SM" skills tag list <skill>   # tags on one skill
"$SM" skills tag list           # all distinct tags

实用的组织查询：

"$SM" --json skills list --untagged
"$SM" --json skills list --no-preset
"$SM" --json skills list --tag frontend
"$SM" --json skills list --preset "Web Dev"
"$SM" --json skills list --deployed-to codex

预设

"$SM" presets list
"$SM" presets current
"$SM" presets show "Web Dev"
"$SM" presets create "Web Dev" --description "Frontend work"
"$SM" presets update "Web Dev" --name "Frontend"
"$SM" presets delete "Old" --dry-run
"$SM" presets delete "Old" --yes

"$SM" presets add-skill <preset> <skill>...
"$SM" presets remove-skill <preset> <skill>...

"$SM" presets deploy <preset>                  # all enabled coding agents
"$SM" presets deploy <preset> --agent codex
"$SM" presets undeploy <preset> --agent claude_code
"$SM" presets undeploy <preset>                # every agent with target rows for this preset
"$SM" --json presets status <preset>

deploy/undeploy 是增量操作，与应用中的预设胶囊按钮一致。显式的 presets apply/deactivate 命令仍供旧版互斥活动预设模型使用；对于常规的“启用/关闭此预设”请求，不要使用这些命令。

不带 --agent 时的默认行为有意设置为不同：deploy 会针对所有已安装且已启用的编码 Agent；undeploy 会查找预设实际关联的目标记录，并将其移除，即使某个 Agent 目前已禁用、已卸载或不再注册。对于“在所有地方关闭此预设”，请使用不带 Agent 参数的 undeploy。

创建/更新/删除预设以及添加技能/移除技能，都是仅限组织使用的 CLI 操作。它们不会隐式部署或取消部署 Agent 文件。

健康检查

当同步行为异常或命令报错令人困惑时：

"$SM" --json repo status   # base dir, skill / preset counts, active preset
"$SM" --json agents list  # detected agents and their target paths
"$SM" agents enable codex
"$SM" agents disable claude_code

repo status 和 agents list 均为只读命令，是排查“为什么在 Cursor 中看不到此技能”问题的首选检查项。agents disable 会实际执行更改：它会移除此 Agent 的所有托管部署。agents enable 会重新启用该 Agent，使其全局可用，并在存在旧版活动预设时重新同步；如果请求的是增量状态，请随后显式部署技能或预设。

当用户希望彻底关闭整个 Agent 集成，或希望从中移除所有托管技能时，请使用 agents disable <agent>。如果用户只想移除某个技能或预设，同时保留 Agent 以便日后部署，请改用 skills undeploy 或 presets undeploy。

典型工作流

“帮我找一个用于 X 的技能” / “安装一个能完成 X 的技能”

1. skills search "X" --limit 5 — 显示排名靠前的 1–3 个结果，并附上安装次数和来源。
2. 如果有明显的首选项：skills install <install_ref>。
3. 如果选择不明确：请用户选择。
4. 使用 skills deploy 将其部署到用户指定的 Agent。
5. 使用 skills status <name> 确认库和部署状态。

“我有哪些技能？”

"$SM" --json skills list

preset_ids、presets、deployed_to、tags 和 source_type 字段通常最有参考价值。旧版 enabled 字段并不代表部署状态。

“导入我的 Agent 目录中已安装的技能”

1. skills adopt ~/.claude/skills --dry-run（以及用户提到的任何其他 Agent 目录）——显示候选列表。
2. 用户确认后：skills adopt ~/.claude/skills。
3. 对于用户知道原始仓库的任何已导入技能，使用 skills set-source <skill> --git-url ... --subpath ... 恢复更新链接。

“更新所有内容”

"$SM" skills check --all     # see what has upstream changes
"$SM" skills update --all    # apply

报告哪些技能实际已刷新（JSON 中 refreshed: true），哪些技能已是最新状态。

注意事项

• 安装成功，但技能没有出现在 Agent 中 → 安装默认只添加到库中。使用 skills deploy <skill> --agent <key>。
• 预设成员关系已更改，但 Agent 文件没有变化 → 成员关系仅用于组织管理。如果用户还要求让技能可见，请接着运行 presets deploy 或 skills deploy。
• 没有活动预设仅影响旧版 skills sync / presets apply；增量部署命令不需要活动预设。
• 已导入的技能无法从 Git 执行 update → npx skills add 和手动 git clone 不会留下源元数据，因此 adopt 必须将它们视为 local。使用 skills set-source 重新指定来源。此处不要尝试使用 adopt --git-url：adopt 只会创建新的库条目，而且错误会在后期才出现——--dry-run 会返回 ok: true，技能处于 skipped 状态，只有实际运行时才会报错：--git-url requires exactly one adoptable skill, found 0。也不要先移除再重新安装——那样会丢失技能 ID，以及与之关联的标签、预设成员关系和每个 Agent 的部署。
• 批量移除、删除标签、删除预设、部署或取消部署前，先使用 --dry-run。更新前先使用 check。