manage-skills

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Before doing anything

操作前准备

Resolve the CLI first, then use the path it prints. Run this once (POSIX shell):
bash
```
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
```
Substitute the printed path into every command below, wherever the examples write
```
$SM
```
. Do not carry
```
$SM
```
as a shell variable: each command you run is a new shell, so an assignment made here is gone by the next one.
The three outcomes:
- A path under
  ~/.skills-manager/bin
  — the desktop app published this copy, and the
```
.version
```
  stamp appears only after it has been verified, so it always matches the app the user is running. Use it.
- BRIDGE_BROKEN
  — something the app left behind is here but does not add up: an unstamped binary, or a stamp with no binary beside it. Either is what a copy that failed half-way leaves. Stop. Do not go looking for another CLI: that binary may predate a safety fix, and the machine has a desktop app whose version nothing here can match. Ask the user to open the Skills Manager app once, which republishes it.
- A path from PATH — nothing was ever published here, so there is no stale copy to worry about: this is a CLI-only machine (a server install, a standalone download, a hand-built binary). Use it, but note it can be older than a desktop app if one is also installed.
If nothing is printed at all, this skill doesn't apply — fall back to find-skills, or tell the user to install Skills Manager.
Always pass
--json
when you parse output yourself. Pretty-printed output is for the user; JSON is for you. Errors include
```
ok=false
```
, a stable
```
code
```
, and
```
message
```
on stderr with a non-zero exit code.

bash

"$SM" --json skills list

先确定CLI路径，再使用其输出的路径。运行以下命令一次（POSIX Shell环境）：
bash
```
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版本：该二进制文件可能早于某个安全修复，且当前机器上的桌面应用版本无法与任何本地CLI匹配。请让用户打开Skills Manager应用一次，它会重新发布正确的CLI文件。
- 返回PATH中的路径——从未在此处发布过CLI文件，因此无需担心存在过时副本：这是仅安装了CLI的机器（如服务器安装、独立下载或手动编译的二进制文件）。可以使用该路径，但需注意如果同时安装了桌面应用，CLI版本可能比桌面应用旧。
如果没有任何输出，则该技能不适用——请改用find-skills，或告知用户安装Skills Manager。
当你自行解析输出时，务必添加
--json
参数。格式化输出是给用户看的，JSON格式才适合程序解析。错误信息会包含
```
ok=false
```
、稳定的
```
code
```
字段，以及stderr中的
```
message
```
内容，同时返回非零退出码。

bash

"$SM" --json skills list

When a deployment is refused

当部署被拒绝时

A deploy that would overwrite something that is not ours is refused outright — nothing at those paths is deleted, and nothing else in the batch is applied. That failure is machine-readable, so report the actual paths rather than the sentence:

json

{"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"}]}}

Tell the user which path is in the way, that its contents are untouched, and offer the two ways out: adopt it into the library (

skills adopt

), or move it aside and retry. Never delete it for them.

如果部署会覆盖非Skills Manager管理的内容，会直接被拒绝——该路径下的内容不会被删除，批次中的其他操作也不会执行。该失败信息是机器可读的，因此请直接报告具体路径而非描述性语句：

json

{"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

命令），或移走该路径后重试。切勿替用户删除该路径。

Mental model

核心逻辑

There's one central library at

~/.skills-manager/skills/

that all agents share. Each skill has source metadata, preset membership, tags, and zero or more real deployments in agent directories. A preset is a reusable group; several presets may be deployed at the same time.

Keep these three states separate:

Library: install/remove controls whether Skills Manager owns the skill.
Preset membership:
```
presets add-skill/remove-skill
```
organizes the library only.
Deployment:
```
skills deploy/undeploy
```
and
```
presets deploy/undeploy
```
control what an agent can actually see.

Internally, presets are still stored as scenarios for backward-compatible Git Backup. The CLI and UI call them presets.

所有Agent共享一个位于

~/.skills-manager/skills/

的中央技能库。每个技能都包含源元数据、预设成员信息、标签，以及在Agent目录中的0个或多个实际部署实例。预设是可复用的技能组；多个预设可同时部署。

请区分以下三种状态：

库状态：install/remove命令控制Skills Manager是否管理该技能。
预设成员关系：
```
presets add-skill/remove-skill
```
仅用于整理库中的技能。
部署状态：
```
skills deploy/undeploy
```
和
```
presets deploy/undeploy
```
控制Agent实际能访问的技能。

在内部，预设仍以场景形式存储，以兼容旧版Git备份功能。CLI和UI均称其为预设。

Install

安装技能

bash

undefined

bash

undefined

From skills.sh marketplace

从skills.sh市场安装

"$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)

从任意Git URL安装（当技能位于子目录时，使用/tree/branch/subpath格式）

"$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


**Default is library-only** — the skill enters the DB but doesn't appear in any agent yet. Prefer an explicit follow-up deployment so scope is unambiguous:

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

--sync

and

--sync-preset

remain legacy shortcuts for the exclusive active-preset workflow.

Ref resolution is deterministic, no path-existence guessing:

Starts with
```
./
```
,
```
../
```
,
```
/
```
, or
```
~/
```
→ local path
Contains
```
://
```
, ends in
```
.git
```
, or starts with
```
git@
```
→ git URL

Matches

owner/repo

owner/repo/skill

, or

owner/repo@skill

→ skillssh

Otherwise → error; pass
```
--local
```
/
```
--git
```
/
```
--skillssh
```
to disambiguate

Always verify after install with

skills list

skills show <name>

so you can confirm the skill landed and report the preset / sync state back to the user.

"$SM" skills install foo/bar --skillssh "$SM" skills install ./looks-like/owner-repo --local


**默认仅安装到库中**——技能会进入数据库，但不会出现在任何Agent中。建议后续显式执行部署命令，以明确作用范围：

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

--sync

和

--sync-preset

仍是旧版专属活动预设工作流的快捷方式。

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

以
```
./
```
、
```
../
```
、
```
/
```
或
```
~/
```
开头 → 本地路径
包含
```
://
```
、以
```
.git
```
结尾或以
```
git@
```
开头 → Git URL

匹配

owner/repo

、

owner/repo/skill

或

owner/repo@skill

格式 → skillssh源

其他情况 → 报错；需通过
```
--local
```
/
```
--git
```
/
```
--skillssh
```
参数明确指定源类型

安装后务必验证，使用

skills list

或

skills show <name>

命令确认技能已成功安装，并向用户报告预设/同步状态。

Search

搜索技能

bash

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

Each result has

install_ref

(paste straight into

skills install

installs

(popularity proxy), and

skills_sh_url

. Show the top 1–3 with install counts before installing — anything with 10K+ installs is battle-tested; anything under 100 needs a careful look at the source repo.

bash

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

每个搜索结果包含

install_ref

（可直接复制到

skills install

命令中）、

installs

（安装量，作为流行度参考）和

skills_sh_url

。在安装前展示前1-3个结果及其安装量——安装量超过10K的技能是经过实战检验的；安装量不足100的技能需要仔细查看其源码仓库。

Update / Check

更新/检查更新

bash

undefined

bash

undefined

Re-fetch one skill (git/skillssh re-clones, local/import re-imports source dir)

更新单个技能（Git/skillssh源会重新克隆，本地/导入源会重新导入目录）

"$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` is the dry-run partner of `update`. Local-only skills (no git source) are reported as `skipped: true`.

