update-agent-skills

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Update Agent Skills

更新Agent技能

Goal

目标

Refresh installed agent skills with the standard

skills

CLI workflow.

Use the normal update command first. If the skills were installed with project scope and the CLI does not detect upstream changes, reinstall each tracked project skill explicitly from its recorded source.

For project-scoped installs, treat a no-change

npx skills update

result as a mandatory fallback trigger. Do not wait for separate proof that a specific skill is stale. Prefer the bundled reinstall script over manual command discovery. It already knows how to read

skills-lock.json

, filter to installed project skills, batch by repository, and pass non-interactive flags.

通过标准的

skills

CLI工作流刷新已安装的Agent技能。

首先使用常规更新命令。如果技能是通过项目级安装的，且CLI未检测到上游变更，则从其记录的源中显式重新安装每个被跟踪的项目技能。

对于项目级安装，将

npx skills update

显示无变更的结果视为触发强制回退流程的条件。无需等待单独的证据证明某个技能已过期。优先使用捆绑的重装脚本，而非手动查找命令。该脚本已内置读取

skills-lock.json

、筛选已安装的项目技能、按仓库批量处理以及传递非交互式标志的功能。

Detect the Installation Scope

检测安装范围

Check whether the target skills are project-scoped or global.
- Project-scoped installs usually have a local
```
skills-lock.json
```
  and one or more agent skill directories such as
```
.agents/skills/
```
  ,
```
.claude/skills/
```
  , or
```
.augment/skills/
```
  .
- Global installs are typically tracked outside the project, for example in
```
~/.agents/.skill-lock.json
```
  or
```
$XDG_STATE_HOME/skills/.skill-lock.json
```
  .
Check which skills are actually managed by the
```
skills
```
CLI.
- Use
```
skills-lock.json
```
  or the relevant global lock file as the source of truth.
- Do not assume custom or manually copied skills are tracked.
- For project-scoped installs, consider the installed skill directories under
```
.agents/skills/
```
  ,
```
.claude/skills/
```
  , or
```
.augment/skills/
```
  .

检查目标技能是项目级安装还是全局安装。
- 项目级安装通常会有本地的
```
skills-lock.json
```
  文件，以及一个或多个Agent技能目录，例如
```
.agents/skills/
```
  、
```
.claude/skills/
```
  或
```
.augment/skills/
```
  。
- 全局安装的跟踪文件通常位于项目外部，例如
```
~/.agents/.skill-lock.json
```
  或
```
$XDG_STATE_HOME/skills/.skill-lock.json
```
  。
检查哪些技能实际由
```
skills
```
CLI管理。
- 将
```
skills-lock.json
```
  或相关的全局锁文件作为事实来源。
- 不要假设自定义或手动复制的技能被跟踪。
- 对于项目级安装，需查看
```
.agents/skills/
```
  、
```
.claude/skills/
```
  或
```
.augment/skills/
```
  下的已安装技能目录。

Standard Update Flow

标准更新流程

Run:

bash

npx skills update

Branch on the installation scope and the command result:
- If the install is global and
```
npx skills update
```
  succeeds, stop there unless the user explicitly asked for a forced reinstall.
- If the install is project-scoped and the command clearly reports that one or more tracked skills were updated, stop there.
- If the install is project-scoped and the command reports
```
All skills are up to date
```
  , or otherwise makes no tracked-skill changes, go directly to the fallback flow below.
Do not use a presence check in the installed project skill directories to decide whether the fallback is needed. Presence only tells you which tracked skills exist locally and therefore must be reinstalled.
Do not pause to inspect
```
npx skills add --help
```
, read the CLI source, or rediscover flags unless the bundled script fails. That investigation slows the task down and is unnecessary for the normal fallback path.

运行以下命令：

bash

npx skills update

根据安装范围和命令结果进行分支处理：
- 若为全局安装且
```
npx skills update
```
  执行成功，则停止操作，除非用户明确要求强制重装。
- 若为项目级安装且命令明确报告一个或多个被跟踪技能已更新，则停止操作。
- 若为项目级安装且命令显示
```
All skills are up to date
```
  （所有技能均已更新），或未对被跟踪技能产生任何变更，则直接进入下方的回退流程。
不要通过检查已安装项目技能目录的存在与否来决定是否需要回退流程。目录存在仅能告诉你哪些被跟踪技能在本地存在，因此需要被重新安装。
除非捆绑脚本执行失败，否则不要暂停去查看
```
npx skills add --help
```
、阅读CLI源码或重新查找命令参数。这些调查会拖慢任务进度，且对于正常的回退路径来说是不必要的。

Fallback Flow for Project-Scoped Skills

项目级技能的回退流程

Open
```
skills-lock.json
```
.
Treat
```
skills-lock.json
```
as the source of truth for tracked skills.
Cross-check it against the installed project skill directories and only keep skills that are both:
- listed in
```
skills-lock.json
```
- present in at least one supported directory such as
```
.agents/skills/
```
  ,
```
.claude/skills/
```
  , or
```
.augment/skills/
```
The bundled script lives inside the installed
```
update-agent-skills
```
skill directory, not in the user's project
```
scripts/
```
folder.
Prefer the bundled script for the reinstall loop and run it immediately after a no-op project-scoped update. Resolve it from the installed skill path first:

bash

for dir in .agents/skills .claude/skills .augment/skills; do
  candidate="$dir/update-agent-skills/scripts/reinstall_project_skills_from_lock.sh"
  if [ -x "$candidate" ]; then
    "$candidate" --project-root .
    break
  fi
done

