mirror of
https://github.com/runkids/skillshare.git
synced 2026-11-20 20:34:19 +00:00
docs(migration): add a path for moving from npx skills
Users who installed skills with npx skills had no migration steps; the FAQ only covered running both tools side by side. The new section maps where npx skills keeps its files and lock file, then walks through backup, collect, optional reinstall from the lock file, and sync. Behavior was checked in an isolated devcontainer environment: collect skips symlinks, plain sync preserves real directories in the universal target, and sync --force replaces them after backing up the target. Translated for zh-Hant, zh-Hans, ja and ko.
This commit is contained in:
@@ -82,6 +82,76 @@ skillshare sync
|
||||
|
||||
---
|
||||
|
||||
## From `npx skills`
|
||||
|
||||
If you installed skills with the [npx skills CLI](https://github.com/vercel-labs/skills) (`npx skills add ...`), skillshare can take over the same directories. You can also [run both tools side by side](/docs/troubleshooting/faq#using-universal-alongside-npx-skills) and only move the skills you want managed.
|
||||
|
||||
Where `npx skills` keeps things:
|
||||
|
||||
| Item | Global | Project |
|
||||
|------|--------|---------|
|
||||
| Skill files | `~/.agents/skills/<name>/` (real directories) | `.agents/skills/<name>/` |
|
||||
| Agent directories | Symlinks to the files above (for example `~/.claude/skills/<name>`) | Same |
|
||||
| Lock file | `~/.agents/.skill-lock.json` (or `$XDG_STATE_HOME/skills/.skill-lock.json`) | `skills-lock.json` |
|
||||
|
||||
Skills installed with `--copy` are real directories in each agent directory instead of symlinks.
|
||||
|
||||
### Step 1: Initialize skillshare
|
||||
|
||||
```bash
|
||||
skillshare init
|
||||
```
|
||||
|
||||
### Step 2: Backup existing skills
|
||||
|
||||
```bash
|
||||
skillshare backup
|
||||
```
|
||||
|
||||
### Step 3: Collect the skills
|
||||
|
||||
`collect` copies real directories and skips symlinks, so the symlinks in agent directories are not collected twice.
|
||||
|
||||
```bash
|
||||
skillshare collect universal --dry-run # Preview
|
||||
skillshare collect universal # ~/.agents/skills
|
||||
```
|
||||
|
||||
If you used `--copy` or have skills in other agent directories, run `skillshare collect --all` instead and resolve duplicates as described in [From Manual Management](#from-manual-management).
|
||||
|
||||
Collected skills are plain local copies. They do not remember which repository they came from, so `skillshare update` cannot update them.
|
||||
|
||||
### Step 4: Reinstall skills you want to keep updating (optional)
|
||||
|
||||
The lock file records where each skill came from. `source` is the repository and `skillPath` is the location inside it.
|
||||
|
||||
```bash
|
||||
cat ~/.agents/.skill-lock.json
|
||||
|
||||
# "source": "anthropics/skills", "skillPath": "skills/pdf/SKILL.md"
|
||||
skillshare install anthropics/skills/skills/pdf
|
||||
```
|
||||
|
||||
Use `--force` if the skill already exists in your source from Step 3.
|
||||
|
||||
### Step 5: Sync
|
||||
|
||||
```bash
|
||||
skillshare sync
|
||||
```
|
||||
|
||||
In merge mode, sync keeps a real directory of the same name in the target (`~/.agents/skills`) and reports it as a preserved local skill. The `npx skills` symlinks in other agent directories, such as `~/.claude/skills`, are repointed to your skillshare source. To also replace the real directories with symlinks, run this after Step 3 has collected them:
|
||||
|
||||
```bash
|
||||
skillshare sync --force
|
||||
```
|
||||
|
||||
`sync --force` backs up the target before replacing anything. After this, manage those skills with skillshare only. `npx skills` tracks installs in its own lock file, so avoid running `npx skills update` or `npx skills remove` on them.
|
||||
|
||||
For a project that uses `npx skills`, follow [From Committed Project Skills](#from-committed-project-skills) with `.agents/skills/` as the directory to move.
|
||||
|
||||
---
|
||||
|
||||
## From Git Submodules
|
||||
|
||||
If you've been using git submodules:
|
||||
|
||||
@@ -82,6 +82,76 @@ skillshare sync
|
||||
|
||||
---
|
||||
|
||||
## `npx skills` からの移行
|
||||
|
||||
[npx skills CLI](https://github.com/vercel-labs/skills)(`npx skills add ...`)で Skill をインストールしていた場合、skillshare は同じディレクトリを引き継げます。[両方のツールを併用](/docs/troubleshooting/faq#using-universal-alongside-npx-skills)し、skillshare で管理したい Skill だけを移すこともできます。
|
||||
|
||||
`npx skills` のファイルの保存場所:
|
||||
|
||||
| 項目 | Global | Project |
|
||||
|------|--------|---------|
|
||||
| Skill ファイル | `~/.agents/skills/<name>/`(実ディレクトリ) | `.agents/skills/<name>/` |
|
||||
| Agent ディレクトリ | 上記ファイルへのシンボリックリンク(例: `~/.claude/skills/<name>`) | 同じ |
|
||||
| ロックファイル | `~/.agents/.skill-lock.json`(または `$XDG_STATE_HOME/skills/.skill-lock.json`) | `skills-lock.json` |
|
||||
|
||||
`--copy` でインストールした Skill は、シンボリックリンクではなく各 Agent ディレクトリ内の実ディレクトリになります。
|
||||
|
||||
### ステップ 1: skillshare を初期化する
|
||||
|
||||
```bash
|
||||
skillshare init
|
||||
```
|
||||
|
||||
### ステップ 2: 既存の Skill をバックアップする
|
||||
|
||||
```bash
|
||||
skillshare backup
|
||||
```
|
||||
|
||||
### ステップ 3: Skill を収集する
|
||||
|
||||
`collect` は実ディレクトリをコピーし、シンボリックリンクはスキップします。そのため、Agent ディレクトリ内のシンボリックリンクが二重に収集されることはありません。
|
||||
|
||||
```bash
|
||||
skillshare collect universal --dry-run # プレビュー
|
||||
skillshare collect universal # ~/.agents/skills
|
||||
```
|
||||
|
||||
`--copy` を使っていた場合や、他の Agent ディレクトリにも Skill がある場合は、代わりに `skillshare collect --all` を実行し、[手動管理からの移行](#手動管理からの移行)の説明に従って重複を処理してください。
|
||||
|
||||
収集した Skill は単なるローカルコピーです。どのリポジトリから来たかを記録していないため、`skillshare update` では更新できません。
|
||||
|
||||
### ステップ 4: 更新を続けたい Skill を再インストールする(任意)
|
||||
|
||||
ロックファイルには各 Skill の取得元が記録されています。`source` はリポジトリ、`skillPath` はその中の場所です。
|
||||
|
||||
```bash
|
||||
cat ~/.agents/.skill-lock.json
|
||||
|
||||
# "source": "anthropics/skills", "skillPath": "skills/pdf/SKILL.md"
|
||||
skillshare install anthropics/skills/skills/pdf
|
||||
```
|
||||
|
||||
ステップ 3 で Skill がすでに Source に存在する場合は `--force` を使ってください。
|
||||
|
||||
### ステップ 5: Sync する
|
||||
|
||||
```bash
|
||||
skillshare sync
|
||||
```
|
||||
|
||||
merge mode では、Sync は Target(`~/.agents/skills`)内の同名の実ディレクトリを保持し、保持されたローカル Skill として報告します。`~/.claude/skills` など他の Agent ディレクトリにある `npx skills` のシンボリックリンクは、skillshare の Source を指すように張り替えられます。実ディレクトリもシンボリックリンクに置き換えるには、ステップ 3 で収集した後に次を実行します:
|
||||
|
||||
```bash
|
||||
skillshare sync --force
|
||||
```
|
||||
|
||||
`sync --force` は何かを置き換える前に Target をバックアップします。これ以降、それらの Skill は skillshare だけで管理してください。`npx skills` は独自のロックファイルでインストールを追跡しているため、それらの Skill に対して `npx skills update` や `npx skills remove` を実行しないでください。
|
||||
|
||||
`npx skills` を使っている Project では、移動するディレクトリを `.agents/skills/` として[コミット済みの Project Skill からの移行](#コミット済みの-project-skill-からの移行)に従ってください。
|
||||
|
||||
---
|
||||
|
||||
## Git サブモジュールからの移行
|
||||
|
||||
git サブモジュールを使っていた場合:
|
||||
|
||||
@@ -82,6 +82,76 @@ skillshare sync
|
||||
|
||||
---
|
||||
|
||||
## `npx skills`로부터
|
||||
|
||||
[npx skills CLI](https://github.com/vercel-labs/skills)(`npx skills add ...`)로 skill을 install했다면, skillshare가 같은 디렉터리를 이어받아 관리할 수 있습니다. [두 도구를 함께 사용](/docs/troubleshooting/faq#using-universal-alongside-npx-skills)하면서 skillshare로 관리하고 싶은 skill만 옮길 수도 있습니다.
|
||||
|
||||
`npx skills`가 파일을 보관하는 위치:
|
||||
|
||||
| 항목 | Global | Project |
|
||||
|------|--------|---------|
|
||||
| Skill 파일 | `~/.agents/skills/<name>/` (실제 디렉터리) | `.agents/skills/<name>/` |
|
||||
| Agent 디렉터리 | 위 파일을 가리키는 symlink (예: `~/.claude/skills/<name>`) | 동일 |
|
||||
| Lock file | `~/.agents/.skill-lock.json` (또는 `$XDG_STATE_HOME/skills/.skill-lock.json`) | `skills-lock.json` |
|
||||
|
||||
`--copy`로 install한 skill은 symlink 대신 각 agent 디렉터리에 실제 디렉터리로 존재합니다.
|
||||
|
||||
### 1단계: skillshare 초기화
|
||||
|
||||
```bash
|
||||
skillshare init
|
||||
```
|
||||
|
||||
### 2단계: 기존 skill 백업
|
||||
|
||||
```bash
|
||||
skillshare backup
|
||||
```
|
||||
|
||||
### 3단계: skill 수집
|
||||
|
||||
`collect`는 실제 디렉터리를 복사하고 symlink는 건너뛰므로, agent 디렉터리의 symlink가 중복으로 수집되지 않습니다.
|
||||
|
||||
```bash
|
||||
skillshare collect universal --dry-run # 미리보기
|
||||
skillshare collect universal # ~/.agents/skills
|
||||
```
|
||||
|
||||
`--copy`를 사용했거나 다른 agent 디렉터리에 skill이 있다면, 대신 `skillshare collect --all`을 실행하고 [수동 관리로부터](#수동-관리로부터)에 설명된 대로 중복을 처리하세요.
|
||||
|
||||
수집된 skill은 단순한 로컬 복사본입니다. 어느 repository에서 왔는지 기억하지 않으므로 `skillshare update`로 업데이트할 수 없습니다.
|
||||
|
||||
### 4단계: 계속 업데이트할 skill 재설치 (선택 사항)
|
||||
|
||||
Lock file에는 각 skill의 출처가 기록되어 있습니다. `source`는 repository이고 `skillPath`는 그 안의 위치입니다.
|
||||
|
||||
```bash
|
||||
cat ~/.agents/.skill-lock.json
|
||||
|
||||
# "source": "anthropics/skills", "skillPath": "skills/pdf/SKILL.md"
|
||||
skillshare install anthropics/skills/skills/pdf
|
||||
```
|
||||
|
||||
3단계에서 이미 source에 같은 skill이 있다면 `--force`를 사용하세요.
|
||||
|
||||
### 5단계: Sync
|
||||
|
||||
```bash
|
||||
skillshare sync
|
||||
```
|
||||
|
||||
Merge mode에서 sync는 target(`~/.agents/skills`)에 있는 같은 이름의 실제 디렉터리를 유지하고, 보존된 로컬 skill로 보고합니다. `~/.claude/skills` 같은 다른 agent 디렉터리의 `npx skills` symlink는 skillshare source를 가리키도록 다시 연결됩니다. 실제 디렉터리도 symlink로 교체하려면, 3단계에서 수집을 마친 뒤 다음을 실행하세요:
|
||||
|
||||
```bash
|
||||
skillshare sync --force
|
||||
```
|
||||
|
||||
`sync --force`는 교체하기 전에 target을 백업합니다. 이후에는 해당 skill을 skillshare로만 관리하세요. `npx skills`는 자체 lock file로 install을 추적하므로, 해당 skill에 `npx skills update`나 `npx skills remove`를 실행하지 마세요.
|
||||
|
||||
`npx skills`를 사용하는 프로젝트라면, 옮길 디렉터리를 `.agents/skills/`로 하여 [커밋된 Project Skill로부터](#커밋된-project-skill로부터)를 따르세요.
|
||||
|
||||
---
|
||||
|
||||
## Git Submodule로부터
|
||||
|
||||
git submodule을 사용해왔다면:
|
||||
|
||||
+70
@@ -82,6 +82,76 @@ skillshare sync
|
||||
|
||||
---
|
||||
|
||||
## 从 `npx skills` 迁移
|
||||
|
||||
如果你使用 [npx skills CLI](https://github.com/vercel-labs/skills)(`npx skills add ...`)安装过 Skill,skillshare 可以接管相同的目录。你也可以[让两个工具并存使用](/docs/troubleshooting/faq#using-universal-alongside-npx-skills),只迁移你希望由 skillshare 管理的 Skill。
|
||||
|
||||
`npx skills` 的存放位置:
|
||||
|
||||
| 项目 | Global | Project |
|
||||
|------|--------|---------|
|
||||
| Skill 文件 | `~/.agents/skills/<name>/`(真实目录) | `.agents/skills/<name>/` |
|
||||
| Agent 目录 | 指向上述文件的 symlink(例如 `~/.claude/skills/<name>`) | 同左 |
|
||||
| Lock file | `~/.agents/.skill-lock.json`(或 `$XDG_STATE_HOME/skills/.skill-lock.json`) | `skills-lock.json` |
|
||||
|
||||
使用 `--copy` 安装的 Skill 在每个 Agent 目录中都是真实目录,而不是 symlink。
|
||||
|
||||
### 第 1 步:初始化 skillshare
|
||||
|
||||
```bash
|
||||
skillshare init
|
||||
```
|
||||
|
||||
### 第 2 步:备份现有 Skill
|
||||
|
||||
```bash
|
||||
skillshare backup
|
||||
```
|
||||
|
||||
### 第 3 步:收集 Skill
|
||||
|
||||
`collect` 会复制真实目录并跳过 symlink,因此 Agent 目录中的 symlink 不会被重复收集。
|
||||
|
||||
```bash
|
||||
skillshare collect universal --dry-run # 预览
|
||||
skillshare collect universal # ~/.agents/skills
|
||||
```
|
||||
|
||||
如果你使用过 `--copy`,或在其他 Agent 目录中也有 Skill,请改为执行 `skillshare collect --all`,并按照[从手动管理迁移](#从手动管理迁移)中的说明处理重复项。
|
||||
|
||||
收集到的 Skill 是普通的本地副本。它们不会记录来自哪个仓库,因此 `skillshare update` 无法更新它们。
|
||||
|
||||
### 第 4 步:重新安装需要持续更新的 Skill(可选)
|
||||
|
||||
Lock file 记录了每个 Skill 的来源。`source` 是仓库,`skillPath` 是 Skill 在仓库中的位置。
|
||||
|
||||
```bash
|
||||
cat ~/.agents/.skill-lock.json
|
||||
|
||||
# "source": "anthropics/skills", "skillPath": "skills/pdf/SKILL.md"
|
||||
skillshare install anthropics/skills/skills/pdf
|
||||
```
|
||||
|
||||
如果该 Skill 已在第 3 步中进入你的 Source,请加上 `--force`。
|
||||
|
||||
### 第 5 步:Sync
|
||||
|
||||
```bash
|
||||
skillshare sync
|
||||
```
|
||||
|
||||
在 merge mode 下,Sync 会保留 Target(`~/.agents/skills`)中同名的真实目录,并将其报告为保留的本地 Skill。其他 Agent 目录(例如 `~/.claude/skills`)中由 `npx skills` 创建的 symlink 会被重新指向你的 skillshare Source。如果还想把这些真实目录也替换为 symlink,请在第 3 步收集完成后执行:
|
||||
|
||||
```bash
|
||||
skillshare sync --force
|
||||
```
|
||||
|
||||
`sync --force` 会在替换任何内容之前备份 Target。此后请只用 skillshare 管理这些 Skill。`npx skills` 在自己的 lock file 中记录安装信息,因此请避免对它们执行 `npx skills update` 或 `npx skills remove`。
|
||||
|
||||
对于使用 `npx skills` 的项目,请按照[从已提交的项目 Skill 迁移](#从已提交的项目-skill-迁移)操作,并将 `.agents/skills/` 作为要迁移的目录。
|
||||
|
||||
---
|
||||
|
||||
## 从 Git Submodule 迁移
|
||||
|
||||
如果你一直在使用 git submodule:
|
||||
|
||||
+70
@@ -82,6 +82,76 @@ skillshare sync
|
||||
|
||||
---
|
||||
|
||||
## 從 `npx skills` 遷移
|
||||
|
||||
如果你是用 [npx skills CLI](https://github.com/vercel-labs/skills)(`npx skills add ...`)安裝 Skills,skillshare 可以接管相同的目錄。你也可以[讓兩個工具並存](/docs/troubleshooting/faq#using-universal-alongside-npx-skills),只把想交給 skillshare 管理的 Skills 搬過來。
|
||||
|
||||
`npx skills` 存放各項內容的位置:
|
||||
|
||||
| 項目 | Global | Project |
|
||||
|------|--------|---------|
|
||||
| Skill 檔案 | `~/.agents/skills/<name>/`(實體目錄) | `.agents/skills/<name>/` |
|
||||
| Agent 目錄 | 指向上述檔案的 symlink(例如 `~/.claude/skills/<name>`) | 同左 |
|
||||
| Lock file | `~/.agents/.skill-lock.json`(或 `$XDG_STATE_HOME/skills/.skill-lock.json`) | `skills-lock.json` |
|
||||
|
||||
以 `--copy` 安裝的 Skills 在每個 Agent 目錄中都是實體目錄,而不是 symlink。
|
||||
|
||||
### 步驟 1:初始化 skillshare
|
||||
|
||||
```bash
|
||||
skillshare init
|
||||
```
|
||||
|
||||
### 步驟 2:備份既有的 Skills
|
||||
|
||||
```bash
|
||||
skillshare backup
|
||||
```
|
||||
|
||||
### 步驟 3:收集 Skills
|
||||
|
||||
`collect` 會複製實體目錄並略過 symlink,因此 Agent 目錄中的 symlink 不會被重複收集。
|
||||
|
||||
```bash
|
||||
skillshare collect universal --dry-run # 預覽
|
||||
skillshare collect universal # ~/.agents/skills
|
||||
```
|
||||
|
||||
如果你用過 `--copy`,或其他 Agent 目錄中也有 Skills,請改為執行 `skillshare collect --all`,並依照[從手動管理遷移](#從手動管理遷移)中的說明處理重複項目。
|
||||
|
||||
收集來的 Skills 是單純的本機副本。它們不會記得來自哪個 repository,因此 `skillshare update` 無法更新它們。
|
||||
|
||||
### 步驟 4:重新安裝想持續更新的 Skills(可選)
|
||||
|
||||
Lock file 記錄了每個 Skill 的來源。`source` 是 repository,`skillPath` 是它在 repository 中的位置。
|
||||
|
||||
```bash
|
||||
cat ~/.agents/.skill-lock.json
|
||||
|
||||
# "source": "anthropics/skills", "skillPath": "skills/pdf/SKILL.md"
|
||||
skillshare install anthropics/skills/skills/pdf
|
||||
```
|
||||
|
||||
如果該 Skill 已在步驟 3 中收集到你的 Source,請加上 `--force`。
|
||||
|
||||
### 步驟 5:Sync
|
||||
|
||||
```bash
|
||||
skillshare sync
|
||||
```
|
||||
|
||||
在 merge mode 下,sync 會保留 Target(`~/.agents/skills`)中同名的實體目錄,並將其回報為保留的本機 Skill。其他 Agent 目錄(例如 `~/.claude/skills`)中由 `npx skills` 建立的 symlink,會改為指向你的 skillshare Source。若也要把這些實體目錄換成 symlink,請在步驟 3 收集完成後執行:
|
||||
|
||||
```bash
|
||||
skillshare sync --force
|
||||
```
|
||||
|
||||
`sync --force` 會在取代任何內容之前先備份 Target。之後請只用 skillshare 管理這些 Skills。`npx skills` 會在自己的 lock file 中追蹤安裝紀錄,因此請避免對它們執行 `npx skills update` 或 `npx skills remove`。
|
||||
|
||||
若是使用 `npx skills` 的專案,請依照[從已 Commit 的 Project Skills 遷移](#從已-commit-的-project-skills-遷移)操作,並以 `.agents/skills/` 作為要搬移的目錄。
|
||||
|
||||
---
|
||||
|
||||
## 從 Git Submodules 遷移
|
||||
|
||||
如果你一直使用 git submodules:
|
||||
|
||||
Reference in New Issue
Block a user