**An update replaces the skill's directory wholesale**, so anything written inside it that the new version does not have would be destroyed. When the CLI detects that, it applies nothing and reports the paths instead:

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

The field is omitted entirely when nothing is held back, so test for its presence rather than for an empty array.

refreshed: false

with

held_back_removals

is not a failure and not something to retry — the skill is untouched and still on its old version. Show the user the listed paths and ask. There is no CLI flag to override this; only the desktop app can confirm and proceed, because only a person can say those files are expendable. The paths are prefixed with where they live (

library

, or an agent key for a deployed copy).

Note what this does not cover: a file the user edited that the new version also ships is reported as surviving, because its path survives — the update overwrites their edits silently. Warn anyone keeping local modifications inside a skill folder.

"$SM" skills check --all


`check`是`update`命令的预演版本。仅本地存在的技能（无Git源）会被标记为`skipped: true`。

**更新会完全替换技能目录**，因此目录中存在但新版本没有的文件会被删除。当CLI检测到这种情况时，不会执行任何操作，而是报告相关路径：

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

如果没有需要保留的文件，该字段会被省略，因此请检查该字段是否存在，而非检查数组是否为空。

refreshed: false

且包含

held_back_removals

不是失败，也无需重试——技能未被改动，仍为旧版本。请向用户展示列出的路径并询问。没有CLI参数可以覆盖此限制；只有桌面应用可以确认并继续操作，因为只有用户才能判断这些文件是否可以删除。路径前缀会标明文件位置（

library

表示库中，或Agent标识表示已部署的副本）。