If the script is installed under
```
.agents/skills/update-agent-skills/
```
, prefer calling that path directly instead of searching the whole workspace.
If the script is not present in those standard installed skill paths, fall back to the manual grouped reinstall flow immediately. Do not use broad
```
find
```
or
```
rg
```
searches across the workspace just to rediscover the same script.
The script is the fast path because it batches skills that share a repository and uses
```
-y
```
to avoid interactive prompts.
If you do not use the script, and
```
npx skills update
```
was a no-op for a project-scoped install, reinstall every matching skill manually. Do not stop after inspecting just one skill, and do not conclude success merely because the directories are present.
For each matching skill or skill group that shares a repository, read its
```
source
```
and reinstall it explicitly.

bash

npx skills add [repository] --skill [skill]

Prefer the non-interactive form when reinstalling manually:

bash

npx skills add [repository] --skill [skill1] [skill2] ... -y

Repeat that command for every matching repository or skill. Do not stop after the first one, and do not guess missing repositories manually.

Example loop:

text

group tracked installed skills by repository:
  npx skills add [repository] --skill [skill1] [skill2] ... -y

Example:

bash

npx skills add https://github.com/code-sherpas/agent-skills --skill atomic-design update-agent-skills write-persistence-representations -y

If the
```
sourceType
```
is
```
github
```
and the
```
source
```
is recorded as
```
owner/repo
```
such as
```
github/awesome-copilot
```
, convert it to the repository form expected by the CLI, for example
```
https://github.com/owner/repo
```
.

打开
```
skills-lock.json
```
文件。
将
```
skills-lock.json
```
作为被跟踪技能的事实来源。
将其与已安装的项目技能目录进行交叉检查，仅保留同时满足以下条件的技能：
- 列在
```
skills-lock.json
```
  中
- 存在于至少一个支持的目录中，例如
```
.agents/skills/
```
  、
```
.claude/skills/
```
  或
```
.augment/skills/
```
捆绑脚本位于已安装的
```
update-agent-skills
```
技能目录内，而非用户项目的
```
scripts/
```
文件夹中。
优先使用捆绑脚本进行重装循环，并在项目级更新无操作后立即运行。首先从已安装技能路径中查找：

bash

for dir in .agents/skills .claude/skills .augment/skills; do
  candidate="$dir/update-agent-skills/scripts/reinstall_project_skills_from_lock.sh"
  if [ -x "$candidate" ]; then
    "$candidate" --project-root .
    break
  fi
done

如果脚本安装在
```
.agents/skills/update-agent-skills/
```
下，优先直接调用该路径，而非搜索整个工作区。
如果脚本不在这些标准的已安装技能路径中，立即回退到手动分组重装流程。不要在整个工作区使用
```
find
```
或
```
rg
```
进行大范围搜索来重新查找同一脚本。
该脚本是快速路径，因为它会对共享同一仓库的技能进行批量处理，并使用
```
-y
```
标志避免交互式提示。
若不使用脚本，且
```
npx skills update
```
在项目级安装中无操作，则手动重新安装每个匹配的技能。不要在检查完一个技能后就停止，也不要仅仅因为目录存在就判定操作成功。
对于每个匹配的技能或共享同一仓库的技能组，读取其
```
source
```
并显式重新安装。

bash

npx skills add [repository] --skill [skill]

手动重装时优先使用非交互式形式：

bash

npx skills add [repository] --skill [skill1] [skill2] ... -y

对每个匹配的仓库或技能重复该命令。不要在第一个命令执行后就停止，也不要手动猜测缺失的仓库。

示例循环：

text

group tracked installed skills by repository:
  npx skills add [repository] --skill [skill1] [skill2] ... -y

示例：

bash

npx skills add https://github.com/code-sherpas/agent-skills --skill atomic-design update-agent-skills write-persistence-representations -y

如果
```
sourceType
```
为
```
github
```
且
```
source
```
记录为
```
owner/repo
```
形式（例如
```
github/awesome-copilot
```
），需将其转换为CLI期望的仓库形式，例如
```
https://github.com/owner/repo
```
。

Interactive Choices

交互式选择

If the CLI prompts for installation details:

Agent selection: choose the default option unless the task says otherwise.
Scope: choose
```
Project
```
for project-scoped updates.
Installation method: choose
```
Symlink
```
.

如果CLI提示输入安装详情：

Agent选择：除非任务另有说明，否则选择默认选项。
范围：对于项目级更新，选择
```
Project
```
。
安装方式：选择
```
Symlink
```
。

Validation

验证

Before finishing:

Confirm the target skill directory now contains the updated skill content.
Confirm the refreshed skill still matches the source and the expected skill name.
If the install was project-scoped and
```
npx skills update
```
returned
```
All skills are up to date
```
, call out that this no-op result triggered the explicit reinstall loop.
Do not report success based only on the fact that the skill directories already existed before the reinstall.
If the bundled script was unavailable or failed and you had to fall back to manual commands, call that out explicitly.

完成操作前：

确认目标技能目录现在包含更新后的技能内容。
确认刷新后的技能仍与源和预期的技能名称匹配。
若为项目级安装且
```
npx skills update
```
返回
```
All skills are up to date
```
，需说明该无操作结果触发了显式重装循环。
不要仅根据重装前技能目录已存在就报告操作成功。
若捆绑脚本不可用或执行失败，不得不回退到手动命令，需明确说明这一点。

Report the Outcome

报告结果

When finishing the task:

State whether
```
npx skills update
```
worked or the fallback reinstall flow was needed.
State which skills were refreshed and from which repository.
State whether the update was project-scoped or global.

完成任务时：

说明
```
npx skills update
```
是否生效，或是否需要回退到重装流程。
说明哪些技能被刷新，以及来自哪个仓库。
说明更新是项目级还是全局级。