mirror of
https://github.com/runkids/skillshare.git
synced 2026-11-18 18:04:17 +00:00
docs: update skills comparison and migration guidance
Compare npx skills v1.7.6 against verified capabilities instead of an install-only model. Position Skillshare around broader resource management and document experimental restore and npm sync limits. Clarify migration ownership, backups, source tracking, ref preservation, and initialization safety across English and four translations.
This commit is contained in:
@@ -82,73 +82,113 @@ skillshare sync
|
||||
|
||||
---
|
||||
|
||||
## From `npx skills`
|
||||
## From `npx skills` {#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.
|
||||
You can keep using `npx skills` for skills it already manages, or hand selected skills over to Skillshare. Both tools support multiple agents and global/project installs; migration is useful when you want Skillshare's broader resource management, not because the other tool can only install. See the [comparison](/docs/understand/philosophy/comparison).
|
||||
|
||||
Where `npx skills` keeps things:
|
||||
**There is no automatic npx lock import or ownership transfer.** Collecting preserves local skill files, not their upstream tracking. Reinstalling from a repository creates Skillshare tracking, but may fetch different content from your existing installation.
|
||||
|
||||
The paths and lock fields below refer to **skills v1.7.6**: [global lock source](https://github.com/vercel-labs/skills/blob/7a5e920bead4b1039a6d6df5d7e1163b7b09423a/src/skill-lock.ts), [project lock source](https://github.com/vercel-labs/skills/blob/7a5e920bead4b1039a6d6df5d7e1163b7b09423a/src/local-lock.ts), and [CLI reference](https://github.com/vercel-labs/skills/blob/7a5e920bead4b1039a6d6df5d7e1163b7b09423a/docs/commands.md).
|
||||
|
||||
| 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` |
|
||||
| Shared skill location | `~/.agents/skills/<name>/` | `.agents/skills/<name>/` |
|
||||
| Agent directories | Usually links to the shared skills; `--copy` creates independent copies | Same |
|
||||
| Lock file | `$XDG_STATE_HOME/skills/.skill-lock.json` when set; otherwise `~/.agents/.skill-lock.json` | `skills-lock.json` |
|
||||
|
||||
Skills installed with `--copy` are real directories in each agent directory instead of symlinks.
|
||||
Skills linked by `experimental_sync` can point into npm dependencies rather than being real directories. Inspect the actual paths before collecting.
|
||||
|
||||
### Step 1: Initialize skillshare
|
||||
### Step 1: Decide scope and preserve the original setup
|
||||
|
||||
The commands in Steps 2–5 explicitly use **global mode** (`-g`). For project installs, use the project notes below instead.
|
||||
|
||||
Before initialization or sync:
|
||||
|
||||
- Decide which skills each manager will own. Pause updates, removals, and automatic sync jobs while migrating.
|
||||
- Make a separate snapshot of the original skill directories, their real contents, and their symlink layout. Include any existing Skillshare source you might replace.
|
||||
- Save the applicable npx lock file separately. For npm projects, also preserve `package.json` and the package-manager lock file. These record sources and dependencies, not a backup of local edits.
|
||||
|
||||
Keep this snapshot until you have verified the handover. Do not delete the old lock or run `npx skills remove` as a cleanup shortcut.
|
||||
|
||||
### Step 2: Initialize without copying, then check backups
|
||||
|
||||
If Skillshare is not initialized, run the following in an **interactive terminal with both stdin and stdout attached**. Do not pipe or automate this command: these flags do not disable initial sync, and non-interactive initialization syncs automatically when targets are selected.
|
||||
|
||||
```bash
|
||||
skillshare init
|
||||
skillshare init -g --no-copy --no-skill --no-git
|
||||
```
|
||||
|
||||
### Step 2: Backup existing skills
|
||||
Select the targets you intend to manage, including `universal` for `~/.agents/skills`, and use merge mode for the workflow below. Decline an initial sync if prompted. For an existing configuration, inspect its source, [targets](/docs/reference/commands/target), and modes instead of resetting it.
|
||||
|
||||
```bash
|
||||
skillshare backup
|
||||
skillshare backup -g --dry-run
|
||||
skillshare backup -g
|
||||
skillshare backup -g --list
|
||||
```
|
||||
|
||||
### Step 3: Collect the skills
|
||||
Check the output for failures and confirm that the real skill files are covered. Target backups **skip symlinks**, do not back up their referents, and do not include the npx lock outside the target directory. They supplement, not replace, the snapshot from Step 1.
|
||||
|
||||
`collect` copies real directories and skips symlinks, so the symlinks in agent directories are not collected twice.
|
||||
### Step 3: Choose local copies or upstream tracking
|
||||
|
||||
**Keep the current files:** preview and collect from the target holding real directories:
|
||||
|
||||
```bash
|
||||
skillshare collect universal --dry-run # Preview
|
||||
skillshare collect universal # ~/.agents/skills
|
||||
skillshare collect universal -g --dry-run
|
||||
skillshare collect universal -g
|
||||
```
|
||||
|
||||
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).
|
||||
This collects all eligible skills in that target, not one selected skill. For copies in an individual agent directory, substitute that configured target name. Use `collect --all -g` only if you intend to collect from every configured target. For a partial handover, copy only the chosen real skill directories into Skillshare's source instead.
|
||||
|
||||
Collected skills are plain local copies. They do not remember which repository they came from, so `skillshare update` cannot update them.
|
||||
Collection skips skill symlinks, including links into `node_modules`. For those, keep npm management or deliberately copy the resolved skill directory as a local snapshot; that copy will no longer follow package updates. Collection also skips names already present in the source unless forced. Inspect skipped/failed results and compare duplicate contents yourself—the preview is not a lock-aware conflict report. Do not use `collect --force` to choose a winner blindly.
|
||||
|
||||
### Step 4: Reinstall skills you want to keep updating (optional)
|
||||
Collected skills have no imported repository tracking, so `skillshare update` cannot update them from their original sources.
|
||||
|
||||
The lock file records where each skill came from. `source` is the repository and `skillPath` is the location inside it.
|
||||
**Keep upstream updates:** inspect each saved lock entry before installing from its source. `sourceType` distinguishes Git, npm, local, and other sources; `sourceUrl`, `ref`, and `skillPath` may provide additional information. Not every entry has a repository or `skillPath`.
|
||||
|
||||
For example, a GitHub entry with `source: "anthropics/skills"` and `skillPath: "skills/pdf/SKILL.md"` maps to the containing skill directory:
|
||||
|
||||
```bash
|
||||
cat ~/.agents/.skill-lock.json
|
||||
|
||||
# "source": "anthropics/skills", "skillPath": "skills/pdf/SKILL.md"
|
||||
skillshare install anthropics/skills/skills/pdf
|
||||
skillshare install anthropics/skills/skills/pdf -g --dry-run
|
||||
skillshare install anthropics/skills/skills/pdf -g
|
||||
```
|
||||
|
||||
Use `--force` if the skill already exists in your source from Step 3.
|
||||
If the lock records a Git ref, add `--branch <recorded-ref>` to both commands above (see [install](/docs/reference/commands/install)). Without it, the example uses the remote default branch. This is a fresh installation, not a replay of the npx content hash. Compare it with your saved files and reconcile local edits. If a collected skill already occupies the destination, stop and resolve it first; do not blindly force an install, which can overwrite edits and override audit blocking. npm and local entries need their own source decision, not an `owner/repo` conversion.
|
||||
|
||||
### Step 5: Sync
|
||||
### Step 4: Preview and explicitly hand over ownership
|
||||
|
||||
```bash
|
||||
skillshare sync
|
||||
skillshare sync -g --dry-run
|
||||
```
|
||||
|
||||
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:
|
||||
Review **all configured targets**, not just `universal`. In merge mode, same-name local directories are preserved, while same-name agent symlinks can be repointed to Skillshare's source even without force. Confirm that this affects only skills you intend to hand over before applying:
|
||||
|
||||
```bash
|
||||
skillshare sync --force
|
||||
skillshare sync -g
|
||||
```
|
||||
|
||||
`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.
|
||||
If you also want the preserved real directories replaced by links, first verify the source contains the versions you want and the original snapshot is complete:
|
||||
|
||||
For a project that uses `npx skills`, follow [From Committed Project Skills](#from-committed-project-skills) with `.agents/skills/` as the directory to move.
|
||||
```bash
|
||||
skillshare sync -g --force --dry-run
|
||||
# Apply only after reviewing every replacement:
|
||||
skillshare sync -g --force
|
||||
```
|
||||
|
||||
Force applies across the configured targets; it is not a per-skill migration switch. Stop if the preview includes resources still owned by npx skills. Keep the tools' managed skill sets separate; see [coexistence](/docs/troubleshooting/faq#using-universal-alongside-npx-skills).
|
||||
|
||||
### Step 5: Verify and keep one owner
|
||||
|
||||
Check the resulting files/links and confirm the intended skills load in each AI tool. Run `skillshare status -g` and review preserved local skills or warnings; a successful sync alone does not prove every original skill was transferred.
|
||||
|
||||
Skillshare does not remove the old npx lock entries. After handover, do not use `npx skills update`, `remove`, `experimental_install`, or `experimental_sync` on the migrated skills. For partial migrations, avoid unqualified bulk commands that include them.
|
||||
|
||||
To roll back, pause both managers and restore the saved original files, link layout, and lock together. Skillshare target backups can help recover local files, but cannot recreate the original npx symlinks or lock by themselves.
|
||||
|
||||
### Project installs and npm synchronization
|
||||
|
||||
Preserve the project's files and lock before changes, including uncommitted or ignored local edits. Initialize with `skillshare init -p`, configure the project targets, then use `collect`, `install`, and `sync` with `-p` rather than the global commands above. The same source-tracking and symlink limitations apply. Skillshare does not create skill-target backups in project mode; use a verified project snapshot or version control that actually includes the files.
|
||||
|
||||
If `experimental_sync` is called from `package.json` scripts or CI, adjust those jobs and skill declarations before handing over overlapping skills. Otherwise a later dependency installation can relink them. Keeping npm-managed skills with npx skills is valid; do not copy links into `.skillshare/skills/` and assume they have become independently managed.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -4,188 +4,62 @@ sidebar_position: 9
|
||||
|
||||
# Comparing Skill Management Approaches
|
||||
|
||||
This page compares the two main architectural approaches to AI CLI skill management: **imperative** (install-per-command) and **declarative** (config + sync).
|
||||
Both **Vercel's `npx skills`** and **Skillshare** manage skills across multiple AI tools. The difference is not “one installs, the other syncs.” Choose by what you need to manage: skills, or a broader AI working environment.
|
||||
|
||||
If you're evaluating tools or considering a switch, this breakdown will help you understand the fundamental design differences.
|
||||
This comparison uses the published **skills v1.7.6** [package metadata](https://registry.npmjs.org/skills/1.7.6) and its [official CLI reference](https://github.com/vercel-labs/skills/blob/7a5e920bead4b1039a6d6df5d7e1163b7b09423a/docs/commands.md). Experimental commands may change or disappear; this is a versioned comparison, not a claim about every installer.
|
||||
|
||||
## Architecture at a Glance
|
||||
|
||||
### Imperative (Install-per-command)
|
||||
### npx skills: Skill discovery and management
|
||||
|
||||
Imperative tools use an install-per-command model — each install is a standalone operation:
|
||||
[skills.sh](https://skills.sh) provides a discovery entry point. The CLI supports multiple agents, project and global installation, symlinks to a canonical copy or independent copies, update checks, and updates. Agent selection and confirmation can be supplied through flags; interactive prompts are not mandatory.
|
||||
|
||||
```
|
||||
tool add owner/repo → select agents → choose method → done
|
||||
tool add owner/repo → select agents → choose method → done
|
||||
tool add owner/repo → select agents → choose method → done
|
||||
```
|
||||
It also records installed skills in lock files. Its experimental commands support project restoration and npm-based synchronization, so it is not accurate to describe it as stateless or install-only.
|
||||
|
||||
Every operation requires user input. There's no persistent state describing "what should be installed where."
|
||||
### Skillshare: A managed environment across tools
|
||||
|
||||
### Declarative (Config + Sync)
|
||||
Skillshare keeps source resources and target configuration separate, then synchronizes them to your tools. Beyond skills, it manages agent definitions, rules and other extras, MCP connection settings, and native hooks for supported clients. A local Web dashboard provides a visual management interface.
|
||||
|
||||
skillshare uses a declarative model — you define your desired state once, then sync:
|
||||
|
||||
```yaml
|
||||
# config.yaml — define once
|
||||
source: ~/.config/skillshare/skills
|
||||
targets:
|
||||
claude: ~/.claude
|
||||
cursor: ~/.cursor/skills
|
||||
codex: ~/.codex/skills
|
||||
```
|
||||
|
||||
```bash
|
||||
skillshare sync # reconcile actual state to desired state
|
||||
```
|
||||
|
||||
One command, no prompts, deterministic results every time.
|
||||
The useful distinction is managing these resources together across tools, machines, and team workflows—not exclusive ownership of symlinks or multi-agent installation. Resource formats and client capabilities still differ; not every resource works in every tool.
|
||||
|
||||
## Feature Comparison
|
||||
|
||||
| Capability | Imperative (install-per-command) | Declarative (skillshare) |
|
||||
|------------|------------------------|--------------------------|
|
||||
| **Configuration** | No config file; prompts on every run | `config.yaml` — set once, reuse forever |
|
||||
| **Agent selection** | Interactive prompt each time | Defined in config; `sync` handles all |
|
||||
| **Install method** | Choose copy/symlink per operation | `sync_mode` in config (merge, copy, or symlink) |
|
||||
| **Single source of truth** | Skills copied to each agent independently | Source directory → symlinks to all targets |
|
||||
| **Removing a skill from one agent** | May delete source files, breaking other agents | Only affects that target's symlink |
|
||||
| **Reproducible setup** | No built-in way to restore on new machine | `config.yaml` + source dir = full restore |
|
||||
| **Project-scoped skills** | Lock file tracks global only | `skillshare init -p` for per-repo skills |
|
||||
| **Cross-machine sync** | Manual (sync lock file via dotfiles) | Built-in `push` / `pull` with git |
|
||||
| **Bidirectional flow** | One-way (install only) | `collect` pulls improvements back from targets |
|
||||
| **Separating own vs installed skills** | Mixed in same directory | Tracked repos use `_` prefix |
|
||||
| **Offline operation** | Requires npx + network for CLI itself | Single binary, works offline after install |
|
||||
| **Web dashboard** | None | `skillshare ui` — visual management |
|
||||
| **Backup / restore** | None | `skillshare backup` / `skillshare restore` |
|
||||
| **Git platform support** | GitHub only for update/check (hardcoded to GitHub Trees API) | Any Git remote — GitHub, GitLab, Bitbucket, Azure DevOps, Gitea, AtomGit, Gitee, self-hosted |
|
||||
| **Runtime dependency** | Node.js + npm | None (single Go binary) |
|
||||
| Capability | npx skills v1.7.6 | Skillshare |
|
||||
|------------|------------------|------------|
|
||||
| **Discovery** | skills.sh and `skills find` | CLI search and local Web dashboard |
|
||||
| **Multiple agents and scopes** | Multiple agents; project and global installs | Configured targets; project and global modes |
|
||||
| **Shared skill files** | Symlinks to a canonical copy; copy option | Source directory with merge, copy, or directory-symlink modes |
|
||||
| **Updates** | `skills check` and `skills update` | `skillshare check` and `skillshare update` |
|
||||
| **Project restoration** | Experimental `skills experimental_install` restores supported sources from `skills-lock.json` | Declarative skill configuration and source resources; see [manifest](/docs/understand/declarative-manifest) |
|
||||
| **npm project sync** | Experimental `skills experimental_sync` reads installed dependencies and `package.json` skill declarations | Source-to-target synchronization; not the same npm dependency workflow |
|
||||
| **Cross-machine workflow** | Project lock restoration and npm sync can help rebuild project skills | Git-backed `push` / `pull`, scoped by `git_root` |
|
||||
| **Beyond skills** | The cited CLI reference focuses on skills | Agent definitions, extras such as rules, MCP settings, and hooks for supported clients |
|
||||
| **Local management and recovery** | The cited CLI reference does not document a local dashboard or target-backup commands | `skillshare ui`, target backups and restore, plus managed-file recovery |
|
||||
| **Runtime** | Node.js and npm/npx | Go binary; Git required for Git-backed operations |
|
||||
|
||||
## Common Pain Points Solved
|
||||
### What the experimental commands cover
|
||||
|
||||
### "I have to select agents every time I install"
|
||||
- **`experimental_install`** restores supported lock entries into `.agents/skills/`. It does not install npm dependencies or create agent-specific links for restored skills. Existing skills are left alone unless explicitly reinstalled. Frozen-lock mode checks content hashes and is the default in CI.
|
||||
- **`experimental_sync`** links skills shipped by installed npm dependencies and resolves skill declarations in `package.json`. It tracks these in `skills-lock.json`, removes skills no longer provided, and preserves separately added skills. Copies require another sync after dependency updates.
|
||||
|
||||
With skillshare, you configure targets once:
|
||||
|
||||
```yaml
|
||||
targets:
|
||||
claude: ~/.claude
|
||||
cursor: ~/.cursor/skills
|
||||
```
|
||||
|
||||
Then every `sync`, `install`, or `collect` knows where to go. No prompts.
|
||||
|
||||
### "Removing a skill from one agent breaks the others"
|
||||
|
||||
In imperative tools, removing a skill from one agent may delete the shared source files, leaving other agents with broken symlinks.
|
||||
|
||||
skillshare's architecture prevents this entirely — the source directory is the single truth. Target symlinks point **to** the source. Removing a target only removes that target's symlinks; source files are untouched.
|
||||
|
||||
```
|
||||
Source: ~/.config/skillshare/skills/my-skill/SKILL.md (always preserved)
|
||||
├── ~/.claude/skills/my-skill → symlink to source ✓
|
||||
├── ~/.cursor/skills/my-skill → symlink to source ✓ (unaffected)
|
||||
└── ~/.codex/skills/my-skill → symlink to source ✓ (unaffected)
|
||||
```
|
||||
|
||||
### "I can't restore my setup on a new machine"
|
||||
|
||||
With skillshare, your entire setup is portable:
|
||||
|
||||
1. Version-control `~/.config/skillshare/` (source + config)
|
||||
2. On a new machine: `git clone` your config repo
|
||||
3. Run `skillshare sync`
|
||||
|
||||
All targets are recreated instantly.
|
||||
|
||||
### "Update and check don't work with GitLab / Bitbucket / Azure DevOps"
|
||||
|
||||
Imperative tools often rely on the GitHub Trees API for update checks, which means `update` and `check` silently skip skills from non-GitHub sources.
|
||||
|
||||
skillshare uses **local git operations** (`git fetch` + tree hash comparison) — it works with any Git remote, including GitLab, Bitbucket, Azure DevOps, Gitea, AtomGit, Gitee, and any self-hosted instance. No platform-specific API is required.
|
||||
|
||||
```bash
|
||||
# All of these support install, update, and check:
|
||||
skillshare install https://gitlab.com/team/skills
|
||||
skillshare install git@bitbucket.org:company/private-skills.git
|
||||
skillshare install https://git.mycompany.com/org/repo
|
||||
skillshare update # checks all sources, regardless of host
|
||||
```
|
||||
|
||||
### "Clone takes forever on large repositories"
|
||||
|
||||
skillshare uses shallow clones (`--depth 1`) by default for non-tracked installs, reducing download time significantly. For tracked repos that need full history, use `--track`.
|
||||
|
||||
### "My skills are scattered across agent directories"
|
||||
|
||||
skillshare keeps everything in one place:
|
||||
|
||||
```
|
||||
~/.config/skillshare/skills/
|
||||
├── my-custom-skill/ # Your own skills
|
||||
├── react-best-practices/ # Installed skills
|
||||
├── _team-repo/ # Tracked repos (prefixed with _)
|
||||
│ ├── frontend-guidelines/
|
||||
│ └── code-review/
|
||||
└── _another-org-repo/
|
||||
```
|
||||
|
||||
The `_` prefix clearly separates tracked (team/org) repos from your personal skills.
|
||||
|
||||
## Migrating to skillshare
|
||||
|
||||
If you're already using another skill manager:
|
||||
|
||||
### Step 1: Install skillshare
|
||||
|
||||
```bash
|
||||
# macOS / Linux
|
||||
curl -fsSL https://raw.githubusercontent.com/runkids/skillshare/main/install.sh | sh
|
||||
```
|
||||
|
||||
If the installer prints PATH setup instructions, follow them before running the commands below. If it prints no PATH warning, no extra setup is needed.
|
||||
|
||||
```bash
|
||||
|
||||
# Homebrew
|
||||
brew install skillshare
|
||||
```
|
||||
|
||||
### Step 2: Initialize and collect existing skills
|
||||
|
||||
```bash
|
||||
skillshare init # Creates config and detects targets
|
||||
skillshare collect --all # Imports existing skills from all detected targets
|
||||
```
|
||||
|
||||
### Step 3: Sync
|
||||
|
||||
```bash
|
||||
skillshare sync # Symlinks source skills to all targets
|
||||
```
|
||||
|
||||
Your existing skills are now managed from one place. For a detailed walkthrough, see the [Migration Guide](/docs/how-to/advanced/migration).
|
||||
These are real synchronization and restoration capabilities, but they are not a backup of an entire AI tool configuration.
|
||||
|
||||
## Choosing the Right Tool
|
||||
|
||||
**Choose an imperative tool if:**
|
||||
- You install skills rarely and don't mind interactive prompts
|
||||
- You only use one AI CLI
|
||||
- You don't need cross-machine or team workflows
|
||||
**Stay with npx skills** if you mainly want to discover, install, and update public or private skills—even across several agents. It is also a reasonable fit when you want skills to follow npm project dependencies and accept the experimental status of that workflow.
|
||||
|
||||
**Choose skillshare if:**
|
||||
- You use multiple AI CLIs and want them in sync
|
||||
- You want a set-and-forget configuration
|
||||
- You work across multiple machines
|
||||
- You share skills with a team or organization
|
||||
- You want backup, restore, and version control for your skills
|
||||
- You host skills on GitLab, Bitbucket, Azure DevOps, or self-hosted Git
|
||||
- You prefer a single binary with no runtime dependencies
|
||||
- You don't want installation/download activity tracked outside your local workflow
|
||||
**Choose Skillshare** when the problem extends beyond installing skills: “I use Claude Code and Codex, and I want to carry my managed skills, rules, MCP settings, and supported hooks to another machine.” Its source/target configuration, Git workflows, local dashboard, and recovery tools address that broader management job.
|
||||
|
||||
---
|
||||
Portability still needs setup: choose the Git scope, configure targets on the destination, and provision credentials and external dependencies separately. `push` defaults to the skills source; it does not automatically publish all configuration or back up the whole machine. See [Git root scope](/docs/reference/commands/push#git-root-scope) and [sync](/docs/reference/commands/sync).
|
||||
|
||||
## Migrating to Skillshare
|
||||
|
||||
You do not need to replace a working installer immediately. Move only the resources you want Skillshare to own, and avoid having both tools update or remove the same managed skill.
|
||||
|
||||
Migration is not currently a lossless lock import: collected skills are local copies without the original repository tracking. Reinstall from the recorded source if you need subsequent Skillshare updates. Back up and preview before handing over ownership; follow the [npx skills migration guide](/docs/how-to/advanced/migration#from-npx-skills) rather than treating collection alone as a complete migration.
|
||||
|
||||
## See Also
|
||||
|
||||
- [Migration](/docs/how-to/advanced/migration) — Migration guide
|
||||
- [Core Concepts](/docs/understand) — How skillshare works
|
||||
- [Migration](/docs/how-to/advanced/migration)
|
||||
- [Core Concepts](/docs/understand)
|
||||
- [Backup](/docs/reference/commands/backup)
|
||||
|
||||
+70
-30
@@ -82,73 +82,113 @@ skillshare sync
|
||||
|
||||
---
|
||||
|
||||
## `npx skills` からの移行
|
||||
## `npx skills` からの移行 {#from-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 だけを移すこともできます。
|
||||
既存 skills は `npx skills` で管理し続けても、選んだ skills を Skillshare に引き継いでも構いません。両方とも複数 agent とグローバル/プロジェクトのインストールに対応しています。移行の理由は Skillshare の広いリソース管理が必要だからであり、もう一方がインストール専用だからではありません。[比較](/docs/understand/philosophy/comparison)を参照してください。
|
||||
|
||||
`npx skills` のファイルの保存場所:
|
||||
**npx lock の自動インポートや管理権の自動移行はありません。** Collect はローカルの skill ファイルを保存しますが、取得元の追跡情報は引き継ぎません。リポジトリから再インストールすると Skillshare の追跡情報が作られますが、既存インストールとは内容が異なる場合があります。
|
||||
|
||||
以下のパスと lock フィールドは **skills v1.7.6** に基づきます:[グローバル lock のソース](https://github.com/vercel-labs/skills/blob/7a5e920bead4b1039a6d6df5d7e1163b7b09423a/src/skill-lock.ts)、[プロジェクト lock のソース](https://github.com/vercel-labs/skills/blob/7a5e920bead4b1039a6d6df5d7e1163b7b09423a/src/local-lock.ts)、[CLI リファレンス](https://github.com/vercel-labs/skills/blob/7a5e920bead4b1039a6d6df5d7e1163b7b09423a/docs/commands.md)。
|
||||
|
||||
| 項目 | 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` |
|
||||
| 共通 skill の場所 | `~/.agents/skills/<name>/` | `.agents/skills/<name>/` |
|
||||
| Agent ディレクトリ | 通常は共通 skills へのリンク。`--copy` は独立したコピーを作成 | 同じ |
|
||||
| Lock ファイル | 設定されていれば `$XDG_STATE_HOME/skills/.skill-lock.json`、それ以外は `~/.agents/.skill-lock.json` | `skills-lock.json` |
|
||||
|
||||
`--copy` でインストールした Skill は、シンボリックリンクではなく各 Agent ディレクトリ内の実ディレクトリになります。
|
||||
`experimental_sync` が作る skills は、実ディレクトリではなく npm 依存関係へのリンクの場合があります。収集前に実際のパスを確認してください。
|
||||
|
||||
### ステップ 1: skillshare を初期化する
|
||||
### ステップ 1: 範囲を決め、元の構成を保存する
|
||||
|
||||
ステップ 2–5 は明示的に**グローバルモード**(`-g`)を使います。プロジェクトのインストールには下のプロジェクト向け説明を使ってください。
|
||||
|
||||
初期化や同期の前に:
|
||||
|
||||
- 各ツールが管理する skills を決め、移行中は更新・削除・自動同期ジョブを停止します。
|
||||
- 元の skill ディレクトリ、実際の内容、symlink 構成を別途スナップショットとして保存します。上書きする可能性がある既存の Skillshare source も含めてください。
|
||||
- 該当する npx lock を別途保存します。npm プロジェクトでは `package.json` とパッケージマネージャーの lock も保存します。これらは取得元と依存関係の記録であり、ローカル編集のバックアップではありません。
|
||||
|
||||
引き継ぎを検証するまでスナップショットを保持してください。古い lock を削除したり、後片付けとして `npx skills remove` を実行したりしないでください。
|
||||
|
||||
### ステップ 2: コピーせずに初期化し、バックアップを確認する
|
||||
|
||||
Skillshare が未初期化の場合、**stdin と stdout の両方が端末につながった対話環境**で以下を実行してください。パイプや自動化では実行しないでください。これらのフラグは初回同期を無効にせず、非対話の初期化では targets が選択されると自動同期します。
|
||||
|
||||
```bash
|
||||
skillshare init
|
||||
skillshare init -g --no-copy --no-skill --no-git
|
||||
```
|
||||
|
||||
### ステップ 2: 既存の Skill をバックアップする
|
||||
管理する targets を選び、`~/.agents/skills` に対応する `universal` を含めてください。この手順では merge mode を使用します。初回同期を尋ねられたら断ってください。設定済みの場合はリセットせず、source、[targets](/docs/reference/commands/target)、モードを確認します。
|
||||
|
||||
```bash
|
||||
skillshare backup
|
||||
skillshare backup -g --dry-run
|
||||
skillshare backup -g
|
||||
skillshare backup -g --list
|
||||
```
|
||||
|
||||
### ステップ 3: Skill を収集する
|
||||
出力の失敗を確認し、実際の skill ファイルが含まれていることを確かめます。Target バックアップは **symlink をスキップ**し、リンク先の内容や target ディレクトリ外の npx lock は保存しません。ステップ 1 のスナップショットを補うもので、代わりにはなりません。
|
||||
|
||||
`collect` は実ディレクトリをコピーし、シンボリックリンクはスキップします。そのため、Agent ディレクトリ内のシンボリックリンクが二重に収集されることはありません。
|
||||
### ステップ 3: ローカルコピーか取得元の追跡を選ぶ
|
||||
|
||||
**現在のファイルを保持する:**実ディレクトリを持つ target からプレビューして収集します。
|
||||
|
||||
```bash
|
||||
skillshare collect universal --dry-run # プレビュー
|
||||
skillshare collect universal # ~/.agents/skills
|
||||
skillshare collect universal -g --dry-run
|
||||
skillshare collect universal -g
|
||||
```
|
||||
|
||||
`--copy` を使っていた場合や、他の Agent ディレクトリにも Skill がある場合は、代わりに `skillshare collect --all` を実行し、[手動管理からの移行](#手動管理からの移行)の説明に従って重複を処理してください。
|
||||
これは target 内の対象となる skills すべてを収集し、選んだ 1 つだけを収集するものではありません。特定 agent のディレクトリにコピーがある場合は、その設定済み target 名に置き換えます。`collect --all -g` は全 targets から収集する場合だけ使ってください。一部だけ引き継ぐ場合は、選んだ実 skill ディレクトリだけを Skillshare source にコピーします。
|
||||
|
||||
収集した Skill は単なるローカルコピーです。どのリポジトリから来たかを記録していないため、`skillshare update` では更新できません。
|
||||
Collect は `node_modules` へのリンクを含む skill symlink をスキップします。npm 管理を続けるか、リンク先の実 skill ディレクトリを明示的にローカルスナップショットとしてコピーしてください。そのコピーはパッケージ更新に追従しなくなります。強制しない限り、source に既存の名前もスキップします。スキップ/失敗の結果を確認し、重複内容は自分で比較してください。プレビューは lock を解釈する競合レポートではありません。`collect --force` で無条件に勝者を決めないでください。
|
||||
|
||||
### ステップ 4: 更新を続けたい Skill を再インストールする(任意)
|
||||
収集した skills にはリポジトリの追跡情報が取り込まれないため、`skillshare update` で元の取得元から更新できません。
|
||||
|
||||
ロックファイルには各 Skill の取得元が記録されています。`source` はリポジトリ、`skillPath` はその中の場所です。
|
||||
**取得元からの更新を続ける:**インストール前に保存した lock の各項目を確認します。`sourceType` は Git、npm、ローカルなどを区別し、`sourceUrl`、`ref`、`skillPath` に追加情報がある場合があります。すべての項目にリポジトリや `skillPath` があるわけではありません。
|
||||
|
||||
たとえば GitHub の項目 `source: "anthropics/skills"`、`skillPath: "skills/pdf/SKILL.md"` は、そのファイルを含む skill ディレクトリに対応します。
|
||||
|
||||
```bash
|
||||
cat ~/.agents/.skill-lock.json
|
||||
|
||||
# "source": "anthropics/skills", "skillPath": "skills/pdf/SKILL.md"
|
||||
skillshare install anthropics/skills/skills/pdf
|
||||
skillshare install anthropics/skills/skills/pdf -g --dry-run
|
||||
skillshare install anthropics/skills/skills/pdf -g
|
||||
```
|
||||
|
||||
ステップ 3 で Skill がすでに Source に存在する場合は `--force` を使ってください。
|
||||
Lock に Git ref が記録されている場合は、上の両コマンドに `--branch <recorded-ref>` を追加してください([install](/docs/reference/commands/install) を参照)。指定しない場合、この例はリモートのデフォルトブランチを使います。これは新規インストールであり、npx の内容 hash を再現するものではありません。保存済みファイルと比較し、ローカル編集を統合してください。収集した skill がすでに宛先にある場合は、いったん止めて解決します。強制インストールは編集を上書きし audit のブロックも上書きする可能性があるため、安易に使わないでください。npm やローカルの項目は別途ソースを判断し、単純に `owner/repo` に変換しないでください。
|
||||
|
||||
### ステップ 5: Sync する
|
||||
### ステップ 4: プレビューし、明示的に管理を引き継ぐ
|
||||
|
||||
```bash
|
||||
skillshare sync
|
||||
skillshare sync -g --dry-run
|
||||
```
|
||||
|
||||
merge mode では、Sync は Target(`~/.agents/skills`)内の同名の実ディレクトリを保持し、保持されたローカル Skill として報告します。`~/.claude/skills` など他の Agent ディレクトリにある `npx skills` のシンボリックリンクは、skillshare の Source を指すように張り替えられます。実ディレクトリもシンボリックリンクに置き換えるには、ステップ 3 で収集した後に次を実行します:
|
||||
`universal` だけでなく、**設定済みの全 targets** を確認します。Merge mode は同名のローカルディレクトリを保持しますが、同名の agent symlink は force なしでも Skillshare source に張り替えられる場合があります。引き継ぐ予定の skills だけに影響することを確認してから適用します。
|
||||
|
||||
```bash
|
||||
skillshare sync --force
|
||||
skillshare sync -g
|
||||
```
|
||||
|
||||
`sync --force` は何かを置き換える前に Target をバックアップします。これ以降、それらの Skill は skillshare だけで管理してください。`npx skills` は独自のロックファイルでインストールを追跡しているため、それらの Skill に対して `npx skills update` や `npx skills remove` を実行しないでください。
|
||||
保持された実ディレクトリもリンクに置き換える場合は、source が希望のバージョンであり、元のスナップショットが完全であることを先に確認してください。
|
||||
|
||||
`npx skills` を使っている Project では、移動するディレクトリを `.agents/skills/` として[コミット済みの Project Skill からの移行](#コミット済みの-project-skill-からの移行)に従ってください。
|
||||
```bash
|
||||
skillshare sync -g --force --dry-run
|
||||
# Apply only after reviewing every replacement:
|
||||
skillshare sync -g --force
|
||||
```
|
||||
|
||||
Force は設定済み targets 全体に作用し、skill 単位の移行スイッチではありません。まだ npx skills が管理するリソースがプレビューに含まれていたら停止してください。管理対象を分離し、[併用の説明](/docs/troubleshooting/faq#using-universal-alongside-npx-skills)を参照してください。
|
||||
|
||||
### ステップ 5: 検証し、管理者を 1 つにする
|
||||
|
||||
結果のファイル/リンクを確認し、各 AI ツールで期待した skills が読み込まれることを確かめます。`skillshare status -g` を実行し、保持されたローカル skills や警告を確認してください。Sync の成功だけでは全 skills の移行を証明できません。
|
||||
|
||||
Skillshare は古い npx lock の項目を削除しません。引き継ぎ後は移行済み skills に `npx skills update`、`remove`、`experimental_install`、`experimental_sync` を使わないでください。一部移行の場合は、それらを含む無指定の一括コマンドを避けてください。
|
||||
|
||||
元に戻す場合は両ツールを停止し、保存した元ファイル、リンク構成、lock をまとめて復元します。Skillshare の target バックアップはローカルファイルの復旧に役立ちますが、元の npx symlink や lock を単独では再現できません。
|
||||
|
||||
### プロジェクトのインストールと npm 同期
|
||||
|
||||
変更前に、未コミット・無視対象のローカル編集も含めてプロジェクトファイルと lock を保存します。`skillshare init -p` で初期化し、プロジェクト targets を設定してから、上記のグローバルコマンドではなく `collect`、`install`、`sync` に `-p` を付けて使います。追跡情報と symlink の制約は同じです。プロジェクトモードでは skill-target のバックアップを作成しないため、検証済みスナップショットか、必要なファイルを実際に含むバージョン管理を使ってください。
|
||||
|
||||
`package.json` の scripts や CI が `experimental_sync` を呼び出す場合、重複する skills を引き継ぐ前にジョブと skill 宣言を調整します。そうしないと次の依存関係インストールで再リンクされる可能性があります。npm の skills を npx skills に任せ続けても構いません。リンクを `.skillshare/skills/` にコピーするだけで独立した管理になったと思わないでください。
|
||||
|
||||
---
|
||||
|
||||
|
||||
+38
-164
@@ -2,190 +2,64 @@
|
||||
sidebar_position: 9
|
||||
---
|
||||
|
||||
# Skill 管理アプローチの比較
|
||||
# Skill 管理方法の比較
|
||||
|
||||
このページでは、AI CLI の Skill 管理における 2 つの主要なアーキテクチャアプローチ、**命令型**(コマンドごとのインストール)と**宣言型**(config + sync)を比較します。
|
||||
**Vercel の `npx skills`** と **Skillshare** は、どちらも複数の AI ツールで skills を管理できます。違いは「一方はインストールだけ、もう一方は同期できる」ではありません。skills を管理したいのか、より広い AI 作業環境を管理したいのかで選びましょう。
|
||||
|
||||
ツールを評価中の方や乗り換えを検討している方は、この比較で根本的な設計の違いを理解できます。
|
||||
本ページは、公開済みの **skills v1.7.6** の[パッケージ情報](https://registry.npmjs.org/skills/1.7.6)と[公式 CLI リファレンス](https://github.com/vercel-labs/skills/blob/7a5e920bead4b1039a6d6df5d7e1163b7b09423a/docs/commands.md)に基づきます。実験的なコマンドは変更・削除される可能性があります。すべてのインストーラーについての一般論ではなく、特定バージョンの比較です。
|
||||
|
||||
## アーキテクチャの概観
|
||||
## アーキテクチャの概要
|
||||
|
||||
### 命令型(コマンドごとのインストール)
|
||||
### npx skills:skills の発見と管理
|
||||
|
||||
命令型ツールはコマンドごとのインストールモデルを採用しており、各インストールは独立した操作です。
|
||||
[skills.sh](https://skills.sh) は skills を見つける入口です。CLI は複数 agent、プロジェクト/グローバルのインストール、共通コピーへの symlink または独立したコピー、更新確認と更新に対応します。Agent の選択と確認はフラグでも指定でき、対話操作は必須ではありません。
|
||||
|
||||
```
|
||||
tool add owner/repo → select agents → choose method → done
|
||||
tool add owner/repo → select agents → choose method → done
|
||||
tool add owner/repo → select agents → choose method → done
|
||||
```
|
||||
インストール済み skills は lock ファイルにも記録されます。実験的なコマンドはプロジェクトの復元と npm ベースの同期に対応するため、状態を持たない、またはインストール専用という説明は正確ではありません。
|
||||
|
||||
すべての操作でユーザー入力が必要です。「どこに何をインストールすべきか」を記述する永続的な状態は存在しません。
|
||||
### Skillshare:ツールをまたぐ作業環境の管理
|
||||
|
||||
### 宣言型(Config + Sync)
|
||||
Skillshare は source リソースと target 設定を分け、各ツールへ同期します。Skills に加え、agent 定義、rules などの extras、MCP 接続設定、対応クライアントのネイティブ hooks を管理します。ローカル Web dashboard から視覚的に管理できます。
|
||||
|
||||
skillshare は宣言型モデルを採用しています。望ましい状態を一度定義すれば、あとは sync するだけです。
|
||||
|
||||
```yaml
|
||||
# config.yaml — define once
|
||||
source: ~/.config/skillshare/skills
|
||||
targets:
|
||||
claude: ~/.claude
|
||||
cursor: ~/.cursor/skills
|
||||
codex: ~/.codex/skills
|
||||
```
|
||||
|
||||
```bash
|
||||
skillshare sync # reconcile actual state to desired state
|
||||
```
|
||||
|
||||
コマンド 1 つ、プロンプトなし、常に決定的な結果が得られます。
|
||||
違いは、これらをツール・マシン・チーム間のワークフローでまとめて管理することです。Symlink や複数 agent へのインストールは独自機能ではありません。リソース形式とクライアントの機能には違いがあり、すべてのリソースがすべてのツールで動くわけではありません。
|
||||
|
||||
## 機能比較
|
||||
|
||||
| 機能 | 命令型(コマンドごとのインストール) | 宣言型(skillshare) |
|
||||
|------------|------------------------|--------------------------|
|
||||
| **設定** | 設定ファイルなし。実行のたびにプロンプトが表示される | `config.yaml` — 一度設定すれば以後も再利用可能 |
|
||||
| **Agent 選択** | 毎回インタラクティブなプロンプト | config 内で定義済み。`sync` がすべて処理 |
|
||||
| **インストール方法** | 操作ごとに copy/symlink を選択 | config 内の `sync_mode`(merge、copy、symlink) |
|
||||
| **単一の信頼できる情報源** | Skill が各 agent に個別にコピーされる | Source ディレクトリ → 全 Target へのシンボリックリンク |
|
||||
| **1 つの agent から Skill を削除する場合** | Source ファイルが削除され、他の agent が壊れることがある | その Target のシンボリックリンクにのみ影響 |
|
||||
| **再現可能なセットアップ** | 新しいマシンで復元する組み込みの方法がない | `config.yaml` + Source ディレクトリで完全復元 |
|
||||
| **プロジェクトスコープの Skill** | ロックファイルはグローバルのみ追跡 | `skillshare init -p` でリポジトリごとの Skill |
|
||||
| **クロスマシン同期** | 手動(dotfiles 経由でロックファイルを同期) | git を使った組み込みの `push` / `pull` |
|
||||
| **双方向のフロー** | 一方向(インストールのみ) | `collect` が Target 側の改善を取り込む |
|
||||
| **自作 Skill とインストール済み Skill の分離** | 同じディレクトリに混在 | Tracked repo は `_` 接頭辞を使用 |
|
||||
| **オフライン動作** | CLI 自体に npx とネットワークが必要 | 単一バイナリで、インストール後はオフラインで動作 |
|
||||
| **Web ダッシュボード** | なし | `skillshare ui` — ビジュアル管理 |
|
||||
| **バックアップ / 復元** | なし | `skillshare backup` / `skillshare restore` |
|
||||
| **Git プラットフォーム対応** | update/check は GitHub のみ(GitHub Trees API にハードコード) | GitHub、GitLab、Bitbucket、Azure DevOps、Gitea、AtomGit、Gitee、セルフホストなど任意の Git remote |
|
||||
| **ランタイム依存** | Node.js + npm | なし(単一の Go バイナリ) |
|
||||
| 機能 | npx skills v1.7.6 | Skillshare |
|
||||
|------|------------------|------------|
|
||||
| **発見** | skills.sh と `skills find` | CLI 検索とローカル Web dashboard |
|
||||
| **複数 agent とスコープ** | 複数 agent、プロジェクト/グローバルのインストール | 設定済み targets、プロジェクト/グローバルモード |
|
||||
| **Skill ファイルの共有** | 共通コピーへの symlink、copy オプション | Source ディレクトリと merge、copy、ディレクトリ全体の symlink モード |
|
||||
| **更新** | `skills check` と `skills update` | `skillshare check` と `skillshare update` |
|
||||
| **プロジェクト復元** | 実験的な `skills experimental_install` が `skills-lock.json` の対応ソースを復元 | 宣言的な skill 設定と source リソース。[manifest](/docs/understand/declarative-manifest) を参照 |
|
||||
| **npm プロジェクト同期** | 実験的な `skills experimental_sync` がインストール済み依存関係と `package.json` の skill 宣言を読む | Source から target への同期。同じ npm 依存関係ワークフローではない |
|
||||
| **マシン間のワークフロー** | プロジェクト lock の復元と npm 同期でプロジェクト skills の再構築を支援 | Git の `push` / `pull`。範囲は `git_root` で決定 |
|
||||
| **Skills 以外** | 引用した CLI 文書は skills が中心 | Agent 定義、rules などの extras、MCP 設定、対応クライアントの hooks |
|
||||
| **ローカル管理と復旧** | 引用した CLI 文書にローカル dashboard や target バックアップのコマンドは記載されていない | `skillshare ui`、target のバックアップ/復元、管理対象ファイルの復旧 |
|
||||
| **実行環境** | Node.js と npm/npx | Go バイナリ。Git 操作には Git が必要 |
|
||||
|
||||
## よくある課題の解決
|
||||
### 実験的なコマンドの範囲
|
||||
|
||||
### 「インストールのたびに agent を選び直さないといけない」
|
||||
- **`experimental_install`** は対応する lock エントリーを `.agents/skills/` に復元します。npm 依存関係のインストールや、復元した skills の agent 専用リンクの作成は行いません。明示的に再インストールしない限り既存 skills は保持されます。Frozen-lock モードでは内容の hash を検証し、CI ではこれがデフォルトです。
|
||||
- **`experimental_sync`** はインストール済み npm 依存関係に含まれる skills をリンクし、`package.json` の skill 宣言を解決します。`skills-lock.json` で追跡し、提供されなくなった skills を削除し、別途追加した skills は保持します。Copy の場合、依存関係の更新後に再同期が必要です。
|
||||
|
||||
skillshare では、Target を一度だけ設定します。
|
||||
|
||||
```yaml
|
||||
targets:
|
||||
claude: ~/.claude
|
||||
cursor: ~/.cursor/skills
|
||||
```
|
||||
|
||||
以降、`sync`、`install`、`collect` はどこに反映すべきか把握しています。プロンプトは不要です。
|
||||
|
||||
### 「1 つの agent から Skill を削除すると他が壊れる」
|
||||
|
||||
命令型ツールでは、1 つの agent から Skill を削除すると共有の Source ファイルが削除され、他の agent のシンボリックリンクが壊れることがあります。
|
||||
|
||||
skillshare のアーキテクチャはこれを完全に防ぎます。Source ディレクトリが唯一の真実であり、Target のシンボリックリンクは Source を**指す**だけです。Target を削除してもそのシンボリックリンクが消えるだけで、Source ファイルは無傷です。
|
||||
|
||||
```
|
||||
Source: ~/.config/skillshare/skills/my-skill/SKILL.md (always preserved)
|
||||
├── ~/.claude/skills/my-skill → symlink to source ✓
|
||||
├── ~/.cursor/skills/my-skill → symlink to source ✓ (unaffected)
|
||||
└── ~/.codex/skills/my-skill → symlink to source ✓ (unaffected)
|
||||
```
|
||||
|
||||
### 「新しいマシンでセットアップを復元できない」
|
||||
|
||||
skillshare なら、セットアップ全体を持ち運べます。
|
||||
|
||||
1. `~/.config/skillshare/`(Source + config)をバージョン管理する
|
||||
2. 新しいマシンで、config リポジトリを `git clone` する
|
||||
3. `skillshare sync` を実行する
|
||||
|
||||
すべての Target が即座に再現されます。
|
||||
|
||||
### 「update と check が GitLab / Bitbucket / Azure DevOps で動かない」
|
||||
|
||||
命令型ツールは更新チェックを GitHub Trees API に依存していることが多く、`update` と `check` が GitHub 以外のソースの Skill を黙ってスキップしてしまいます。
|
||||
|
||||
skillshare は**ローカルの git 操作**(`git fetch` + ツリーハッシュ比較)を使用するため、GitLab、Bitbucket、Azure DevOps、Gitea、AtomGit、Gitee、任意のセルフホストインスタンスを含む、あらゆる Git remote で動作します。プラットフォーム固有の API は不要です。
|
||||
|
||||
```bash
|
||||
# All of these support install, update, and check:
|
||||
skillshare install https://gitlab.com/team/skills
|
||||
skillshare install git@bitbucket.org:company/private-skills.git
|
||||
skillshare install https://git.mycompany.com/org/repo
|
||||
skillshare update # checks all sources, regardless of host
|
||||
```
|
||||
|
||||
### 「大きなリポジトリの clone に時間がかかりすぎる」
|
||||
|
||||
skillshare は、tracked でないインストールに対してデフォルトで shallow clone(`--depth 1`)を使用し、ダウンロード時間を大幅に短縮します。完全な履歴が必要な tracked repo には `--track` を使用してください。
|
||||
|
||||
### 「Skill が各 agent のディレクトリに散らばっている」
|
||||
|
||||
skillshare はすべてを 1 か所にまとめます。
|
||||
|
||||
```
|
||||
~/.config/skillshare/skills/
|
||||
├── my-custom-skill/ # Your own skills
|
||||
├── react-best-practices/ # Installed skills
|
||||
├── _team-repo/ # Tracked repos (prefixed with _)
|
||||
│ ├── frontend-guidelines/
|
||||
│ └── code-review/
|
||||
└── _another-org-repo/
|
||||
```
|
||||
|
||||
`_` 接頭辞により、tracked(チーム/組織)の repo と個人の Skill が明確に区別されます。
|
||||
|
||||
## skillshare への移行
|
||||
|
||||
すでに別の Skill マネージャーを使用している場合は、以下の手順に従ってください。
|
||||
|
||||
### ステップ 1: skillshare をインストールする
|
||||
|
||||
```bash
|
||||
# macOS / Linux
|
||||
curl -fsSL https://raw.githubusercontent.com/runkids/skillshare/main/install.sh | sh
|
||||
```
|
||||
|
||||
インストーラーが PATH 設定の案内を表示した場合のみ、その案内に従ってから以下のコマンドを実行してください。PATH の警告がなければ追加の設定は不要です。
|
||||
|
||||
```bash
|
||||
|
||||
# Homebrew
|
||||
brew install skillshare
|
||||
```
|
||||
|
||||
### ステップ 2: 初期化して既存の Skill を取り込む
|
||||
|
||||
```bash
|
||||
skillshare init # Creates config and detects targets
|
||||
skillshare collect --all # Imports existing skills from all detected targets
|
||||
```
|
||||
|
||||
### ステップ 3: Sync する
|
||||
|
||||
```bash
|
||||
skillshare sync # Symlinks source skills to all targets
|
||||
```
|
||||
|
||||
これで既存の Skill が 1 か所から管理できるようになりました。詳しい手順は[移行ガイド](/docs/how-to/advanced/migration)を参照してください。
|
||||
これらは実際の同期・復元機能ですが、AI ツール設定全体のバックアップではありません。
|
||||
|
||||
## 適切なツールの選び方
|
||||
|
||||
**次の場合は命令型ツールを選びましょう。**
|
||||
- Skill をたまにしかインストールせず、インタラクティブなプロンプトが気にならない
|
||||
- 使用している AI CLI が 1 つだけである
|
||||
- クロスマシンやチームでのワークフローが不要である
|
||||
**npx skills を使い続ける**:主な目的が公開・非公開 skills の発見、インストール、更新なら、複数 agent を使う場合も合理的です。Skills を npm プロジェクトの依存関係に追従させたく、実験的なワークフローを受け入れられる場合にも適しています。
|
||||
|
||||
**次の場合は skillshare を選びましょう。**
|
||||
- 複数の AI CLI を使用しており、それらを同期させたい
|
||||
- 一度設定したら放置できる構成を望んでいる
|
||||
- 複数のマシンで作業している
|
||||
- チームや組織で Skill を共有している
|
||||
- Skill のバックアップ、復元、バージョン管理をしたい
|
||||
- GitLab、Bitbucket、Azure DevOps、またはセルフホストの Git で Skill をホストしている
|
||||
- ランタイム依存のない単一バイナリを好む
|
||||
- ローカルワークフローの外でインストール/ダウンロードの活動が追跡されるのを望まない
|
||||
**Skillshare を選ぶ**:たとえば「Claude Code と Codex を使っていて、管理対象の skills、rules、MCP 設定、対応する hooks を別のマシンに持っていきたい」場合です。Source/target 設定、Git ワークフロー、ローカル dashboard、復旧ツールが、この広い管理ニーズに対応します。
|
||||
|
||||
---
|
||||
移行先でも準備は必要です。Git の範囲を選び、targets を設定し、認証情報と外部依存関係を別途用意してください。`push` のデフォルトは skills の source であり、全設定の公開やマシン全体のバックアップは行いません。[Git root の範囲](/docs/reference/commands/push)と [sync](/docs/reference/commands/sync) を参照してください。
|
||||
|
||||
## Skillshare への移行
|
||||
|
||||
正常に動いているインストーラーをすぐに置き換える必要はありません。Skillshare に管理させたいリソースだけを移し、同じ管理対象 skill を両ツールで更新・削除しないでください。
|
||||
|
||||
現在の移行は、情報をすべて保持する lock インポートではありません。収集した skills はローカルコピーであり、元リポジトリの追跡情報を保持しません。Skillshare で更新を続けたい場合は、記録されたソースから再インストールしてください。管理を移す前にバックアップとプレビューを行い、収集だけで完了とせず [npx skills 移行ガイド](/docs/how-to/advanced/migration)に従ってください。
|
||||
|
||||
## 関連項目
|
||||
|
||||
- [移行](/docs/how-to/advanced/migration) — 移行ガイド
|
||||
- [コアコンセプト](/docs/understand) — skillshare の仕組み
|
||||
- [移行](/docs/how-to/advanced/migration)
|
||||
- [コアコンセプト](/docs/understand)
|
||||
- [バックアップ](/docs/reference/commands/backup)
|
||||
|
||||
+70
-30
@@ -82,73 +82,113 @@ skillshare sync
|
||||
|
||||
---
|
||||
|
||||
## `npx skills`로부터
|
||||
## `npx skills`로부터 {#from-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만 옮길 수도 있습니다.
|
||||
기존 skills를 `npx skills`로 계속 관리하거나, 선택한 skills를 Skillshare에 넘길 수 있습니다. 두 도구 모두 여러 agent와 전역/프로젝트 설치를 지원합니다. 이전 이유는 Skillshare의 더 넓은 리소스 관리가 필요해서이지, 다른 도구가 설치만 할 수 있어서가 아닙니다. [비교](/docs/understand/philosophy/comparison)를 참고하세요.
|
||||
|
||||
`npx skills`가 파일을 보관하는 위치:
|
||||
**npx lock 자동 가져오기나 자동 관리권 이전 기능은 없습니다.** Collect는 로컬 skill 파일을 보존하지만 원본 추적 정보는 가져오지 않습니다. 저장소에서 다시 설치하면 Skillshare 추적 정보가 생기지만 기존 설치와 다른 콘텐츠를 받을 수 있습니다.
|
||||
|
||||
아래 경로와 lock 필드는 **skills v1.7.6** 기준입니다: [전역 lock 소스](https://github.com/vercel-labs/skills/blob/7a5e920bead4b1039a6d6df5d7e1163b7b09423a/src/skill-lock.ts), [프로젝트 lock 소스](https://github.com/vercel-labs/skills/blob/7a5e920bead4b1039a6d6df5d7e1163b7b09423a/src/local-lock.ts), [CLI 문서](https://github.com/vercel-labs/skills/blob/7a5e920bead4b1039a6d6df5d7e1163b7b09423a/docs/commands.md).
|
||||
|
||||
| 항목 | 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` |
|
||||
| 공유 skill 위치 | `~/.agents/skills/<name>/` | `.agents/skills/<name>/` |
|
||||
| Agent 디렉터리 | 보통 공유 skills를 가리키는 링크. `--copy`는 독립 복사본 생성 | 동일 |
|
||||
| Lock 파일 | 설정되어 있으면 `$XDG_STATE_HOME/skills/.skill-lock.json`, 아니면 `~/.agents/.skill-lock.json` | `skills-lock.json` |
|
||||
|
||||
`--copy`로 install한 skill은 symlink 대신 각 agent 디렉터리에 실제 디렉터리로 존재합니다.
|
||||
`experimental_sync`가 만든 skills는 실제 디렉터리가 아니라 npm 의존성을 가리키는 링크일 수 있습니다. 수집 전에 실제 경로를 확인하세요.
|
||||
|
||||
### 1단계: skillshare 초기화
|
||||
### 1단계: 범위를 정하고 원래 구성을 보존하기
|
||||
|
||||
2–5단계 명령은 명시적으로 **전역 모드**(`-g`)를 사용합니다. 프로젝트 설치에는 아래 프로젝트 설명을 사용하세요.
|
||||
|
||||
초기화 또는 동기화 전:
|
||||
|
||||
- 각 도구가 관리할 skills를 정하세요. 이전 중에는 업데이트, 제거, 자동 동기화 작업을 중지하세요.
|
||||
- 원래 skill 디렉터리, 실제 콘텐츠, symlink 구성을 별도 스냅샷으로 저장하세요. 교체될 수 있는 기존 Skillshare source도 포함하세요.
|
||||
- 해당 npx lock 파일을 별도로 보존하세요. npm 프로젝트에서는 `package.json`과 패키지 관리자의 lock도 저장하세요. 이 파일들은 소스와 의존성 기록이지 로컬 수정의 백업이 아닙니다.
|
||||
|
||||
인계를 검증할 때까지 스냅샷을 유지하세요. 이전 lock을 삭제하거나 정리 목적으로 `npx skills remove`를 실행하지 마세요.
|
||||
|
||||
### 2단계: 복사 없이 초기화하고 백업 확인하기
|
||||
|
||||
Skillshare가 아직 초기화되지 않았다면 **stdin과 stdout 모두 터미널에 연결된 대화형 환경**에서 다음 명령을 실행하세요. 파이프나 자동화로 실행하지 마세요. 이 플래그들은 초기 동기화를 비활성화하지 않으며 비대화형 초기화에서는 targets가 선택되면 자동으로 동기화됩니다.
|
||||
|
||||
```bash
|
||||
skillshare init
|
||||
skillshare init -g --no-copy --no-skill --no-git
|
||||
```
|
||||
|
||||
### 2단계: 기존 skill 백업
|
||||
관리할 targets를 선택하고 `~/.agents/skills`에 해당하는 `universal`을 포함하세요. 이 절차에서는 merge mode를 사용합니다. 초기 동기화를 묻는다면 거절하세요. 이미 설정했다면 초기화하지 말고 source, [targets](/docs/reference/commands/target), 모드를 확인하세요.
|
||||
|
||||
```bash
|
||||
skillshare backup
|
||||
skillshare backup -g --dry-run
|
||||
skillshare backup -g
|
||||
skillshare backup -g --list
|
||||
```
|
||||
|
||||
### 3단계: skill 수집
|
||||
출력의 실패 여부와 실제 skill 파일 포함 여부를 확인하세요. Target 백업은 **symlink를 건너뛰며**, 링크 대상의 콘텐츠나 target 디렉터리 밖의 npx lock을 저장하지 않습니다. 1단계 스냅샷을 보완하는 것이지 대체하지 않습니다.
|
||||
|
||||
`collect`는 실제 디렉터리를 복사하고 symlink는 건너뛰므로, agent 디렉터리의 symlink가 중복으로 수집되지 않습니다.
|
||||
### 3단계: 로컬 복사본 또는 원본 추적 선택하기
|
||||
|
||||
**현재 파일 유지:** 실제 디렉터리를 가진 target에서 미리 보고 수집하세요.
|
||||
|
||||
```bash
|
||||
skillshare collect universal --dry-run # 미리보기
|
||||
skillshare collect universal # ~/.agents/skills
|
||||
skillshare collect universal -g --dry-run
|
||||
skillshare collect universal -g
|
||||
```
|
||||
|
||||
`--copy`를 사용했거나 다른 agent 디렉터리에 skill이 있다면, 대신 `skillshare collect --all`을 실행하고 [수동 관리로부터](#수동-관리로부터)에 설명된 대로 중복을 처리하세요.
|
||||
이는 해당 target의 수집 가능한 모든 skills를 수집하며 선택한 하나만 수집하는 명령이 아닙니다. 특정 agent 디렉터리에 복사본이 있다면 해당 설정된 target 이름으로 바꾸세요. 모든 설정된 targets에서 수집하려는 경우에만 `collect --all -g`를 사용하세요. 일부만 넘길 때는 선택한 실제 skill 디렉터리만 Skillshare source에 복사하세요.
|
||||
|
||||
수집된 skill은 단순한 로컬 복사본입니다. 어느 repository에서 왔는지 기억하지 않으므로 `skillshare update`로 업데이트할 수 없습니다.
|
||||
Collect는 `node_modules` 링크를 포함한 skill symlink를 건너뜁니다. npm 관리를 유지하거나, 링크가 가리키는 실제 skill 디렉터리를 의도적으로 로컬 스냅샷으로 복사하세요. 이 복사본은 패키지 업데이트를 따라가지 않습니다. 강제하지 않으면 source에 이미 있는 이름도 건너뜁니다. 건너뜀/실패 결과를 살피고 중복 콘텐츠를 직접 비교하세요. 미리보기는 lock을 이해하는 충돌 보고서가 아닙니다. `collect --force`로 무조건 한쪽을 선택하지 마세요.
|
||||
|
||||
### 4단계: 계속 업데이트할 skill 재설치 (선택 사항)
|
||||
수집된 skills에는 저장소 추적 정보가 없으므로 `skillshare update`로 원래 소스에서 업데이트할 수 없습니다.
|
||||
|
||||
Lock file에는 각 skill의 출처가 기록되어 있습니다. `source`는 repository이고 `skillPath`는 그 안의 위치입니다.
|
||||
**원본 업데이트 유지:** 소스에서 설치하기 전에 저장한 lock 항목을 각각 확인하세요. `sourceType`은 Git, npm, 로컬 등의 소스를 구분하며 `sourceUrl`, `ref`, `skillPath`에 추가 정보가 있을 수 있습니다. 모든 항목에 저장소나 `skillPath`가 있는 것은 아닙니다.
|
||||
|
||||
예를 들어 GitHub 항목 `source: "anthropics/skills"`, `skillPath: "skills/pdf/SKILL.md"`는 해당 파일이 들어 있는 skill 디렉터리에 대응합니다.
|
||||
|
||||
```bash
|
||||
cat ~/.agents/.skill-lock.json
|
||||
|
||||
# "source": "anthropics/skills", "skillPath": "skills/pdf/SKILL.md"
|
||||
skillshare install anthropics/skills/skills/pdf
|
||||
skillshare install anthropics/skills/skills/pdf -g --dry-run
|
||||
skillshare install anthropics/skills/skills/pdf -g
|
||||
```
|
||||
|
||||
3단계에서 이미 source에 같은 skill이 있다면 `--force`를 사용하세요.
|
||||
Lock에 Git ref가 기록되어 있다면 위 두 명령 모두에 `--branch <recorded-ref>`를 추가하세요([install](/docs/reference/commands/install) 참고). 지정하지 않으면 이 예시는 원격 기본 브랜치를 사용합니다. 이는 새 설치이며 npx 콘텐츠 hash를 재현하는 작업이 아닙니다. 저장한 파일과 비교하고 로컬 수정을 통합하세요. 수집한 skill이 이미 목적지를 차지한다면 먼저 멈추고 해결하세요. 강제 설치는 수정 내용을 덮어쓰고 audit 차단을 무시할 수도 있으므로 무작정 사용하지 마세요. npm과 로컬 항목은 별도로 소스를 판단해야 하며 단순히 `owner/repo`로 변환할 수 없습니다.
|
||||
|
||||
### 5단계: Sync
|
||||
### 4단계: 미리 보고 명시적으로 관리권 넘기기
|
||||
|
||||
```bash
|
||||
skillshare sync
|
||||
skillshare sync -g --dry-run
|
||||
```
|
||||
|
||||
Merge mode에서 sync는 target(`~/.agents/skills`)에 있는 같은 이름의 실제 디렉터리를 유지하고, 보존된 로컬 skill로 보고합니다. `~/.claude/skills` 같은 다른 agent 디렉터리의 `npx skills` symlink는 skillshare source를 가리키도록 다시 연결됩니다. 실제 디렉터리도 symlink로 교체하려면, 3단계에서 수집을 마친 뒤 다음을 실행하세요:
|
||||
`universal`뿐 아니라 **설정된 모든 targets**를 검토하세요. Merge mode는 같은 이름의 로컬 디렉터리를 보존하지만 같은 이름의 agent symlink는 force 없이도 Skillshare source로 다시 연결될 수 있습니다. 넘기려는 skills에만 영향을 주는지 확인한 후 적용하세요.
|
||||
|
||||
```bash
|
||||
skillshare sync --force
|
||||
skillshare sync -g
|
||||
```
|
||||
|
||||
`sync --force`는 교체하기 전에 target을 백업합니다. 이후에는 해당 skill을 skillshare로만 관리하세요. `npx skills`는 자체 lock file로 install을 추적하므로, 해당 skill에 `npx skills update`나 `npx skills remove`를 실행하지 마세요.
|
||||
보존된 실제 디렉터리도 링크로 바꾸려면, source에 원하는 버전이 있고 원래 스냅샷이 완전한지 먼저 확인하세요.
|
||||
|
||||
`npx skills`를 사용하는 프로젝트라면, 옮길 디렉터리를 `.agents/skills/`로 하여 [커밋된 Project Skill로부터](#커밋된-project-skill로부터)를 따르세요.
|
||||
```bash
|
||||
skillshare sync -g --force --dry-run
|
||||
# Apply only after reviewing every replacement:
|
||||
skillshare sync -g --force
|
||||
```
|
||||
|
||||
Force는 설정된 targets 전체에 적용되며 skill별 이전 스위치가 아닙니다. 아직 npx skills가 관리하는 리소스가 미리보기에 포함되면 중지하세요. 관리 대상을 분리하세요. [함께 사용하기](/docs/troubleshooting/faq#using-universal-alongside-npx-skills)를 참고하세요.
|
||||
|
||||
### 5단계: 검증하고 관리자를 하나로 유지하기
|
||||
|
||||
결과 파일/링크를 확인하고 각 AI 도구가 의도한 skills를 불러오는지 확인하세요. `skillshare status -g`를 실행해 보존된 로컬 skills나 경고를 살피세요. Sync 성공만으로 모든 원래 skill이 이전되었다고 볼 수는 없습니다.
|
||||
|
||||
Skillshare는 이전 npx lock 항목을 제거하지 않습니다. 인계 후 이전한 skills에 `npx skills update`, `remove`, `experimental_install`, `experimental_sync`를 사용하지 마세요. 일부만 이전했다면 해당 skills까지 포함하는 범위 미지정 일괄 명령을 피하세요.
|
||||
|
||||
되돌리려면 두 관리 도구를 중지하고 저장한 원래 파일, 링크 구성, lock을 함께 복원하세요. Skillshare target 백업은 로컬 파일 복구에 도움이 되지만 원래 npx symlink나 lock을 단독으로 재구성하지 못합니다.
|
||||
|
||||
### 프로젝트 설치와 npm 동기화
|
||||
|
||||
변경 전에 커밋하지 않았거나 무시된 로컬 수정까지 포함해 프로젝트 파일과 lock을 보존하세요. `skillshare init -p`로 초기화하고 프로젝트 targets를 설정한 뒤, 위 전역 명령 대신 `collect`, `install`, `sync`에 `-p`를 사용하세요. 원본 추적과 symlink 제한은 동일합니다. 프로젝트 모드에서는 skill-target 백업을 만들지 않으므로 검증된 프로젝트 스냅샷이나 해당 파일을 실제로 포함하는 버전 관리를 사용하세요.
|
||||
|
||||
`package.json` scripts 또는 CI에서 `experimental_sync`를 호출한다면, 겹치는 skills를 넘기기 전에 작업과 skill 선언을 조정하세요. 그렇지 않으면 다음 의존성 설치 때 다시 연결될 수 있습니다. npm skills를 npx skills에 계속 맡겨도 됩니다. 링크를 `.skillshare/skills/`에 복사했다고 독립적으로 관리되는 것은 아닙니다.
|
||||
|
||||
---
|
||||
|
||||
|
||||
+35
-161
@@ -4,188 +4,62 @@ sidebar_position: 9
|
||||
|
||||
# Skill 관리 방식 비교
|
||||
|
||||
이 페이지는 AI CLI skill 관리에 대한 두 가지 주요 아키텍처 접근 방식을 비교합니다: **imperative**(명령별 install)와 **declarative**(config + sync).
|
||||
**Vercel의 `npx skills`**와 **Skillshare**는 모두 여러 AI 도구에서 skills를 관리합니다. 차이는 “하나는 설치만, 다른 하나는 동기화”가 아닙니다. Skills를 관리할지, 더 넓은 AI 작업 환경을 관리할지에 따라 선택하세요.
|
||||
|
||||
도구를 평가 중이거나 전환을 고려 중이라면, 이 분석이 근본적인 설계 차이를 이해하는 데 도움이 될 것입니다.
|
||||
이 비교는 배포된 **skills v1.7.6**의 [패키지 정보](https://registry.npmjs.org/skills/1.7.6)와 [공식 CLI 문서](https://github.com/vercel-labs/skills/blob/7a5e920bead4b1039a6d6df5d7e1163b7b09423a/docs/commands.md)를 기준으로 합니다. 실험적 명령은 변경되거나 사라질 수 있습니다. 모든 설치 도구에 대한 일반화가 아니라 특정 버전의 비교입니다.
|
||||
|
||||
## 아키텍처 한눈에 보기
|
||||
## 아키텍처 개요
|
||||
|
||||
### Imperative (명령별 Install)
|
||||
### npx skills: Skills 발견과 관리
|
||||
|
||||
Imperative 도구는 명령별 install 모델을 사용합니다 — 각 install이 독립적인 작업입니다:
|
||||
[skills.sh](https://skills.sh)는 skills를 찾는 출발점입니다. CLI는 여러 agent, 프로젝트 및 전역 설치, 공통 복사본을 가리키는 symlink 또는 독립 복사본, 업데이트 확인과 업데이트를 지원합니다. Agent 선택과 확인은 플래그로 지정할 수 있으므로 대화형 입력은 필수가 아닙니다.
|
||||
|
||||
```
|
||||
tool add owner/repo → select agents → choose method → done
|
||||
tool add owner/repo → select agents → choose method → done
|
||||
tool add owner/repo → select agents → choose method → done
|
||||
```
|
||||
설치된 skills는 lock 파일에도 기록됩니다. 실험적 명령은 프로젝트 복원과 npm 기반 동기화를 지원하므로 상태가 없거나 설치 전용이라고 설명하면 정확하지 않습니다.
|
||||
|
||||
모든 작업에 사용자 입력이 필요합니다. "무엇이 어디에 설치되어야 하는가"를 설명하는 영구적인 상태가 없습니다.
|
||||
### Skillshare: 도구 간 작업 환경 관리
|
||||
|
||||
### Declarative (Config + Sync)
|
||||
Skillshare는 source 리소스와 target 설정을 분리한 뒤 각 도구에 동기화합니다. Skills 외에도 agent 정의, rules 같은 extras, MCP 연결 설정, 지원 클라이언트의 네이티브 hooks를 관리합니다. 로컬 Web dashboard에서 시각적으로 관리할 수 있습니다.
|
||||
|
||||
skillshare는 declarative 모델을 사용합니다 — 원하는 상태를 한 번 정의한 다음 sync합니다:
|
||||
|
||||
```yaml
|
||||
# config.yaml — define once
|
||||
source: ~/.config/skillshare/skills
|
||||
targets:
|
||||
claude: ~/.claude
|
||||
cursor: ~/.cursor/skills
|
||||
codex: ~/.codex/skills
|
||||
```
|
||||
|
||||
```bash
|
||||
skillshare sync # reconcile actual state to desired state
|
||||
```
|
||||
|
||||
하나의 명령, 프롬프트 없음, 매번 결정론적인 결과.
|
||||
차이는 이러한 리소스를 도구, 머신, 팀 워크플로우 전반에서 함께 관리하는 데 있습니다. Symlink나 여러 agent 설치가 독점 기능이라는 뜻은 아닙니다. 리소스 형식과 클라이언트 기능이 다르므로 모든 리소스가 모든 도구에서 작동하지는 않습니다.
|
||||
|
||||
## 기능 비교
|
||||
|
||||
| 기능 | Imperative (명령별 install) | Declarative (skillshare) |
|
||||
|------------|------------------------|--------------------------|
|
||||
| **설정** | Config 파일 없음. 실행마다 프롬프트 | `config.yaml` — 한 번 설정하고 계속 재사용 |
|
||||
| **Agent 선택** | 매번 대화형 프롬프트 | config에 정의됨. `sync`가 모두 처리 |
|
||||
| **설치 방식** | 작업마다 copy/symlink 선택 | config의 `sync_mode` (merge, copy, symlink) |
|
||||
| **단일 source of truth** | 각 agent에 독립적으로 skill 복사 | source 디렉터리 → 모든 target에 symlink |
|
||||
| **하나의 agent에서 skill 제거** | source 파일을 삭제해 다른 agent에 영향을 줄 수 있음 | 해당 target의 symlink에만 영향 |
|
||||
| **재현 가능한 설정** | 새 머신에서 복원할 내장 방법 없음 | `config.yaml` + source dir = 전체 복원 |
|
||||
| **프로젝트 범위 skill** | Lock 파일이 global만 추적 | 저장소별 skill을 위한 `skillshare init -p` |
|
||||
| **여러 머신 간 sync** | 수동 (dotfiles를 통한 lock 파일 sync) | git을 사용한 내장 `push` / `pull` |
|
||||
| **양방향 흐름** | 단방향 (install만) | `collect`가 target에서 개선 사항을 다시 가져옴 |
|
||||
| **자신의 skill과 설치한 skill 구분** | 같은 디렉터리에 혼재 | Tracked repo는 `_` 접두사 사용 |
|
||||
| **오프라인 작동** | CLI 자체에 npx와 네트워크 필요 | 단일 바이너리, 설치 후 오프라인 작동 |
|
||||
| **웹 대시보드** | 없음 | `skillshare ui` — 시각적 관리 |
|
||||
| **백업 / 복원** | 없음 | `skillshare backup` / `skillshare restore` |
|
||||
| **Git 플랫폼 지원** | update/check는 GitHub 전용 (GitHub Trees API에 하드코딩) | 모든 Git remote — GitHub, GitLab, Bitbucket, Azure DevOps, Gitea, AtomGit, Gitee, self-hosted |
|
||||
| **런타임 의존성** | Node.js + npm | 없음 (단일 Go 바이너리) |
|
||||
| 기능 | npx skills v1.7.6 | Skillshare |
|
||||
|------|------------------|------------|
|
||||
| **발견** | skills.sh 및 `skills find` | CLI 검색 및 로컬 Web dashboard |
|
||||
| **여러 agent와 범위** | 여러 agent, 프로젝트 및 전역 설치 | 설정된 targets, 프로젝트 및 전역 모드 |
|
||||
| **Skill 파일 공유** | 공통 복사본을 가리키는 symlink, copy 옵션 | Source 디렉터리와 merge, copy, 전체 디렉터리 symlink 모드 |
|
||||
| **업데이트** | `skills check` 및 `skills update` | `skillshare check` 및 `skillshare update` |
|
||||
| **프로젝트 복원** | 실험적 `skills experimental_install`이 `skills-lock.json`의 지원 소스를 복원 | 선언적 skill 설정과 source 리소스. [manifest](/docs/understand/declarative-manifest) 참고 |
|
||||
| **npm 프로젝트 동기화** | 실험적 `skills experimental_sync`가 설치된 의존성과 `package.json`의 skill 선언을 읽음 | Source에서 target으로 동기화. 동일한 npm 의존성 워크플로우는 아님 |
|
||||
| **머신 간 워크플로우** | 프로젝트 lock 복원과 npm 동기화로 프로젝트 skills 재구성 지원 | Git `push` / `pull`, 범위는 `git_root`로 결정 |
|
||||
| **Skills 외 리소스** | 인용한 CLI 문서는 skills 중심 | Agent 정의, rules 같은 extras, MCP 설정, 지원 클라이언트의 hooks |
|
||||
| **로컬 관리와 복구** | 인용한 CLI 문서에는 로컬 dashboard나 target 백업 명령이 명시되어 있지 않음 | `skillshare ui`, target 백업과 복원, 관리 파일 복구 |
|
||||
| **실행 환경** | Node.js 및 npm/npx | Go 바이너리. Git 작업에는 Git 필요 |
|
||||
|
||||
## 자주 겪는 문제 해결
|
||||
### 실험적 명령의 범위
|
||||
|
||||
### "설치할 때마다 agent를 매번 선택해야 함"
|
||||
- **`experimental_install`**은 지원하는 lock 항목을 `.agents/skills/`에 복원합니다. npm 의존성을 설치하거나 복원한 skills에 agent 전용 링크를 만들지는 않습니다. 명시적으로 재설치하지 않으면 기존 skills는 유지됩니다. Frozen-lock 모드는 콘텐츠 hash를 검사하며 CI에서 기본값입니다.
|
||||
- **`experimental_sync`**는 설치된 npm 의존성에 포함된 skills를 연결하고 `package.json`의 skill 선언을 처리합니다. `skills-lock.json`으로 추적하고 더 이상 제공되지 않는 skills를 제거하며 별도로 추가한 skills는 보존합니다. Copy를 사용하면 의존성 업데이트 후 다시 동기화해야 합니다.
|
||||
|
||||
skillshare에서는 target을 한 번만 설정하면 됩니다:
|
||||
이는 실제 동기화 및 복원 기능이지만 AI 도구 설정 전체의 백업은 아닙니다.
|
||||
|
||||
```yaml
|
||||
targets:
|
||||
claude: ~/.claude
|
||||
cursor: ~/.cursor/skills
|
||||
```
|
||||
## 적절한 도구 선택
|
||||
|
||||
그러면 모든 `sync`, `install`, `collect`가 어디로 가야 할지 알고 있습니다. 프롬프트 없음.
|
||||
**npx skills 유지**: 주된 목적이 공개 또는 비공개 skills를 찾고 설치하고 업데이트하는 것이라면 여러 agent를 사용하더라도 합리적입니다. Skills가 npm 프로젝트 의존성을 따르기를 원하고 실험적 워크플로우를 수용할 수 있는 경우에도 적합합니다.
|
||||
|
||||
### "하나의 agent에서 skill을 제거하면 다른 agent가 깨짐"
|
||||
**Skillshare 선택**: 예를 들어 “Claude Code와 Codex를 쓰는데, 관리 중인 skills, rules, MCP 설정, 지원되는 hooks를 다른 컴퓨터로 가져가고 싶다”는 경우입니다. Source/target 설정, Git 워크플로우, 로컬 dashboard와 복구 도구는 이러한 더 넓은 관리 요구를 위한 것입니다.
|
||||
|
||||
Imperative 도구에서는 하나의 agent에서 skill을 제거하면 공유된 source 파일이 삭제되어 다른 agent에 깨진 symlink가 남을 수 있습니다.
|
||||
이식성에도 준비가 필요합니다. Git 범위를 선택하고 새 머신의 targets를 설정하며 자격 증명과 외부 의존성을 별도로 준비해야 합니다. `push`는 기본적으로 skills source만 처리하며 모든 설정을 자동 게시하거나 머신 전체를 백업하지 않습니다. [Git root 범위](/docs/reference/commands/push)와 [sync](/docs/reference/commands/sync)를 참고하세요.
|
||||
|
||||
skillshare의 아키텍처는 이를 완전히 방지합니다 — source 디렉터리가 유일한 진실입니다. Target symlink는 source를 **가리킵니다**. Target을 제거해도 그 target의 symlink만 제거되며, source 파일은 그대로입니다.
|
||||
## Skillshare로 마이그레이션
|
||||
|
||||
```
|
||||
Source: ~/.config/skillshare/skills/my-skill/SKILL.md (always preserved)
|
||||
├── ~/.claude/skills/my-skill → symlink to source ✓
|
||||
├── ~/.cursor/skills/my-skill → symlink to source ✓ (unaffected)
|
||||
└── ~/.codex/skills/my-skill → symlink to source ✓ (unaffected)
|
||||
```
|
||||
잘 작동하는 설치 도구를 바로 대체할 필요는 없습니다. Skillshare가 관리할 리소스만 이전하고, 같은 관리 대상 skill을 두 도구에서 동시에 업데이트하거나 제거하지 마세요.
|
||||
|
||||
### "새 머신에서 내 설정을 복원할 수 없음"
|
||||
|
||||
skillshare를 사용하면 전체 설정이 이식 가능합니다:
|
||||
|
||||
1. `~/.config/skillshare/`(source + config)를 버전 관리에 등록
|
||||
2. 새 머신에서: 설정 repo를 `git clone`
|
||||
3. `skillshare sync` 실행
|
||||
|
||||
모든 target이 즉시 재생성됩니다.
|
||||
|
||||
### "Update와 check가 GitLab / Bitbucket / Azure DevOps에서 작동하지 않음"
|
||||
|
||||
Imperative 도구는 종종 update 확인을 위해 GitHub Trees API에 의존하는데, 이는 `update`와 `check`가 GitHub가 아닌 소스의 skill을 조용히 건너뛴다는 뜻입니다.
|
||||
|
||||
skillshare는 **로컬 git 작업**(`git fetch` + tree hash 비교)을 사용합니다 — GitLab, Bitbucket, Azure DevOps, Gitea, AtomGit, Gitee, 그리고 모든 self-hosted 인스턴스를 포함한 모든 Git remote와 함께 작동합니다. 플랫폼 특화 API가 필요하지 않습니다.
|
||||
|
||||
```bash
|
||||
# All of these support install, update, and check:
|
||||
skillshare install https://gitlab.com/team/skills
|
||||
skillshare install git@bitbucket.org:company/private-skills.git
|
||||
skillshare install https://git.mycompany.com/org/repo
|
||||
skillshare update # checks all sources, regardless of host
|
||||
```
|
||||
|
||||
### "큰 저장소에서 clone이 너무 오래 걸림"
|
||||
|
||||
skillshare는 tracked가 아닌 install에 기본적으로 shallow clone(`--depth 1`)을 사용해 다운로드 시간을 크게 줄입니다. 전체 히스토리가 필요한 tracked repo는 `--track`을 사용하세요.
|
||||
|
||||
### "내 skill들이 여러 agent 디렉터리에 흩어져 있음"
|
||||
|
||||
skillshare는 모든 것을 한곳에 유지합니다:
|
||||
|
||||
```
|
||||
~/.config/skillshare/skills/
|
||||
├── my-custom-skill/ # Your own skills
|
||||
├── react-best-practices/ # Installed skills
|
||||
├── _team-repo/ # Tracked repos (prefixed with _)
|
||||
│ ├── frontend-guidelines/
|
||||
│ └── code-review/
|
||||
└── _another-org-repo/
|
||||
```
|
||||
|
||||
`_` 접두사는 tracked(팀/조직) repo를 개인 skill과 명확하게 구분합니다.
|
||||
|
||||
## skillshare로 마이그레이션하기
|
||||
|
||||
이미 다른 skill 관리자를 사용 중이라면:
|
||||
|
||||
### 1단계: skillshare 설치
|
||||
|
||||
```bash
|
||||
# macOS / Linux
|
||||
curl -fsSL https://raw.githubusercontent.com/runkids/skillshare/main/install.sh | sh
|
||||
```
|
||||
|
||||
설치 프로그램이 PATH 설정 안내를 표시할 때만 안내에 따라 설정한 후 아래 명령을 실행하세요. PATH 경고가 없으면 추가 설정은 필요하지 않습니다.
|
||||
|
||||
```bash
|
||||
|
||||
# Homebrew
|
||||
brew install skillshare
|
||||
```
|
||||
|
||||
### 2단계: 초기화 및 기존 skill 수집
|
||||
|
||||
```bash
|
||||
skillshare init # Creates config and detects targets
|
||||
skillshare collect --all # Imports existing skills from all detected targets
|
||||
```
|
||||
|
||||
### 3단계: Sync
|
||||
|
||||
```bash
|
||||
skillshare sync # Symlinks source skills to all targets
|
||||
```
|
||||
|
||||
이제 기존 skill들이 한곳에서 관리됩니다. 자세한 안내는 [Migration Guide](/docs/how-to/advanced/migration)를 참고하세요.
|
||||
|
||||
## 올바른 도구 선택하기
|
||||
|
||||
**다음의 경우 imperative 도구를 선택하세요:**
|
||||
- skill을 드물게 설치하고 대화형 프롬프트에 개의치 않는 경우
|
||||
- AI CLI를 하나만 사용하는 경우
|
||||
- 여러 머신이나 팀 워크플로우가 필요 없는 경우
|
||||
|
||||
**다음의 경우 skillshare를 선택하세요:**
|
||||
- 여러 AI CLI를 사용하며 서로 동기화되기를 원하는 경우
|
||||
- 설정하고 잊어버릴 수 있는(set-and-forget) 구성을 원하는 경우
|
||||
- 여러 머신에서 작업하는 경우
|
||||
- 팀이나 조직과 skill을 공유하는 경우
|
||||
- skill에 대한 백업, 복원, 버전 관리를 원하는 경우
|
||||
- GitLab, Bitbucket, Azure DevOps, 또는 self-hosted Git에 skill을 호스팅하는 경우
|
||||
- 런타임 의존성이 없는 단일 바이너리를 선호하는 경우
|
||||
- 로컬 워크플로우 밖에서 설치/다운로드 활동이 추적되는 것을 원하지 않는 경우
|
||||
|
||||
---
|
||||
현재 마이그레이션은 정보를 모두 보존하는 lock 가져오기가 아닙니다. 수집한 skills는 원래 저장소의 추적 정보가 없는 로컬 복사본입니다. 이후 Skillshare로 업데이트하려면 기록된 소스에서 다시 설치하세요. 관리권을 넘기기 전에 백업과 미리보기를 하고, 수집만으로 완료했다고 생각하지 말고 [npx skills 마이그레이션 가이드](/docs/how-to/advanced/migration)를 따르세요.
|
||||
|
||||
## 참고
|
||||
|
||||
- [Migration](/docs/how-to/advanced/migration) — 마이그레이션 가이드
|
||||
- [Core Concepts](/docs/understand) — skillshare 동작 방식
|
||||
- [마이그레이션](/docs/how-to/advanced/migration)
|
||||
- [핵심 개념](/docs/understand)
|
||||
- [백업](/docs/reference/commands/backup)
|
||||
|
||||
+70
-30
@@ -82,73 +82,113 @@ skillshare sync
|
||||
|
||||
---
|
||||
|
||||
## 从 `npx skills` 迁移
|
||||
## 从 `npx skills` 迁移 {#from-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` 管理原有 skills,也可以将选定的 skills 交给 Skillshare。两者都支持多 agent 与全局/项目安装;迁移的理由是需要 Skillshare 更广的资源管理能力,而不是另一个工具只能安装。见[比较页](/docs/understand/philosophy/comparison)。
|
||||
|
||||
`npx skills` 的存放位置:
|
||||
**目前没有自动导入 npx lock 或移交管理权的功能。** Collect 保留本地 skill 文件,不会导入上游跟踪信息。从仓库重新安装会建立 Skillshare 的跟踪信息,但获取的内容可能与现有安装不同。
|
||||
|
||||
以下路径与 lock 字段依据 **skills v1.7.6**:[全局 lock 源码](https://github.com/vercel-labs/skills/blob/7a5e920bead4b1039a6d6df5d7e1163b7b09423a/src/skill-lock.ts)、[项目 lock 源码](https://github.com/vercel-labs/skills/blob/7a5e920bead4b1039a6d6df5d7e1163b7b09423a/src/local-lock.ts)及 [CLI 文档](https://github.com/vercel-labs/skills/blob/7a5e920bead4b1039a6d6df5d7e1163b7b09423a/docs/commands.md)。
|
||||
|
||||
| 项目 | 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` |
|
||||
| 共享 skill 位置 | `~/.agents/skills/<name>/` | `.agents/skills/<name>/` |
|
||||
| Agent 目录 | 通常是指向共享 skills 的链接;`--copy` 会创建独立副本 | 同左 |
|
||||
| Lock 文件 | 已设置时使用 `$XDG_STATE_HOME/skills/.skill-lock.json`,否则为 `~/.agents/.skill-lock.json` | `skills-lock.json` |
|
||||
|
||||
使用 `--copy` 安装的 Skill 在每个 Agent 目录中都是真实目录,而不是 symlink。
|
||||
`experimental_sync` 创建的 skills 可能是指向 npm 依赖的链接,而非真实目录。收集前先检查实际路径。
|
||||
|
||||
### 第 1 步:初始化 skillshare
|
||||
### 第 1 步:决定范围并保存原始配置
|
||||
|
||||
第 2–5 步的命令明确使用**全局模式**(`-g`)。项目安装请改看下方的项目说明。
|
||||
|
||||
初始化或同步前:
|
||||
|
||||
- 决定每个管理工具负责哪些 skills。迁移期间暂停更新、移除与自动同步任务。
|
||||
- 另外创建原始 skill 目录、实际内容与 symlink 布局的快照。也要包含可能被替换的现有 Skillshare source。
|
||||
- 单独保存适用的 npx lock。npm 项目也要保存 `package.json` 与包管理器的 lock;这些只记录来源与依赖,不是本地修改的备份。
|
||||
|
||||
验证交接完成前保留这份快照。不要删除旧 lock,也不要把 `npx skills remove` 当作清理捷径。
|
||||
|
||||
### 第 2 步:初始化但不复制,然后检查备份
|
||||
|
||||
若尚未初始化 Skillshare,请在 **stdin 与 stdout 都连接到终端的交互式环境**执行下列命令。不要通过管道或自动化执行:这些参数不会禁用首次同步,非交互初始化在选定 targets 后会自动同步。
|
||||
|
||||
```bash
|
||||
skillshare init
|
||||
skillshare init -g --no-copy --no-skill --no-git
|
||||
```
|
||||
|
||||
### 第 2 步:备份现有 Skill
|
||||
选择要管理的 targets,包含对应 `~/.agents/skills` 的 `universal`,并使用本流程采用的 merge mode。若提示是否立即同步,请拒绝。已有配置时,先检查 source、[targets](/docs/reference/commands/target) 与模式,不要重置。
|
||||
|
||||
```bash
|
||||
skillshare backup
|
||||
skillshare backup -g --dry-run
|
||||
skillshare backup -g
|
||||
skillshare backup -g --list
|
||||
```
|
||||
|
||||
### 第 3 步:收集 Skill
|
||||
检查输出中的失败,确认实际 skill 文件已覆盖。Target 备份会**跳过 symlink**,不会备份链接指向的内容,也不包含 target 目录外的 npx lock。它只是第 1 步快照的补充,不能取代快照。
|
||||
|
||||
`collect` 会复制真实目录并跳过 symlink,因此 Agent 目录中的 symlink 不会被重复收集。
|
||||
### 第 3 步:选择本地副本或上游跟踪
|
||||
|
||||
**保留当前文件:**从存放真实目录的 target 预览并收集:
|
||||
|
||||
```bash
|
||||
skillshare collect universal --dry-run # 预览
|
||||
skillshare collect universal # ~/.agents/skills
|
||||
skillshare collect universal -g --dry-run
|
||||
skillshare collect universal -g
|
||||
```
|
||||
|
||||
如果你使用过 `--copy`,或在其他 Agent 目录中也有 Skill,请改为执行 `skillshare collect --all`,并按照[从手动管理迁移](#从手动管理迁移)中的说明处理重复项。
|
||||
这会收集该 target 中所有符合条件的 skills,不是单一选定的 skill。若副本位于某个 agent 目录,请换成配置中对应的 target 名称。只有打算收集所有配置 targets 时才用 `collect --all -g`。部分交接时,改为只将选定的真实 skill 目录复制到 Skillshare source。
|
||||
|
||||
收集到的 Skill 是普通的本地副本。它们不会记录来自哪个仓库,因此 `skillshare update` 无法更新它们。
|
||||
Collect 会跳过 skill symlink,包括指向 `node_modules` 的链接。这些 skills 可以继续由 npm 管理,或明确将解析后的真实 skill 目录复制为本地快照;副本之后不会随包更新。除非强制覆盖,collect 也会跳过 source 中已存在的名称。检查跳过/失败结果,并自行比较重复内容;预览不是理解 lock 的冲突报告。不要用 `collect --force` 盲目决定保留哪份内容。
|
||||
|
||||
### 第 4 步:重新安装需要持续更新的 Skill(可选)
|
||||
收集的 skills 没有导入仓库跟踪信息,因此 `skillshare update` 无法从原始来源更新它们。
|
||||
|
||||
Lock file 记录了每个 Skill 的来源。`source` 是仓库,`skillPath` 是 Skill 在仓库中的位置。
|
||||
**保留上游更新:**从来源安装前,先检查保存的每个 lock 条目。`sourceType` 区分 Git、npm、本地与其他来源;`sourceUrl`、`ref`、`skillPath` 可能提供额外信息。不是每个条目都有仓库或 `skillPath`。
|
||||
|
||||
例如 GitHub 条目 `source: "anthropics/skills"`、`skillPath: "skills/pdf/SKILL.md"` 对应的是包含该文件的 skill 目录:
|
||||
|
||||
```bash
|
||||
cat ~/.agents/.skill-lock.json
|
||||
|
||||
# "source": "anthropics/skills", "skillPath": "skills/pdf/SKILL.md"
|
||||
skillshare install anthropics/skills/skills/pdf
|
||||
skillshare install anthropics/skills/skills/pdf -g --dry-run
|
||||
skillshare install anthropics/skills/skills/pdf -g
|
||||
```
|
||||
|
||||
如果该 Skill 已在第 3 步中进入你的 Source,请加上 `--force`。
|
||||
若 lock 记录了 Git ref,请在上述两个命令都加上 `--branch <recorded-ref>`(见 [install](/docs/reference/commands/install));没有指定时,示例会使用远程默认分支。这是重新安装,不是重放 npx 的内容 hash。请与保存的文件比较并合并本地修改。若已收集的 skill 占用目标位置,先停止并处理;不要直接强制安装,因为可能覆盖修改并覆盖 audit 阻止结果。npm 与本地条目需要各自决定来源,不能直接转成 `owner/repo`。
|
||||
|
||||
### 第 5 步:Sync
|
||||
### 第 4 步:预览并明确移交管理权
|
||||
|
||||
```bash
|
||||
skillshare sync
|
||||
skillshare sync -g --dry-run
|
||||
```
|
||||
|
||||
在 merge mode 下,Sync 会保留 Target(`~/.agents/skills`)中同名的真实目录,并将其报告为保留的本地 Skill。其他 Agent 目录(例如 `~/.claude/skills`)中由 `npx skills` 创建的 symlink 会被重新指向你的 skillshare Source。如果还想把这些真实目录也替换为 symlink,请在第 3 步收集完成后执行:
|
||||
检查**所有配置的 targets**,不只是 `universal`。Merge mode 会保留同名本地目录,但即使没有 force,同名的 agent symlink 也可能被改为指向 Skillshare source。确认只影响打算交接的 skills 后才应用:
|
||||
|
||||
```bash
|
||||
skillshare sync --force
|
||||
skillshare sync -g
|
||||
```
|
||||
|
||||
`sync --force` 会在替换任何内容之前备份 Target。此后请只用 skillshare 管理这些 Skill。`npx skills` 在自己的 lock file 中记录安装信息,因此请避免对它们执行 `npx skills update` 或 `npx skills remove`。
|
||||
若也想把保留的真实目录换成链接,先确认 source 中是要保留的版本,且原始快照完整:
|
||||
|
||||
对于使用 `npx skills` 的项目,请按照[从已提交的项目 Skill 迁移](#从已提交的项目-skill-迁移)操作,并将 `.agents/skills/` 作为要迁移的目录。
|
||||
```bash
|
||||
skillshare sync -g --force --dry-run
|
||||
# Apply only after reviewing every replacement:
|
||||
skillshare sync -g --force
|
||||
```
|
||||
|
||||
Force 会作用于配置的 targets,不是单个 skill 的迁移开关。若预览包含仍由 npx skills 管理的资源,请停止。两个工具的管理范围应分开;见[并存说明](/docs/troubleshooting/faq#using-universal-alongside-npx-skills)。
|
||||
|
||||
### 第 5 步:验证并保留单一管理者
|
||||
|
||||
检查结果文件/链接,并确认各 AI 工具能加载预期的 skills。执行 `skillshare status -g`,检查保留的本地 skills 或警告;sync 成功不代表每个原始 skill 都已迁移。
|
||||
|
||||
Skillshare 不会移除旧 npx lock 条目。交接后不要对已迁移的 skills 使用 `npx skills update`、`remove`、`experimental_install` 或 `experimental_sync`。部分迁移时,避免未指定范围而包含它们的批量命令。
|
||||
|
||||
若要回滚,先暂停两个管理工具,再一起恢复保存的原始文件、链接布局与 lock。Skillshare target 备份可协助恢复本地文件,但无法单独重建原始 npx symlink 或 lock。
|
||||
|
||||
### 项目安装与 npm 同步
|
||||
|
||||
变更前保存项目文件与 lock,包含尚未提交或被忽略的本地修改。以 `skillshare init -p` 初始化并配置项目 targets,再对 `collect`、`install`、`sync` 使用 `-p`,而非上述全局命令。相同的来源跟踪与 symlink 限制仍适用。Skillshare 不会在项目模式创建 skill-target 备份;请使用已验证的项目快照,或确实包含相关文件的版本控制。
|
||||
|
||||
若 `package.json` scripts 或 CI 会调用 `experimental_sync`,交接重叠的 skills 前先调整任务与 skill 声明,否则下次安装依赖可能重新链接它们。继续让 npx skills 管理 npm skills 完全合理;不要把链接复制到 `.skillshare/skills/` 就以为已改为独立管理。
|
||||
|
||||
---
|
||||
|
||||
|
||||
+37
-163
@@ -2,190 +2,64 @@
|
||||
sidebar_position: 9
|
||||
---
|
||||
|
||||
# 比较 Skill 管理方案
|
||||
# 比较 Skill 管理方式
|
||||
|
||||
本页比较 AI CLI Skill 管理的两种主要架构方案:**命令式**(逐条命令安装)和**声明式**(配置 + sync)。
|
||||
**Vercel 的 `npx skills`** 和 **Skillshare** 都能跨多个 AI 工具管理 skills。差别不是“一个只能安装,另一个才能同步”,而是你需要管理 skills,还是更完整的 AI 工作环境。
|
||||
|
||||
如果你正在评估各种工具或考虑切换,这份分析能帮助你理解其中根本的设计差异。
|
||||
本页依据已发布的 **skills v1.7.6** [包信息](https://registry.npmjs.org/skills/1.7.6)及其[官方 CLI 文档](https://github.com/vercel-labs/skills/blob/7a5e920bead4b1039a6d6df5d7e1163b7b09423a/docs/commands.md)。实验性命令可能变更或移除;这是指定版本的比较,不是对所有安装工具的概括。
|
||||
|
||||
## 架构总览
|
||||
## 架构概览
|
||||
|
||||
### 命令式(逐条命令安装)
|
||||
### npx skills:发现与管理 skills
|
||||
|
||||
命令式工具采用逐条命令安装的模式——每次安装都是一次独立的操作:
|
||||
[skills.sh](https://skills.sh) 提供发现入口。CLI 支持多 agent、项目与全局安装、指向共享副本的符号链接或独立副本,以及更新检查与更新。Agent 选择及确认可通过参数提供,不一定需要交互提示。
|
||||
|
||||
```
|
||||
tool add owner/repo → select agents → choose method → done
|
||||
tool add owner/repo → select agents → choose method → done
|
||||
tool add owner/repo → select agents → choose method → done
|
||||
```
|
||||
它也会通过 lock 文件记录已安装的 skills。实验性命令支持项目恢复与 npm 同步,因此不能将它描述为没有持久状态或只能安装。
|
||||
|
||||
每次操作都需要用户输入。没有持久化状态来描述“哪里应该安装什么”。
|
||||
### Skillshare:跨工具管理工作环境
|
||||
|
||||
### 声明式(配置 + Sync)
|
||||
Skillshare 将源资源与 target 配置分开,再同步到各工具。除了 skills,也管理 agent 定义、rules 等 extras、MCP 连接设置,以及支持客户端的原生 hooks。本地 Web dashboard 提供可视化管理界面。
|
||||
|
||||
skillshare 采用声明式模型——你只需定义一次期望状态,然后执行 sync:
|
||||
真正的差别是将这些资源一起纳入跨工具、跨机器与团队工作流,而不是独有的符号链接或多 agent 安装能力。资源格式与客户端能力仍有差异,并非每种资源都适用于每个工具。
|
||||
|
||||
```yaml
|
||||
# config.yaml — define once
|
||||
source: ~/.config/skillshare/skills
|
||||
targets:
|
||||
claude: ~/.claude
|
||||
cursor: ~/.cursor/skills
|
||||
codex: ~/.codex/skills
|
||||
```
|
||||
## 功能比较
|
||||
|
||||
```bash
|
||||
skillshare sync # reconcile actual state to desired state
|
||||
```
|
||||
| 能力 | npx skills v1.7.6 | Skillshare |
|
||||
|------|------------------|------------|
|
||||
| **发现** | skills.sh 与 `skills find` | CLI 搜索与本地 Web dashboard |
|
||||
| **多 agent 与范围** | 多 agent;项目与全局安装 | 配置中的 targets;项目与全局模式 |
|
||||
| **共享 skill 文件** | 指向共享副本的符号链接;可选 copy | 源目录搭配 merge、copy 或整个目录的 symlink 模式 |
|
||||
| **更新** | `skills check` 与 `skills update` | `skillshare check` 与 `skillshare update` |
|
||||
| **项目恢复** | 实验性 `skills experimental_install` 从 `skills-lock.json` 恢复支持的来源 | 声明式 skill 配置与源资源;见 [manifest](/docs/understand/declarative-manifest) |
|
||||
| **npm 项目同步** | 实验性 `skills experimental_sync` 读取已安装依赖与 `package.json` 的 skill 声明 | 源到 target 的同步;不是相同的 npm 依赖工作流 |
|
||||
| **跨机器工作流** | 项目 lock 恢复与 npm 同步可协助重建项目 skills | Git `push` / `pull`,范围由 `git_root` 决定 |
|
||||
| **Skills 以外** | 所引用的 CLI 文档以 skills 为主 | Agent 定义、rules 等 extras、MCP 设置与支持客户端的 hooks |
|
||||
| **本地管理与恢复** | 所引用的 CLI 文档未列出本地 dashboard 或 target 备份命令 | `skillshare ui`、target 备份与恢复,以及受管理文件恢复 |
|
||||
| **运行环境** | Node.js 与 npm/npx | Go 可执行文件;Git 工作流需要 Git |
|
||||
|
||||
一条命令,无需任何提示,每次结果都是确定的。
|
||||
### 实验性命令涵盖什么
|
||||
|
||||
## 功能对比
|
||||
- **`experimental_install`** 将支持的 lock 条目恢复到 `.agents/skills/`。它不会安装 npm 依赖,也不会为恢复的 skills 创建 agent 专用链接。除非明确要求重新安装,否则保留已有 skills。Frozen-lock 模式会检查内容 hash,且为 CI 默认值。
|
||||
- **`experimental_sync`** 链接已安装 npm 依赖附带的 skills,并解析 `package.json` 的 skill 声明。它通过 `skills-lock.json` 跟踪这些条目、移除不再提供的 skills,并保留另外安装的 skills。使用 copy 时,依赖更新后需要再次同步。
|
||||
|
||||
| 能力 | 命令式(逐条命令安装) | 声明式(skillshare) |
|
||||
|------------|------------------------|--------------------------|
|
||||
| **配置** | 无配置文件;每次运行都要提示 | `config.yaml`——设置一次,永久复用 |
|
||||
| **Agent 选择** | 每次都要交互式提示 | 在配置中定义;`sync` 统一处理 |
|
||||
| **安装方式** | 每次操作都要选择 copy/symlink | 配置中的 `sync_mode`(merge、copy 或 symlink) |
|
||||
| **单一事实来源** | Skills 被独立复制到每个 agent | Source 目录 → 符号链接指向所有 Target |
|
||||
| **从某个 agent 移除 Skill** | 可能删除 source 文件,破坏其他 agent | 只影响该 Target 的符号链接 |
|
||||
| **可复现的环境搭建** | 没有内置的方式在新机器上恢复 | `config.yaml` + source 目录 = 完整恢复 |
|
||||
| **项目范围的 Skills** | 锁定文件只追踪全局层级 | `skillshare init -p` 用于按仓库管理 Skills |
|
||||
| **跨机器同步** | 手动(通过 dotfiles 同步锁定文件) | 内置的 `push` / `pull`,基于 git |
|
||||
| **双向流动** | 单向(仅安装) | `collect` 可以把 Target 上的改进拉回来 |
|
||||
| **区分自有 Skills 与已安装 Skills** | 混在同一目录下 | 被追踪的仓库使用 `_` 前缀 |
|
||||
| **离线操作** | CLI 本身就需要 npx + 网络 | 单一二进制文件,安装后可离线工作 |
|
||||
| **Web 控制台** | 无 | `skillshare ui`——可视化管理 |
|
||||
| **备份 / 恢复** | 无 | `skillshare backup` / `skillshare restore` |
|
||||
| **Git 平台支持** | update/check 仅支持 GitHub(写死使用 GitHub Trees API) | 任何 Git 远程仓库——GitHub、GitLab、Bitbucket、Azure DevOps、Gitea、AtomGit、Gitee、自建实例 |
|
||||
| **运行时依赖** | Node.js + npm | 无(单一 Go 二进制文件) |
|
||||
这些确实是同步与恢复能力,但不是整套 AI 工具配置的备份。
|
||||
|
||||
## 常见痛点及解决方案
|
||||
## 选择合适的工具
|
||||
|
||||
### “每次安装都要重新选择 agent”
|
||||
**继续使用 npx skills**:如果主要需求是发现、安装与更新公开或私有 skills,即使同时使用多个 agent 也很合理。若希望 skills 跟随 npm 项目依赖,且能接受此工作流仍属实验性,也适合考虑。
|
||||
|
||||
使用 skillshare,你只需配置一次 Target:
|
||||
**选择 Skillshare**:当问题不只是安装 skills,例如:“我同时用 Claude Code 和 Codex,希望把受管理的 skills、rules、MCP 设置与支持的 hooks 带到另一台电脑。”它的源/target 配置、Git 工作流、本地 dashboard 与恢复工具服务于这个更广的管理需求。
|
||||
|
||||
```yaml
|
||||
targets:
|
||||
claude: ~/.claude
|
||||
cursor: ~/.cursor/skills
|
||||
```
|
||||
可移植性仍需要配置:选择 Git 范围、在新机器配置 targets,并另外准备凭据与外部依赖。`push` 默认只处理 skills 源,不会自动发布全部配置或备份整台机器。见 [Git root 范围](/docs/reference/commands/push)与 [sync](/docs/reference/commands/sync)。
|
||||
|
||||
之后每次 `sync`、`install` 或 `collect` 都知道该同步到哪里,无需任何提示。
|
||||
## 迁移至 Skillshare
|
||||
|
||||
### “从一个 agent 移除 Skill 会连带破坏其他 agent”
|
||||
不必立刻取代运行良好的安装工具。只移交希望由 Skillshare 管理的资源,并避免两个工具同时更新或移除同一个受管理的 skill。
|
||||
|
||||
在命令式工具中,从某个 agent 移除 Skill 可能会删除共享的 source 文件,导致其他 agent 出现失效的符号链接。
|
||||
|
||||
skillshare 的架构从根本上避免了这个问题——source 目录是唯一的事实来源。Target 的符号链接指向 source,而不是反过来。移除某个 Target 只会移除该 Target 自己的符号链接,source 文件不受影响。
|
||||
|
||||
```
|
||||
Source: ~/.config/skillshare/skills/my-skill/SKILL.md (always preserved)
|
||||
├── ~/.claude/skills/my-skill → symlink to source ✓
|
||||
├── ~/.cursor/skills/my-skill → symlink to source ✓ (unaffected)
|
||||
└── ~/.codex/skills/my-skill → symlink to source ✓ (unaffected)
|
||||
```
|
||||
|
||||
### “没法在新机器上恢复我的配置”
|
||||
|
||||
使用 skillshare,你的整套配置都是可移植的:
|
||||
|
||||
1. 对 `~/.config/skillshare/`(source + 配置)进行版本控制
|
||||
2. 在新机器上:`git clone` 你的配置仓库
|
||||
3. 运行 `skillshare sync`
|
||||
|
||||
所有 Target 会立即被重新创建。
|
||||
|
||||
### “update 和 check 在 GitLab / Bitbucket / Azure DevOps 上不起作用”
|
||||
|
||||
命令式工具在检查更新时通常依赖 GitHub Trees API,这意味着 `update` 和 `check` 会默默跳过来自非 GitHub 来源的 Skills。
|
||||
|
||||
skillshare 使用**本地 git 操作**(`git fetch` + 目录树哈希比对)——它可以配合任何 Git 远程仓库使用,包括 GitLab、Bitbucket、Azure DevOps、Gitea、AtomGit、Gitee,以及任何自建实例,不需要平台专属的 API。
|
||||
|
||||
```bash
|
||||
# All of these support install, update, and check:
|
||||
skillshare install https://gitlab.com/team/skills
|
||||
skillshare install git@bitbucket.org:company/private-skills.git
|
||||
skillshare install https://git.mycompany.com/org/repo
|
||||
skillshare update # checks all sources, regardless of host
|
||||
```
|
||||
|
||||
### “大仓库 clone 起来要等很久”
|
||||
|
||||
skillshare 对非追踪安装默认使用浅克隆(`--depth 1`),大幅缩短下载时间。如果需要完整历史记录的追踪仓库,使用 `--track`。
|
||||
|
||||
### “我的 Skills 分散在各个 agent 目录里”
|
||||
|
||||
skillshare 把所有内容集中放在一个地方:
|
||||
|
||||
```
|
||||
~/.config/skillshare/skills/
|
||||
├── my-custom-skill/ # Your own skills
|
||||
├── react-best-practices/ # Installed skills
|
||||
├── _team-repo/ # Tracked repos (prefixed with _)
|
||||
│ ├── frontend-guidelines/
|
||||
│ └── code-review/
|
||||
└── _another-org-repo/
|
||||
```
|
||||
|
||||
`_` 前缀清楚地把被追踪的(团队/组织)仓库与你的个人 Skills 区分开。
|
||||
|
||||
## 迁移到 skillshare
|
||||
|
||||
如果你已经在使用其他 Skill 管理工具:
|
||||
|
||||
### 第一步:安装 skillshare
|
||||
|
||||
```bash
|
||||
# macOS / Linux
|
||||
curl -fsSL https://raw.githubusercontent.com/runkids/skillshare/main/install.sh | sh
|
||||
```
|
||||
|
||||
只有安装器显示 PATH 设置提示时,才需要按提示设置后再运行下方命令。没有 PATH 警告就不需要额外设置。
|
||||
|
||||
```bash
|
||||
|
||||
# Homebrew
|
||||
brew install skillshare
|
||||
```
|
||||
|
||||
### 第二步:初始化并收集现有 Skills
|
||||
|
||||
```bash
|
||||
skillshare init # Creates config and detects targets
|
||||
skillshare collect --all # Imports existing skills from all detected targets
|
||||
```
|
||||
|
||||
### 第三步:Sync
|
||||
|
||||
```bash
|
||||
skillshare sync # Symlinks source skills to all targets
|
||||
```
|
||||
|
||||
你现有的 Skills 现在都统一由一处管理。详细步骤请参见[迁移指南](/docs/how-to/advanced/migration)。
|
||||
|
||||
## 如何选择合适的工具
|
||||
|
||||
**在以下情况选择命令式工具:**
|
||||
- 你很少安装 Skills,也不介意交互式提示
|
||||
- 你只使用一个 AI CLI
|
||||
- 你不需要跨机器或团队协作的工作流
|
||||
|
||||
**在以下情况选择 skillshare:**
|
||||
- 你使用多个 AI CLI,并希望它们保持同步
|
||||
- 你想要一次设置、之后无需再管的配置
|
||||
- 你在多台机器上工作
|
||||
- 你与团队或组织共享 Skills
|
||||
- 你希望 Skills 能够备份、恢复并进行版本控制
|
||||
- 你把 Skills 托管在 GitLab、Bitbucket、Azure DevOps 或自建 Git 上
|
||||
- 你更喜欢没有运行时依赖的单一二进制文件
|
||||
- 你不希望安装/下载行为被本地工作流之外的系统追踪
|
||||
|
||||
---
|
||||
目前迁移并非无损的 lock 导入:收集的 skills 是本地副本,不保留原始 repository 的跟踪信息。若需要后续通过 Skillshare 更新,请从记录的来源重新安装。移交管理权前先备份与预览;请遵循 [npx skills 迁移指南](/docs/how-to/advanced/migration),不要将 collect 本身视为完整迁移。
|
||||
|
||||
## 另请参阅
|
||||
|
||||
- [迁移](/docs/how-to/advanced/migration) — 迁移指南
|
||||
- [核心概念](/docs/understand) — skillshare 的工作原理
|
||||
- [迁移](/docs/how-to/advanced/migration)
|
||||
- [核心概念](/docs/understand)
|
||||
- [备份](/docs/reference/commands/backup)
|
||||
|
||||
+70
-30
@@ -82,73 +82,113 @@ skillshare sync
|
||||
|
||||
---
|
||||
|
||||
## 從 `npx skills` 遷移
|
||||
## 從 `npx skills` 遷移 {#from-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` 管理原有 skills,也可以將選定的 skills 交給 Skillshare。兩者都支援多 agent 與全域/專案安裝;遷移的理由是需要 Skillshare 更廣的資源管理能力,而不是另一個工具只能安裝。見[比較頁](/docs/understand/philosophy/comparison)。
|
||||
|
||||
`npx skills` 存放各項內容的位置:
|
||||
**目前沒有自動匯入 npx lock 或移交管理權的功能。** Collect 保留本地 skill 檔案,不會匯入上游追蹤資訊。從 repository 重新安裝會建立 Skillshare 的追蹤資訊,但取得的內容可能與既有安裝不同。
|
||||
|
||||
以下路徑與 lock 欄位依據 **skills v1.7.6**:[全域 lock 原始碼](https://github.com/vercel-labs/skills/blob/7a5e920bead4b1039a6d6df5d7e1163b7b09423a/src/skill-lock.ts)、[專案 lock 原始碼](https://github.com/vercel-labs/skills/blob/7a5e920bead4b1039a6d6df5d7e1163b7b09423a/src/local-lock.ts)及 [CLI 文件](https://github.com/vercel-labs/skills/blob/7a5e920bead4b1039a6d6df5d7e1163b7b09423a/docs/commands.md)。
|
||||
|
||||
| 項目 | 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` |
|
||||
| 共用 skill 位置 | `~/.agents/skills/<name>/` | `.agents/skills/<name>/` |
|
||||
| Agent 目錄 | 通常是指向共用 skills 的連結;`--copy` 會建立獨立副本 | 同左 |
|
||||
| Lock 檔案 | 有設定時使用 `$XDG_STATE_HOME/skills/.skill-lock.json`,否則為 `~/.agents/.skill-lock.json` | `skills-lock.json` |
|
||||
|
||||
以 `--copy` 安裝的 Skills 在每個 Agent 目錄中都是實體目錄,而不是 symlink。
|
||||
`experimental_sync` 建立的 skills 可能是指向 npm 依賴的連結,而非實體目錄。收集前先檢查實際路徑。
|
||||
|
||||
### 步驟 1:初始化 skillshare
|
||||
### 步驟 1:決定範圍並保存原始設定
|
||||
|
||||
步驟 2–5 的指令明確使用**全域模式**(`-g`)。專案安裝請改看下方的專案說明。
|
||||
|
||||
初始化或同步前:
|
||||
|
||||
- 決定每個管理工具負責哪些 skills。遷移期間暫停更新、移除與自動同步工作。
|
||||
- 另外建立原始 skill 目錄、實際內容與 symlink 配置的快照。也要包含可能被取代的既有 Skillshare source。
|
||||
- 另存適用的 npx lock。npm 專案也要保存 `package.json` 與套件管理器的 lock;這些只記錄來源與依賴,不是本地修改的備份。
|
||||
|
||||
驗證交接完成前保留這份快照。不要刪除舊 lock,也不要把 `npx skills remove` 當作清理捷徑。
|
||||
|
||||
### 步驟 2:初始化但不複製,然後檢查備份
|
||||
|
||||
若尚未初始化 Skillshare,請在 **stdin 與 stdout 都連到終端的互動式環境**執行下列指令。不要透過管線或自動化執行:這些旗標不會停用初次同步,非互動初始化在選定 targets 後會自動同步。
|
||||
|
||||
```bash
|
||||
skillshare init
|
||||
skillshare init -g --no-copy --no-skill --no-git
|
||||
```
|
||||
|
||||
### 步驟 2:備份既有的 Skills
|
||||
選擇要管理的 targets,包含對應 `~/.agents/skills` 的 `universal`,並使用本流程採用的 merge mode。若提示是否立即同步,請拒絕。已有設定時,先檢查 source、[targets](/docs/reference/commands/target) 與模式,不要重設。
|
||||
|
||||
```bash
|
||||
skillshare backup
|
||||
skillshare backup -g --dry-run
|
||||
skillshare backup -g
|
||||
skillshare backup -g --list
|
||||
```
|
||||
|
||||
### 步驟 3:收集 Skills
|
||||
檢查輸出中的失敗,確認實際 skill 檔案已涵蓋。Target 備份會**略過 symlink**,不會備份連結指向的內容,也不包含 target 目錄外的 npx lock。它只是步驟 1 快照的補充,不能取代快照。
|
||||
|
||||
`collect` 會複製實體目錄並略過 symlink,因此 Agent 目錄中的 symlink 不會被重複收集。
|
||||
### 步驟 3:選擇本地副本或上游追蹤
|
||||
|
||||
**保留目前檔案:**從存放實體目錄的 target 預覽並收集:
|
||||
|
||||
```bash
|
||||
skillshare collect universal --dry-run # 預覽
|
||||
skillshare collect universal # ~/.agents/skills
|
||||
skillshare collect universal -g --dry-run
|
||||
skillshare collect universal -g
|
||||
```
|
||||
|
||||
如果你用過 `--copy`,或其他 Agent 目錄中也有 Skills,請改為執行 `skillshare collect --all`,並依照[從手動管理遷移](#從手動管理遷移)中的說明處理重複項目。
|
||||
這會收集該 target 中所有符合條件的 skills,不是單一選定的 skill。若副本位於個別 agent 目錄,請換成該設定中的 target 名稱。只有打算收集所有設定 targets 時才用 `collect --all -g`。部分交接時,改為只將選定的實體 skill 目錄複製到 Skillshare source。
|
||||
|
||||
收集來的 Skills 是單純的本機副本。它們不會記得來自哪個 repository,因此 `skillshare update` 無法更新它們。
|
||||
Collect 會略過 skill symlink,包括指向 `node_modules` 的連結。這些 skills 可以繼續由 npm 管理,或明確將解析後的實體 skill 目錄複製為本地快照;副本之後不會隨套件更新。除非強制覆寫,collect 也會略過 source 中已存在的名稱。檢查略過/失敗結果,並自行比較重複內容;預覽不是理解 lock 的衝突報告。不要用 `collect --force` 盲目決定保留哪份內容。
|
||||
|
||||
### 步驟 4:重新安裝想持續更新的 Skills(可選)
|
||||
收集的 skills 沒有匯入 repository 追蹤資訊,因此 `skillshare update` 無法從原始來源更新它們。
|
||||
|
||||
Lock file 記錄了每個 Skill 的來源。`source` 是 repository,`skillPath` 是它在 repository 中的位置。
|
||||
**保留上游更新:**從來源安裝前,先檢查保存的每個 lock 項目。`sourceType` 區分 Git、npm、本地與其他來源;`sourceUrl`、`ref`、`skillPath` 可能提供額外資訊。不是每個項目都有 repository 或 `skillPath`。
|
||||
|
||||
例如 GitHub 項目 `source: "anthropics/skills"`、`skillPath: "skills/pdf/SKILL.md"` 對應的是包含該檔案的 skill 目錄:
|
||||
|
||||
```bash
|
||||
cat ~/.agents/.skill-lock.json
|
||||
|
||||
# "source": "anthropics/skills", "skillPath": "skills/pdf/SKILL.md"
|
||||
skillshare install anthropics/skills/skills/pdf
|
||||
skillshare install anthropics/skills/skills/pdf -g --dry-run
|
||||
skillshare install anthropics/skills/skills/pdf -g
|
||||
```
|
||||
|
||||
如果該 Skill 已在步驟 3 中收集到你的 Source,請加上 `--force`。
|
||||
若 lock 記錄了 Git ref,請在上述兩個指令都加上 `--branch <recorded-ref>`(見 [install](/docs/reference/commands/install));沒有指定時,範例會使用遠端預設分支。這是重新安裝,不是重播 npx 的內容 hash。請與保存的檔案比較並整合本地修改。若已收集的 skill 佔用目的位置,先停止並處理;不要直接強制安裝,因為可能覆寫修改並覆蓋 audit 阻擋。npm 與本地項目需要各自決定來源,不能直接轉成 `owner/repo`。
|
||||
|
||||
### 步驟 5:Sync
|
||||
### 步驟 4:預覽並明確移交管理權
|
||||
|
||||
```bash
|
||||
skillshare sync
|
||||
skillshare sync -g --dry-run
|
||||
```
|
||||
|
||||
在 merge mode 下,sync 會保留 Target(`~/.agents/skills`)中同名的實體目錄,並將其回報為保留的本機 Skill。其他 Agent 目錄(例如 `~/.claude/skills`)中由 `npx skills` 建立的 symlink,會改為指向你的 skillshare Source。若也要把這些實體目錄換成 symlink,請在步驟 3 收集完成後執行:
|
||||
檢查**所有設定的 targets**,不只是 `universal`。Merge mode 會保留同名本地目錄,但即使沒有 force,同名的 agent symlink 也可能被改為指向 Skillshare source。確認只影響打算交接的 skills 後才套用:
|
||||
|
||||
```bash
|
||||
skillshare sync --force
|
||||
skillshare sync -g
|
||||
```
|
||||
|
||||
`sync --force` 會在取代任何內容之前先備份 Target。之後請只用 skillshare 管理這些 Skills。`npx skills` 會在自己的 lock file 中追蹤安裝紀錄,因此請避免對它們執行 `npx skills update` 或 `npx skills remove`。
|
||||
若也想把保留的實體目錄換成連結,先確認 source 中是要保留的版本,且原始快照完整:
|
||||
|
||||
若是使用 `npx skills` 的專案,請依照[從已 Commit 的 Project Skills 遷移](#從已-commit-的-project-skills-遷移)操作,並以 `.agents/skills/` 作為要搬移的目錄。
|
||||
```bash
|
||||
skillshare sync -g --force --dry-run
|
||||
# Apply only after reviewing every replacement:
|
||||
skillshare sync -g --force
|
||||
```
|
||||
|
||||
Force 會作用於設定的 targets,不是單一 skill 的遷移開關。若預覽包含仍由 npx skills 管理的資源,請停止。兩個工具的管理範圍應分開;見[並存說明](/docs/troubleshooting/faq#using-universal-alongside-npx-skills)。
|
||||
|
||||
### 步驟 5:驗證並保留單一管理者
|
||||
|
||||
檢查結果檔案/連結,並確認各 AI 工具能載入預期的 skills。執行 `skillshare status -g`,檢查保留的本地 skills 或警告;sync 成功不代表每個原始 skill 都已移轉。
|
||||
|
||||
Skillshare 不會移除舊 npx lock 項目。交接後不要對已遷移的 skills 使用 `npx skills update`、`remove`、`experimental_install` 或 `experimental_sync`。部分遷移時,避免未指定範圍而包含它們的批次命令。
|
||||
|
||||
若要回復,先暫停兩個管理工具,再一起還原保存的原始檔案、連結配置與 lock。Skillshare target 備份可協助復原本地檔案,但無法單獨重建原始 npx symlink 或 lock。
|
||||
|
||||
### 專案安裝與 npm 同步
|
||||
|
||||
變更前保存專案檔案與 lock,包含尚未提交或被忽略的本地修改。以 `skillshare init -p` 初始化並設定專案 targets,再對 `collect`、`install`、`sync` 使用 `-p`,而非上述全域指令。相同的來源追蹤與 symlink 限制仍適用。Skillshare 不會在專案模式建立 skill-target 備份;請使用已驗證的專案快照,或確實包含相關檔案的版本控制。
|
||||
|
||||
若 `package.json` scripts 或 CI 會呼叫 `experimental_sync`,交接重疊的 skills 前先調整工作與 skill 宣告,否則下次安裝依賴可能重新連結它們。繼續讓 npx skills 管理 npm skills 完全合理;不要把連結複製到 `.skillshare/skills/` 就以為已改為獨立管理。
|
||||
|
||||
---
|
||||
|
||||
|
||||
+37
-163
@@ -4,188 +4,62 @@ sidebar_position: 9
|
||||
|
||||
# 比較 Skill 管理方式
|
||||
|
||||
本頁比較 AI CLI skill 管理的兩種主要架構方式:**命令式**(每次操作各自安裝)與**宣告式**(config + sync)。
|
||||
**Vercel 的 `npx skills`** 和 **Skillshare** 都能跨多個 AI 工具管理 skills。差別不是「一個只能安裝,另一個才能同步」,而是你需要管理 skills,還是更完整的 AI 工作環境。
|
||||
|
||||
如果你正在評估工具或考慮換用其他方案,這篇分析能幫助你理解兩者在設計上的根本差異。
|
||||
本頁依據已發布的 **skills v1.7.6** [套件資訊](https://registry.npmjs.org/skills/1.7.6)及其[官方 CLI 文件](https://github.com/vercel-labs/skills/blob/7a5e920bead4b1039a6d6df5d7e1163b7b09423a/docs/commands.md)。實驗性命令可能變更或移除;這是指定版本的比較,不是對所有安裝工具的概括。
|
||||
|
||||
## 架構總覽
|
||||
## 架構概覽
|
||||
|
||||
### 命令式(每次操作各自安裝)
|
||||
### npx skills:發現與管理 skills
|
||||
|
||||
命令式工具採用每次操作各自安裝的模式 — 每次安裝都是獨立的操作:
|
||||
[skills.sh](https://skills.sh) 提供發現入口。CLI 支援多 agent、專案與全域安裝、指向共用副本的 symlink 或獨立複本,以及更新檢查與更新。Agent 選擇及確認可透過旗標提供,不一定需要互動提示。
|
||||
|
||||
```
|
||||
tool add owner/repo → select agents → choose method → done
|
||||
tool add owner/repo → select agents → choose method → done
|
||||
tool add owner/repo → select agents → choose method → done
|
||||
```
|
||||
它也會以 lock 檔案記錄已安裝的 skills。實驗性命令支援專案還原與 npm 同步,因此不能將它描述為沒有持久狀態或只能安裝。
|
||||
|
||||
每個操作都需要使用者輸入。沒有任何持久化狀態能描述「什麼東西該裝在哪裡」。
|
||||
### Skillshare:跨工具管理工作環境
|
||||
|
||||
### 宣告式(Config + Sync)
|
||||
Skillshare 將來源資源與 target 設定分開,再同步到各工具。除了 skills,也管理 agent 定義、rules 等 extras、MCP 連線設定,以及支援用戶端的原生 hooks。本地 Web dashboard 提供視覺化管理介面。
|
||||
|
||||
skillshare 採用宣告式模式 — 你只需定義一次期望狀態,然後執行 sync:
|
||||
|
||||
```yaml
|
||||
# config.yaml — define once
|
||||
source: ~/.config/skillshare/skills
|
||||
targets:
|
||||
claude: ~/.claude
|
||||
cursor: ~/.cursor/skills
|
||||
codex: ~/.codex/skills
|
||||
```
|
||||
|
||||
```bash
|
||||
skillshare sync # reconcile actual state to desired state
|
||||
```
|
||||
|
||||
一個命令,沒有提示,每次結果都一致可預期。
|
||||
真正的差別是將這些資源一起納入跨工具、跨機器與團隊工作流程,而不是獨有的 symlink 或多 agent 安裝能力。資源格式與用戶端能力仍有差異,並非每種資源都適用於每個工具。
|
||||
|
||||
## 功能比較
|
||||
|
||||
| 能力 | 命令式(每次操作各自安裝) | 宣告式(skillshare) |
|
||||
|------------|------------------------|--------------------------|
|
||||
| **設定** | 沒有設定檔;每次執行都會提示 | `config.yaml` — 設定一次,永久沿用 |
|
||||
| **Agent 選擇** | 每次都要互動式提示 | 定義在設定中;`sync` 一次處理全部 |
|
||||
| **安裝方式** | 每次操作各自選擇 copy/symlink | 設定中的 `sync_mode`(merge、copy 或 symlink) |
|
||||
| **單一事實來源** | Skills 各自獨立複製到每個 agent | Source 目錄 → symlink 到所有 targets |
|
||||
| **從單一 agent 移除 skill** | 可能刪除 source 檔案,波及其他 agent | 只影響該 target 的 symlink |
|
||||
| **可重現的設定** | 沒有內建方式能在新機器上還原 | `config.yaml` + source 目錄 = 完整還原 |
|
||||
| **Project-scoped skills** | Lock 檔案只追蹤全域範圍 | `skillshare init -p` 提供每個 repo 各自的 skills |
|
||||
| **跨機器同步** | 手動(透過 dotfiles 同步 lock 檔案) | 內建 `push` / `pull` 搭配 git |
|
||||
| **雙向流動** | 單向(僅安裝) | `collect` 能把 targets 上的改進拉回來 |
|
||||
| **區分自製與已安裝 skills** | 混在同一個目錄裡 | Tracked repos 使用 `_` 前綴 |
|
||||
| **離線操作** | CLI 本身就需要 npx + 網路 | 單一執行檔,安裝後可離線運作 |
|
||||
| **Web 儀表板** | 無 | `skillshare ui` — 視覺化管理 |
|
||||
| **備份/還原** | 無 | `skillshare backup` / `skillshare restore` |
|
||||
| **Git 平台支援** | update/check 僅限 GitHub(寫死使用 GitHub Trees API) | 任何 Git remote — GitHub、GitLab、Bitbucket、Azure DevOps、Gitea、AtomGit、Gitee、自架伺服器 |
|
||||
| **執行環境依賴** | Node.js + npm | 無(單一 Go 執行檔) |
|
||||
| 能力 | npx skills v1.7.6 | Skillshare |
|
||||
|------|------------------|------------|
|
||||
| **發現** | skills.sh 與 `skills find` | CLI 搜尋與本地 Web dashboard |
|
||||
| **多 agent 與範圍** | 多 agent;專案與全域安裝 | 設定中的 targets;專案與全域模式 |
|
||||
| **共用 skill 檔案** | 指向共用副本的 symlink;可選 copy | 來源目錄搭配 merge、copy 或整個目錄的 symlink 模式 |
|
||||
| **更新** | `skills check` 與 `skills update` | `skillshare check` 與 `skillshare update` |
|
||||
| **專案還原** | 實驗性 `skills experimental_install` 從 `skills-lock.json` 還原支援的來源 | 宣告式 skill 設定與來源資源;見 [manifest](/docs/understand/declarative-manifest) |
|
||||
| **npm 專案同步** | 實驗性 `skills experimental_sync` 讀取已安裝依賴與 `package.json` 的 skill 宣告 | 來源到 target 的同步;不是相同的 npm 依賴工作流程 |
|
||||
| **跨機器工作流程** | 專案 lock 還原與 npm 同步可協助重建專案 skills | Git `push` / `pull`,範圍由 `git_root` 決定 |
|
||||
| **Skills 以外** | 所引用的 CLI 文件以 skills 為主 | Agent 定義、rules 等 extras、MCP 設定與支援用戶端的 hooks |
|
||||
| **本地管理與復原** | 所引用的 CLI 文件未列出本地 dashboard 或 target 備份命令 | `skillshare ui`、target 備份與還原,以及受管理檔案復原 |
|
||||
| **執行環境** | Node.js 與 npm/npx | Go 執行檔;Git 工作流程需要 Git |
|
||||
|
||||
## 常見痛點的解法
|
||||
### 實驗性命令涵蓋什麼
|
||||
|
||||
### 「我每次安裝都要重新選一次 agent」
|
||||
- **`experimental_install`** 將支援的 lock 項目還原到 `.agents/skills/`。它不會安裝 npm 依賴,也不會為還原的 skills 建立 agent 專用連結。除非明確要求重新安裝,否則保留既有 skills。Frozen-lock 模式會檢查內容 hash,且為 CI 預設。
|
||||
- **`experimental_sync`** 連結已安裝 npm 依賴附帶的 skills,並解析 `package.json` 的 skill 宣告。它以 `skills-lock.json` 追蹤這些項目、移除不再提供的 skills,並保留另外安裝的 skills。使用 copy 時,依賴更新後需要再次同步。
|
||||
|
||||
用 skillshare,你只需要設定一次 targets:
|
||||
|
||||
```yaml
|
||||
targets:
|
||||
claude: ~/.claude
|
||||
cursor: ~/.cursor/skills
|
||||
```
|
||||
|
||||
之後每次 `sync`、`install` 或 `collect` 都知道要送去哪裡。不會再有提示。
|
||||
|
||||
### 「從一個 agent 移除 skill 會弄壞其他 agent」
|
||||
|
||||
在命令式工具中,從一個 agent 移除 skill 可能會刪掉共用的 source 檔案,讓其他 agent 留下損毀的 symlink。
|
||||
|
||||
skillshare 的架構完全避免了這個問題 — source 目錄是唯一的事實來源。Target 的 symlink 都指**向** source。移除一個 target 只會移除該 target 自己的 symlink;source 檔案不受影響。
|
||||
|
||||
```
|
||||
Source: ~/.config/skillshare/skills/my-skill/SKILL.md (always preserved)
|
||||
├── ~/.claude/skills/my-skill → symlink to source ✓
|
||||
├── ~/.cursor/skills/my-skill → symlink to source ✓ (unaffected)
|
||||
└── ~/.codex/skills/my-skill → symlink to source ✓ (unaffected)
|
||||
```
|
||||
|
||||
### 「我沒辦法在新機器上還原我的設定」
|
||||
|
||||
用 skillshare,你的整套設定都是可攜的:
|
||||
|
||||
1. 把 `~/.config/skillshare/`(source + config)納入版本控制
|
||||
2. 在新機器上:`git clone` 你的設定 repo
|
||||
3. 執行 `skillshare sync`
|
||||
|
||||
所有 targets 會立即被重新建立。
|
||||
|
||||
### 「Update 和 check 在 GitLab / Bitbucket / Azure DevOps 上不能用」
|
||||
|
||||
命令式工具通常依賴 GitHub Trees API 來做更新檢查,這代表 `update` 和 `check` 會默默略過來自非 GitHub 來源的 skills。
|
||||
|
||||
skillshare 使用**本機 git 操作**(`git fetch` + tree hash 比對)— 可以搭配任何 Git remote 運作,包括 GitLab、Bitbucket、Azure DevOps、Gitea、AtomGit、Gitee,以及任何自架的伺服器。不需要平台專屬的 API。
|
||||
|
||||
```bash
|
||||
# All of these support install, update, and check:
|
||||
skillshare install https://gitlab.com/team/skills
|
||||
skillshare install git@bitbucket.org:company/private-skills.git
|
||||
skillshare install https://git.mycompany.com/org/repo
|
||||
skillshare update # checks all sources, regardless of host
|
||||
```
|
||||
|
||||
### 「大型 repository clone 起來要花超久」
|
||||
|
||||
skillshare 預設對非 tracked 的安裝使用淺層 clone(`--depth 1`),大幅縮短下載時間。若 tracked repo 需要完整歷史紀錄,可使用 `--track`。
|
||||
|
||||
### 「我的 skills 散落在各個 agent 目錄裡」
|
||||
|
||||
skillshare 把所有東西集中在一個地方:
|
||||
|
||||
```
|
||||
~/.config/skillshare/skills/
|
||||
├── my-custom-skill/ # Your own skills
|
||||
├── react-best-practices/ # Installed skills
|
||||
├── _team-repo/ # Tracked repos (prefixed with _)
|
||||
│ ├── frontend-guidelines/
|
||||
│ └── code-review/
|
||||
└── _another-org-repo/
|
||||
```
|
||||
|
||||
`_` 前綴清楚區分了 tracked(團隊/組織)repo 與你個人的 skills。
|
||||
|
||||
## 遷移至 skillshare
|
||||
|
||||
如果你已經在使用其他的 skill 管理工具:
|
||||
|
||||
### 步驟 1:安裝 skillshare
|
||||
|
||||
```bash
|
||||
# macOS / Linux
|
||||
curl -fsSL https://raw.githubusercontent.com/runkids/skillshare/main/install.sh | sh
|
||||
```
|
||||
|
||||
只有安裝器顯示 PATH 設定提示時,才需要依提示設定後再執行下方指令。沒有 PATH 警告就不需要額外設定。
|
||||
|
||||
```bash
|
||||
|
||||
# Homebrew
|
||||
brew install skillshare
|
||||
```
|
||||
|
||||
### 步驟 2:初始化並收集既有 skills
|
||||
|
||||
```bash
|
||||
skillshare init # Creates config and detects targets
|
||||
skillshare collect --all # Imports existing skills from all detected targets
|
||||
```
|
||||
|
||||
### 步驟 3:Sync
|
||||
|
||||
```bash
|
||||
skillshare sync # Symlinks source skills to all targets
|
||||
```
|
||||
|
||||
你現有的 skills 現在都集中在同一個地方管理了。詳細步驟請見 [遷移指南](/docs/how-to/advanced/migration)。
|
||||
這些確實是同步與還原能力,但不是整套 AI 工具設定的備份。
|
||||
|
||||
## 選擇合適的工具
|
||||
|
||||
**在以下情況選擇命令式工具:**
|
||||
- 你很少安裝 skill,也不介意互動式提示
|
||||
- 你只使用一種 AI CLI
|
||||
- 你不需要跨機器或團隊協作的工作流程
|
||||
**繼續使用 npx skills**:如果主要需求是發現、安裝與更新公開或私有 skills,即使同時使用多個 agent 也很合理。若希望 skills 跟隨 npm 專案依賴,且能接受此工作流程仍屬實驗性,也適合考慮。
|
||||
|
||||
**在以下情況選擇 skillshare:**
|
||||
- 你同時使用多種 AI CLI,並希望它們保持同步
|
||||
- 你想要一次設定、之後就不用再管
|
||||
- 你在多台機器上工作
|
||||
- 你會與團隊或組織分享 skills
|
||||
- 你需要 skills 的備份、還原與版本控制
|
||||
- 你把 skills 放在 GitLab、Bitbucket、Azure DevOps 或自架 Git 上
|
||||
- 你偏好單一執行檔、不想有執行環境依賴
|
||||
- 你不希望安裝/下載活動被追蹤到你本機工作流程之外
|
||||
**選擇 Skillshare**:當問題不只是安裝 skills,例如:「我同時用 Claude Code 和 Codex,希望把受管理的 skills、rules、MCP 設定與支援的 hooks 帶到另一台電腦。」它的來源/target 設定、Git 工作流程、本地 dashboard 與復原工具服務於這個較廣的管理需求。
|
||||
|
||||
---
|
||||
可攜性仍需要設定:選擇 Git 範圍、在新機器設定 targets,並另外準備憑證與外部依賴。`push` 預設只處理 skills 來源,不會自動發布全部設定或備份整台機器。見 [Git root 範圍](/docs/reference/commands/push)與 [sync](/docs/reference/commands/sync)。
|
||||
|
||||
## 遷移至 Skillshare
|
||||
|
||||
不必立刻取代運作良好的安裝工具。只移交希望由 Skillshare 管理的資源,並避免兩個工具同時更新或移除同一個受管理的 skill。
|
||||
|
||||
目前遷移並非無損的 lock 匯入:收集的 skills 是本地副本,不保留原始 repository 的追蹤資訊。若需要後續透過 Skillshare 更新,請從記錄的來源重新安裝。移交管理權前先備份與預覽;請遵循 [npx skills 遷移指南](/docs/how-to/advanced/migration),不要將 collect 本身視為完整遷移。
|
||||
|
||||
## 延伸閱讀
|
||||
|
||||
- [Migration](/docs/how-to/advanced/migration) — 遷移指南
|
||||
- [Core Concepts](/docs/understand) — skillshare 如何運作
|
||||
- [遷移](/docs/how-to/advanced/migration)
|
||||
- [核心概念](/docs/understand)
|
||||
- [備份](/docs/reference/commands/backup)
|
||||
|
||||
Reference in New Issue
Block a user