请注意以下情况未被覆盖：用户编辑过的文件如果新版本也包含，会被覆盖且无提示。请提醒用户不要在技能文件夹内保留本地修改。

Remove

移除技能

bash

undefined

bash

undefined

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

实际删除需要添加--yes参数；JSON模式不会自动确认

"$SM" skills remove <skill> --yes


Remove deletes the central-library copy, all synced targets across agents, and the DB row. It's not reversible without re-installing.

"$SM" skills remove <skill> --yes


移除操作会删除中央库中的副本、所有Agent中的同步目标以及数据库记录。该操作不可撤销，除非重新安装。

Deploy / Undeploy

部署/取消部署技能

bash

"$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>

These commands change real managed deployments without deleting the central-library copy or changing preset membership.

skills enable/disable

are deprecated compatibility commands and do not change deployment; never use them.

skills deploy

and

skills undeploy

always require at least one explicit

--agent

, whether the command names one skill or several.

skills status

also reports target rows left by a custom agent that is no longer registered, so stale deployments stay visible and can be cleaned with an explicit undeploy while the row exists.

bash

"$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留下的目标记录，因此过时的部署会保持可见，并可通过显式取消部署操作清理。

Legacy exclusive sync

旧版专属同步模式

bash

undefined

bash

undefined

Sync current active preset to all enabled agents

将当前活动预设同步到所有启用的Agent

"$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)

仅同步到单个Agent（当某个Agent目录不同步时有用）

"$SM" skills sync --tool claude_code

undefined

"$SM" skills sync --tool claude_code

undefined

Adopt skills installed elsewhere

纳入其他位置安装的技能

When skills already live in an agent's directory (e.g. installed via

npx skills add

or manual

git clone

) but aren't in the central library, pull them in:

bash

undefined

当技能已存在于Agent目录中（例如通过

npx skills add

或手动

git clone

安装）但未在中央库中时，可将其纳入：

bash

undefined

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)

纳入所有找到的技能——每个技能都会被标记为source_type=local（无法从Git自动更新）

"$SM" skills adopt ~/.claude/skills

Adopt a single skill and pin it to a git source so

update

works later

纳入单个技能并绑定到Git源，以便后续使用

update

命令

"$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

当URL仅为仓库根目录时，需显式指定--git-subpath参数

"$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` auto-excludes anything already in the DB or already a sync target, so it's safe to re-run. `--git-url` requires either a URL with a subpath (`/tree/branch/path`) or an explicit `--git-subpath` — without that, future `update` would re-clone the wrong directory, so the CLI refuses to guess.

"$SM" skills adopt ~/.claude/skills/my-skill
--git-url https://github.com/me/my-skill --git-subpath ""


`adopt`命令会自动排除已在数据库中或已为同步目标的内容，因此可以安全地重复执行。`--git-url`参数需要包含子路径的URL（`/tree/branch/path`格式）或显式指定`--git-subpath`参数——否则后续的`update`命令会克隆错误的目录，因此CLI不会进行猜测。

标签管理

bash

"$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

Useful organization queries:

bash

"$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

bash

"$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>   # 查看单个技能的标签
"$SM" skills tag list           # 查看所有不同的标签

实用的分类查询命令：

bash

"$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

Presets

预设管理

bash

"$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

are additive and match the app's Preset pills. Explicit

presets apply/deactivate

commands remain for the legacy exclusive active-preset model; do not use them for normal "turn this preset on/off" requests.

The no-

--agent

defaults intentionally differ: deploy targets all installed, enabled coding agents; undeploy discovers the preset's actual target rows and removes them even when an agent is now disabled, uninstalled, or no longer registered. Use the no-agent undeploy for "turn this preset off everywhere."

Preset create/update/delete and add-skill/remove-skill are organization-only CLI operations. They never deploy or undeploy agent files implicitly.

bash

"$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>                  # 部署到所有启用的编码Agent
"$SM" presets deploy <preset> --agent codex
"$SM" presets undeploy <preset> --agent claude_code
"$SM" presets undeploy <preset>                # 从所有包含该预设目标记录的Agent中取消部署
"$SM" --json presets status <preset>

deploy/undeploy

命令是增量式的，与应用中的预设按钮功能一致。旧版专属活动预设模式的

presets apply/deactivate

命令仍存在，但不要用于常规的“开启/关闭预设”请求。

不带

--agent

参数的默认行为有所不同：deploy会部署到所有已安装且启用的编码Agent；undeploy会找到该预设的所有实际目标记录并移除，即使Agent已被禁用、卸载或注销。使用不带agent参数的undeploy命令可实现“在所有位置关闭该预设”。

