migrate-skills-between-libraries

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Migrate Skills Between Libraries

在不同库之间迁移Skill

Goal

目标

Move skills from one library workspace to another without losing metadata, breaking dependencies, or duplicating entries.

在不丢失元数据、破坏依赖关系或产生重复条目的前提下，将Skill从一个库工作区迁移到另一个库工作区。

Guardrails

注意事项

Always use
```
--dry-run
```
before any mutating command in the target workspace.
Always use
```
--list
```
to inspect the source library before importing.
Always use
```
--format json
```
for structured output when scripting migrations.
Never import skills without checking for name collisions in the target workspace first.
Always run
```
build-docs
```
in the target workspace after migration.

在目标工作区执行任何变更命令前，务必先使用
```
--dry-run
```
参数。
导入前务必使用
```
--list
```
参数检查源库内容。
编写迁移脚本时，务必使用
```
--format json
```
获取结构化输出。
务必先检查目标工作区是否存在名称冲突，再导入Skill。
迁移完成后，务必在目标工作区运行
```
build-docs
```
命令。

Workflow

工作流程

Export: Identify skills to migrate from the source library

导出：确定要从源库迁移的Skill

List all skills in the source workspace.

bash

cd /path/to/source-library
npx ai-agent-skills list --format json --fields name,tier,workArea,collections

For house copies, note the skill folder paths. For upstream picks, note the installSource.

列出源工作区的所有Skill。

bash

cd /path/to/source-library
npx ai-agent-skills list --format json --fields name,tier,workArea,collections

对于内部拷贝（house copies），记录Skill文件夹路径。对于上游选取（upstream picks），记录installSource。

Import: Add skills to the target workspace

导入：将Skill添加到目标工作区

For house copies, use
```
vendor
```
to copy the skill folder into the target:

bash

cd /path/to/target-library
npx ai-agent-skills vendor /path/to/source-library --skill <name> --area <workArea> --branch <branch> --why "Migrated from source library." --dry-run
npx ai-agent-skills vendor /path/to/source-library --skill <name> --area <workArea> --branch <branch> --why "Migrated from source library."

For upstream picks, use
```
catalog
```
to re-catalog from the original source:

bash

npx ai-agent-skills catalog <owner>/<repo> --skill <name> --area <workArea> --branch <branch> --why "Migrated from source library." --dry-run
npx ai-agent-skills catalog <owner>/<repo> --skill <name> --area <workArea> --branch <branch> --why "Migrated from source library."

Rebuild docs in the target workspace.

bash

npx ai-agent-skills build-docs

Validate the target workspace.

bash

npx ai-agent-skills validate

对于内部拷贝，使用
```
vendor
```
命令将Skill文件夹复制到目标工作区：

bash

cd /path/to/target-library
npx ai-agent-skills vendor /path/to/source-library --skill <name> --area <workArea> --branch <branch> --why "Migrated from source library." --dry-run
npx ai-agent-skills vendor /path/to/source-library --skill <name> --area <workArea> --branch <branch> --why "Migrated from source library."

对于上游选取，使用
```
catalog
```
命令从原始源重新编入目录：

bash

npx ai-agent-skills catalog <owner>/<repo> --skill <name> --area <workArea> --branch <branch> --why "Migrated from source library." --dry-run
npx ai-agent-skills catalog <owner>/<repo> --skill <name> --area <workArea> --branch <branch> --why "Migrated from source library."

在目标工作区重建文档。

bash

npx ai-agent-skills build-docs

验证目标工作区。

bash

npx ai-agent-skills validate

Gotchas

常见问题

Skill names must be unique per workspace. Check for collisions before importing.
House copies are full folder copies — the source and target are independent after migration.
Upstream picks re-catalog from the original upstream source, not the intermediate library.
Dependencies (
```
requires
```
field) must also be migrated. Check
```
info --format json
```
for each skill's dependency graph.
Collection membership does not transfer automatically. Use
```
curate --collection <id>
```
to add migrated skills to target collections.

Skill名称在单个工作区内必须唯一，导入前请检查是否存在冲突。
内部拷贝是完整的文件夹复制——迁移完成后源和目标相互独立。
上游选取是从原始上游源重新编入目录，而非从中间库获取。
依赖项（
```
requires
```
字段）也必须一并迁移，可通过
```
info --format json
```
查看每个Skill的依赖图。
集合归属不会自动转移，可使用
```
curate --collection <id>
```
将已迁移的Skill添加到目标集合中。