预设的创建/更新/删除以及添加/移除技能操作仅用于整理库，不会隐式部署或取消部署Agent文件。

Health check

健康检查

When sync misbehaves or a command errors in a confusing way:

bash

"$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

and

agents list

are read-only and are the first checks for "why isn't this skill showing up in Cursor" questions.

agents disable

is a real mutation: it removes every managed deployment for that agent.

agents enable

makes the agent globally available again and re-syncs the legacy active preset, if one exists; use explicit skill or preset deployment afterward when the requested state is additive.

Use

agents disable <agent>

when the user wants the whole Agent integration turned off or wants every managed skill removed from it. If they only want one skill or preset removed while keeping the Agent available for future deployments, use

skills undeploy

presets undeploy

instead.

当同步行为异常或命令报错且原因不明时：

bash

"$SM" --json repo status   # 查看基础目录、技能/预设数量、活动预设
"$SM" --json agents list  # 查看检测到的Agent及其目标路径
"$SM" agents enable codex
"$SM" agents disable claude_code

repo status

和

agents list

是只读命令，是排查“为什么这个技能没有出现在Cursor中”这类问题的首选检查步骤。

agents disable

是实际修改操作：它会移除该Agent的所有托管部署。

agents enable

会重新全局启用该Agent，并同步旧版活动预设（如果存在）；之后请使用显式的技能或预设部署命令来实现增量部署。

当用户希望关闭整个Agent集成或移除该Agent的所有托管技能时，使用

agents disable <agent>

命令。如果用户仅希望移除某个技能或预设，同时保留Agent以供未来部署使用，请改用

skills undeploy

或

presets undeploy

命令。

Typical workflows

典型工作流

"Find me a skill for X" / "Install a skill that does X"

“帮我找一个能实现X的技能” / “安装一个能实现X的技能”

```
skills search "X" --limit 5
```
— show the top 1–3 hits with install counts and source.
If a clear winner:
```
skills install <install_ref>
```
.
If ambiguous: ask the user to pick.
Deploy it to the agent(s) the user requested with
```
skills deploy
```
.
```
skills status <name>
```
to confirm the library and deployment state.

执行
```
skills search "X" --limit 5
```
——展示前1-3个结果及其安装量和源信息。
如果有明确的最优选择：执行
```
skills install <install_ref>
```
。
如果结果不明确：请用户选择。
使用
```
skills deploy
```
命令将其部署到用户指定的Agent。
执行
```
skills status <name>
```
确认库状态和部署状态。

"What skills do I have?"

“我已经安装了哪些技能？”

bash

"$SM" --json skills list

The

preset_ids

presets

deployed_to

tags

, and

source_type

fields are usually the most informative. The legacy

enabled

field is not deployment state.

bash

"$SM" --json skills list

preset_ids

、

presets

、

deployed_to

、

tags

和

source_type

字段通常是最有用的。旧版

enabled

字段不代表部署状态。

"Pull in the skills already installed in my agent directories"

“把我Agent目录中已安装的技能纳入中央库”

```
skills adopt ~/.claude/skills --dry-run
```
(and any other agent dirs the user mentions) — show the candidate list.
After user confirms:
```
skills adopt ~/.claude/skills
```
.
For any adopted skill where the user knows the original repo, follow up with
```
skills adopt ... --git-url ... --git-subpath ...
```
to restore the update link.

执行
```
skills adopt ~/.claude/skills --dry-run
```
（以及用户提到的其他Agent目录）——展示候选技能列表。
用户确认后：执行
```
skills adopt ~/.claude/skills
```
。
对于用户知道原仓库的已纳入技能，后续执行
```
skills adopt ... --git-url ... --git-subpath ...
```
命令以恢复更新链接。

"Update everything"

“更新所有技能”

bash

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

Report which skills actually refreshed (

refreshed: true

in the JSON) vs which were already up-to-date.

bash

"$SM" skills check --all     # 查看哪些技能有上游更新
"$SM" skills update --all    # 应用更新

向用户报告哪些技能实际完成了更新（JSON中

refreshed: true

），哪些已经是最新版本。

Pitfalls

常见陷阱

Install succeeded but skill doesn't appear in the agent → install defaults to library-only. Use
```
skills deploy <skill> --agent <key>
```
.
Preset membership changed but agent files did not → membership is organization only. Follow with
```
presets deploy
```
or
```
skills deploy
```
when the user also asked to make it visible.
No active preset only affects legacy
```
skills sync
```
/
```
presets apply
```
; additive deploy commands do not require one.
Adopted skills can't be
update
d from git →
```
npx skills add
```
and manual
```
git clone
```
don't leave source metadata, so adopt has to treat them as
```
local
```
. Fix per-skill with
```
adopt ... --git-url ... --git-subpath ...
```
, or just
```
skills remove
```
+
```
skills install <git-ref>
```
to start clean with a real source.
Use
```
--dry-run
```
before bulk remove, tag delete, preset delete, deploy, or undeploy operations. Use
```
check
```
before
```
update
```
.

安装成功但技能未出现在Agent中→安装默认仅到库中。请使用
```
skills deploy <skill> --agent <key>
```
命令部署。
预设成员关系已更改但Agent文件未更新→成员关系仅用于整理库。当用户希望技能在Agent中可见时，请后续执行
```
presets deploy
```
或
```
skills deploy
```
命令。
无活动预设仅影响旧版
```
skills sync
```
/
```
presets apply
```
命令；增量部署命令不需要活动预设。
已纳入的技能无法从Git更新→
```
npx skills add
```
和手动
```
git clone
```
不会留下源元数据，因此纳入时会被标记为
```
local
```
。可通过
```
adopt ... --git-url ... --git-subpath ...
```
命令逐个修复，或直接执行
```
skills remove
```
+
```
skills install <git-ref>
```
命令重新安装，以获得完整的源支持。
在批量移除、删除标签、删除预设、部署或取消部署操作前，请使用
```
--dry-run
```
预演。在执行
```
update
```
前，请使用
```
check
```
命令检查。

manage-skills

Original

Translation

Before doing anything

操作前准备

When a deployment is refused

当部署被拒绝时

Mental model

核心逻辑

Install

安装技能

From skills.sh marketplace

从skills.sh市场安装

Any git URL (use /tree/branch/subpath form when the skill lives in a sub-directory)

从任意Git URL安装（当技能位于子目录时，使用/tree/branch/subpath格式）

Local folder

从本地文件夹安装

Force a source type when the ref is ambiguous

当引用模糊时，强制指定源类型

Search

搜索技能

Update / Check

更新/检查更新

Re-fetch one skill (git/skillssh re-clones, local/import re-imports source dir)

更新单个技能（Git/skillssh源会重新克隆，本地/导入源会重新导入目录）

Re-fetch all eligible skills

更新所有符合条件的技能

Just probe remote revisions, don't touch files

仅检查远程版本，不修改本地文件

Remove

移除技能

Always preview first when removing more than one

移除多个技能前务必先预演

--yes is required for the actual delete; --json mode does NOT auto-confirm

实际删除需要添加--yes参数；JSON模式不会自动确认

Deploy / Undeploy

部署/取消部署技能

Legacy exclusive sync

旧版专属同步模式

Sync current active preset to all enabled agents

将当前活动预设同步到所有启用的Agent

Preview the target list — safe, no writes

预览目标列表——安全操作，不会写入内容

Switch the one legacy active preset, then sync

切换到旧版活动预设，然后同步

Only sync to a single agent (useful when one agent's directory got out of sync)

仅同步到单个Agent（当某个Agent目录不同步时有用）

Adopt skills installed elsewhere

纳入其他位置安装的技能

Dry-run scan first — lists candidates without writing

先预演扫描——列出候选技能但不写入

Adopt everything found — each becomes source_type=local (can't auto-update from git)

纳入所有找到的技能——每个技能都会被标记为source_type=local（无法从Git自动更新）

Adopt a single skill and pin it to a git source so update works later

纳入单个技能并绑定到Git源，以便后续使用update命令

Or pass --git-subpath explicitly when the URL is just the repo root

当URL仅为仓库根目录时，需显式指定--git-subpath参数

Skill lives at the repo root? Pass an empty subpath

技能位于仓库根目录？传入空的子路径

Tag

标签管理

Presets

预设管理

Health check

健康检查

Typical workflows

典型工作流

"Find me a skill for X" / "Install a skill that does X"

“帮我找一个能实现X的技能” / “安装一个能实现X的技能”

"What skills do I have?"

“我已经安装了哪些技能？”

"Pull in the skills already installed in my agent directories"

“把我Agent目录中已安装的技能纳入中央库”

"Update everything"

“更新所有技能”

Pitfalls

常见陷阱

Adopt a single skill and pin it to a git source so
`update`
works later

纳入单个技能并绑定到Git源，以便后续使用
`update`
命令