diff --git a/ai_docs/tests/sync_adopts_moved_skill_runbook.md b/ai_docs/tests/sync_adopts_moved_skill_runbook.md new file mode 100644 index 000000000..e97d76323 --- /dev/null +++ b/ai_docs/tests/sync_adopts_moved_skill_runbook.md @@ -0,0 +1,154 @@ +# CLI E2E Runbook: sync Adopts a Hand-Moved Skill + +Verifies that `skillshare sync` moves the install record of a skill that was +moved with a plain `mv`, and that `sync` never prunes a record whose skill is +gone. `sync --dry-run` changes no record. + +**Origin**: follow-up to [#510](https://github.com/runkids/skillshare/issues/510) — +before this, only `install` or **Install missing** adopted a moved copy, so +`update` and `uninstall` could not find a skill after a hand `mv` + `sync`. + +## Scope + +- Global mode, one local-path skill +- `sync --dry-run` leaves the record at the old path +- `sync` re-keys the record to the new path and renames the target link +- `sync` keeps the record of a skill whose directory was removed by hand +- `uninstall` finds the skill by its new path + +## Environment + +Run inside the devcontainer with `ssenv` isolation (`--init`). +Requires `jq`. mdproof replaces `$HOME`, so the source is read through +`$XDG_CONFIG_HOME` and the target path through `ss status --json`. + +## Steps + +### 1. Setup: install two local skills and sync + +```bash +rm -rf /tmp/ss-adopt-src +mkdir -p /tmp/ss-adopt-src/adopt-skill /tmp/ss-adopt-src/gone-skill +printf -- "---\nname: adopt-skill\n---\n# Adopt\n" > /tmp/ss-adopt-src/adopt-skill/SKILL.md +printf -- "---\nname: gone-skill\n---\n# Gone\n" > /tmp/ss-adopt-src/gone-skill/SKILL.md +ss install /tmp/ss-adopt-src/adopt-skill -g +ss install /tmp/ss-adopt-src/gone-skill -g +ss sync -g +CLAUDE=$(ss status -g --json | jq -r '.targets[] | select(.name=="claude") | .path') +ls "$CLAUDE" +``` + +Expected: +- exit_code: 0 +- adopt-skill +- gone-skill + +### 2. Records are keyed by the flat names + +```bash +jq -c '.entries | {adopt: .["adopt-skill"].type, gone: .["gone-skill"].type}' $XDG_CONFIG_HOME/skillshare/skills/.metadata.json +``` + +Expected: +- exit_code: 0 +- jq: .adopt == "local" +- jq: .gone == "local" + +### 3. Move one skill by hand and delete the other + +```bash +SRC="$XDG_CONFIG_HOME/skillshare/skills" +mkdir -p "$SRC/grp" +mv "$SRC/adopt-skill" "$SRC/grp/adopt-skill" +rm -rf "$SRC/gone-skill" +ls "$SRC/grp" +``` + +Expected: +- exit_code: 0 +- adopt-skill + +### 4. Dry-run sync reports a dry run + +```bash +ss sync -g --dry-run --json +``` + +Expected: +- exit_code: 0 +- jq: .dry_run == true + +### 5. Dry run changed no record + +```bash +jq -c '.entries | keys' $XDG_CONFIG_HOME/skillshare/skills/.metadata.json +``` + +Expected: +- exit_code: 0 +- jq: index("adopt-skill") != null +- jq: index("grp/adopt-skill") == null +- jq: index("gone-skill") != null + +### 6. Real sync succeeds + +```bash +ss sync -g --json +``` + +Expected: +- exit_code: 0 +- jq: .dry_run == false + +### 7. The moved record followed and the gone record survived + +```bash +jq -c '.entries | {keys: keys, group: .["grp/adopt-skill"].group, type: .["grp/adopt-skill"].type}' $XDG_CONFIG_HOME/skillshare/skills/.metadata.json +``` + +Expected: +- exit_code: 0 +- jq: (.keys | index("grp/adopt-skill")) != null +- jq: (.keys | index("adopt-skill")) == null +- jq: (.keys | index("gone-skill")) != null +- jq: .group == "grp" +- jq: .type == "local" + +### 8. The target link uses the new flat name + +```bash +CLAUDE=$(ss status -g --json | jq -r '.targets[] | select(.name=="claude") | .path') +ls "$CLAUDE" +echo "gone-count=$(ls "$CLAUDE" | grep -c gone-skill)" +``` + +Expected: +- exit_code: 0 +- grp__adopt-skill +- gone-count=0 + +### 9. uninstall finds the skill by its new path + +```bash +ss uninstall grp/adopt-skill -g --json +``` + +Expected: +- exit_code: 0 + +### 10. The record is gone after uninstall + +```bash +jq -c '.entries | keys' $XDG_CONFIG_HOME/skillshare/skills/.metadata.json +``` + +Expected: +- exit_code: 0 +- jq: index("grp/adopt-skill") == null + +## Pass Criteria + +- Step 5: `sync --dry-run` leaves `adopt-skill` and `gone-skill` keyed at their old paths. +- Step 7: `sync` re-keys `adopt-skill` to `grp/adopt-skill` with group `grp` and keeps `gone-skill`. +- Step 8: the claude target holds `grp__adopt-skill` and the removed `gone-skill` link is pruned. +- Step 9: `uninstall grp/adopt-skill` exits 0. diff --git a/cmd/skillshare/sync.go b/cmd/skillshare/sync.go index 084ce432e..307aaf4fc 100644 --- a/cmd/skillshare/sync.go +++ b/cmd/skillshare/sync.go @@ -13,6 +13,7 @@ import ( "skillshare/internal/backup" "skillshare/internal/config" "skillshare/internal/hooks" + "skillshare/internal/install" "skillshare/internal/mcp" "skillshare/internal/oplog" "skillshare/internal/skillignore" @@ -359,6 +360,18 @@ func cmdSync(args []string) error { return agentErr } + // A skill moved by hand keeps its install record; sync never prunes one. + var metaWarnings []string + if !dryRun { + store, adoptErr := install.LoadMetadata(cfg.EffectiveSkillsSource()) + if adoptErr == nil { + adoptErr = config.AdoptMovedGlobalSkills(cfg, store) + } + if adoptErr != nil { + metaWarnings = append(metaWarnings, fmt.Sprintf("install metadata not updated: %v", adoptErr)) + } + } + // Phase 1: Discovery (skills) var spinner *ui.Spinner if !jsonOutput { @@ -380,7 +393,7 @@ func cmdSync(args []string) error { reportCollisions(discoveredSkills, cfg.Targets) } sourceIncomplete := walk.Follow.Incomplete() - linkWarnings := sync.SourceLinkWarnings(walk, sourceIncomplete) + linkWarnings := append(metaWarnings, sync.SourceLinkWarnings(walk, sourceIncomplete)...) if !jsonOutput { for _, w := range linkWarnings { ui.Warning("%s", w) diff --git a/cmd/skillshare/sync_project.go b/cmd/skillshare/sync_project.go index 1790ae601..ee9780afe 100644 --- a/cmd/skillshare/sync_project.go +++ b/cmd/skillshare/sync_project.go @@ -53,6 +53,14 @@ func cmdSyncProject(root string, dryRun, force, jsonOutput, quiet bool) (syncLog return stats, nil, nil, nil, nil, nil, fmt.Errorf("source directory does not exist: %s", runtime.sourcePath) } + // A skill moved by hand keeps its install record; sync never prunes one. + var metaWarnings []string + if !dryRun { + if rErr := config.AdoptMovedProjectSkills(root, cfg, runtime.skillsStore, runtime.sourcePath); rErr != nil { + metaWarnings = append(metaWarnings, fmt.Sprintf("install metadata not updated: %v", rErr)) + } + } + // Phase 1: Discovery var spinner *ui.Spinner if !jsonOutput { @@ -71,7 +79,7 @@ func cmdSyncProject(root string, dryRun, force, jsonOutput, quiet bool) (syncLog reportCollisions(discoveredSkills, runtime.targets) } sourceIncomplete := walk.Follow.Incomplete() - linkWarnings := sync.SourceLinkWarnings(walk, sourceIncomplete) + linkWarnings := append(metaWarnings, sync.SourceLinkWarnings(walk, sourceIncomplete)...) if !jsonOutput { for _, w := range linkWarnings { ui.Warning("%s", w) diff --git a/internal/config/project_reconcile.go b/internal/config/project_reconcile.go index f14121323..e5fe93188 100644 --- a/internal/config/project_reconcile.go +++ b/internal/config/project_reconcile.go @@ -16,6 +16,16 @@ import ( // and ensures they are present in the MetadataStore. // It also updates the project directory's .gitignore for each tracked skill. func ReconcileProjectSkills(projectRoot string, projectCfg *ProjectConfig, store *install.MetadataStore, sourcePath string) error { + return reconcileProjectSkills(projectRoot, projectCfg, store, sourcePath, true) +} + +// AdoptMovedProjectSkills is ReconcileProjectSkills without the prune; see +// AdoptMovedGlobalSkills. +func AdoptMovedProjectSkills(projectRoot string, projectCfg *ProjectConfig, store *install.MetadataStore, sourcePath string) error { + return reconcileProjectSkills(projectRoot, projectCfg, store, sourcePath, false) +} + +func reconcileProjectSkills(projectRoot string, projectCfg *ProjectConfig, store *install.MetadataStore, sourcePath string, prune bool) error { if _, err := os.Stat(sourcePath); os.IsNotExist(err) { return nil } @@ -52,15 +62,15 @@ func ReconcileProjectSkills(projectRoot string, projectCfg *ProjectConfig, store return fmt.Errorf("failed to scan project skills: %w", err) } - if !result.incomplete && pruneStaleEntries(store, result.live) { + if prune && !result.incomplete && pruneStaleEntries(store, result.live) { result.changed = true } // A moved skill's old ignore rule would keep ignoring whatever lands there. - if gitignoreDir != "" && len(result.movedFrom) > 0 { + if gitignoreDir != "" && len(result.moved) > 0 { var stale []string - for _, old := range result.movedFrom { - stale = append(stale, prefix+"/"+old) + for _, m := range result.moved { + stale = append(stale, prefix+"/"+m.from) } if _, err := install.RemoveFromGitIgnoreBatch(gitignoreDir, stale); err != nil { return fmt.Errorf("failed to update .gitignore: %w", err) @@ -91,6 +101,23 @@ func ReconcileProjectSkills(projectRoot string, projectCfg *ProjectConfig, store } if projectCfg != nil { + // The pin must follow first, or WriteProjectLock pins the local commit. + if len(result.moved) > 0 { + dir := projectdir.Resolve(projectRoot) + lock, err := install.LoadLock(dir) + if err != nil { + return err + } + changed := false + for _, m := range result.moved { + changed = lock.MovePin(m.from, m.to) || changed + } + if changed { + if err := lock.Save(dir); err != nil { + return fmt.Errorf("failed to write %s: %w", install.LockFileName, err) + } + } + } if err := WriteProjectLock(projectRoot, projectCfg, store, sourcePath); err != nil { return fmt.Errorf("failed to write %s: %w", install.LockFileName, err) } diff --git a/internal/config/project_reconcile_test.go b/internal/config/project_reconcile_test.go index fad63ca49..d53e04bd8 100644 --- a/internal/config/project_reconcile_test.go +++ b/internal/config/project_reconcile_test.go @@ -430,3 +430,49 @@ func TestReconcileProjectSkills_MovedSkillKeepsGroupAndPin(t *testing.T) { t.Error("the pin of the old path was left behind") } } + +// TestReconcileProjectSkills_HandMovedSkillKeepsPin verifies that adopting a +// copy moved with mv re-keys the lock pin instead of pinning the local commit. +func TestReconcileProjectSkills_HandMovedSkillKeepsPin(t *testing.T) { + root := t.TempDir() + skillsDir := filepath.Join(root, ".skillshare", "skills") + moved := filepath.Join(skillsDir, "grp", "demo") + if err := os.MkdirAll(moved, 0755); err != nil { + t.Fatal(err) + } + if err := os.WriteFile(filepath.Join(moved, "SKILL.md"), []byte("---\nname: demo\n---\n"), 0644); err != nil { + t.Fatal(err) + } + hashes, err := install.ComputeFileHashes(moved) + if err != nil { + t.Fatal(err) + } + pinned := strings.Repeat("a", 40) + installed := strings.Repeat("b", 40) + dir := filepath.Join(root, ".skillshare") + lock := &install.Lock{Skills: map[string]install.LockEntry{"demo": {Source: "github.com/user/repo/demo", Commit: pinned}}} + if err := lock.Save(dir); err != nil { + t.Fatal(err) + } + cfg := &ProjectConfig{ + Targets: []ProjectTargetEntry{{Name: "claude"}}, + Skills: []SkillEntry{{Name: "demo", Source: "github.com/user/repo/demo"}}, + } + store := install.NewMetadataStore() + store.Set("demo", &install.MetadataEntry{Source: "github.com/user/repo/demo", Commit: installed, FileHashes: hashes}) + + if err := AdoptMovedProjectSkills(root, cfg, store, skillsDir); err != nil { + t.Fatal(err) + } + + got, err := install.LoadLock(dir) + if err != nil { + t.Fatal(err) + } + if pin := got.Skills["grp/demo"]; pin.Commit != pinned { + t.Errorf("pin = %+v, want the shared commit kept under grp/demo", pin) + } + if _, stale := got.Skills["demo"]; stale { + t.Error("the pin of the old path was left behind") + } +} diff --git a/internal/config/reconcile.go b/internal/config/reconcile.go index def06ff7d..0dc38eaef 100644 --- a/internal/config/reconcile.go +++ b/internal/config/reconcile.go @@ -11,6 +11,17 @@ import ( // skills (those with install metadata or tracked repos) and ensures they are // present in the MetadataStore. func ReconcileGlobalSkills(cfg *Config, store *install.MetadataStore) error { + return reconcileGlobalSkills(cfg, store, true) +} + +// AdoptMovedGlobalSkills is ReconcileGlobalSkills without the prune: a record +// follows its moved copy, but a record whose skill is gone stays. sync runs it, +// since sync must never drop audit acceptances. +func AdoptMovedGlobalSkills(cfg *Config, store *install.MetadataStore) error { + return reconcileGlobalSkills(cfg, store, false) +} + +func reconcileGlobalSkills(cfg *Config, store *install.MetadataStore, prune bool) error { sourcePath := cfg.EffectiveSkillsSource() if _, err := os.Stat(sourcePath); os.IsNotExist(err) { return nil @@ -21,7 +32,7 @@ func ReconcileGlobalSkills(cfg *Config, store *install.MetadataStore) error { return fmt.Errorf("failed to scan global skills: %w", err) } - if !result.incomplete && pruneStaleEntries(store, result.live) { + if prune && !result.incomplete && pruneStaleEntries(store, result.live) { result.changed = true } diff --git a/internal/config/reconcile_core.go b/internal/config/reconcile_core.go index e4ad6b410..d72b2c46b 100644 --- a/internal/config/reconcile_core.go +++ b/internal/config/reconcile_core.go @@ -20,10 +20,12 @@ type reconcileResult struct { // incomplete means a followed source link could not be read, so entries // absent from live may still exist and must not be removed. incomplete bool - // movedFrom lists the source-relative paths records were moved away from. - movedFrom []string + // moved lists the records that followed a hand-moved copy, by source-relative path. + moved []movedRecord } +type movedRecord struct{ from, to string } + // reconcileSkillsWalk walks sourcePath for installed skills (those with metadata // or tracked repos) and ensures they are present in the MetadataStore. // onFound is called for each discovered installed skill; pass nil to skip. @@ -67,11 +69,13 @@ func reconcileSkillsWalk(sourcePath string, walk sourcewalk.Options, store *inst var source string tracked := install.IsTrackedCheckout(path) + // A basename key is this skill's record only when its group matches. A + // top-level record found under another folder is a move candidate, and + // MovedEntryKey below decides on gone path, hashes and uniqueness. existing := store.Get(fullPath) - if existing == nil || !tracked { - existing = store.GetByPath(fullPath) - if tracked && existing != nil && existing.Group != group { - existing = nil + if existing == nil { + if e := store.GetByPath(fullPath); e != nil && e.Group == group { + existing = e } } // A skill moved with mv takes its record along once the walk shows a @@ -161,7 +165,7 @@ func reconcileSkillsWalk(sourcePath string, walk sourcewalk.Options, store *inst continue } entry := store.Get(key) - result.movedFrom = append(result.movedFrom, filepath.ToSlash(install.KeyToRelPath(key, entry))) + result.moved = append(result.moved, movedRecord{filepath.ToSlash(install.KeyToRelPath(key, entry)), dests[0]}) store.MoveEntry(key, dests[0]) entry.Group = "" if idx := strings.LastIndex(dests[0], "/"); idx >= 0 { diff --git a/internal/config/reconcile_test.go b/internal/config/reconcile_test.go index 99b57f330..a195f2930 100644 --- a/internal/config/reconcile_test.go +++ b/internal/config/reconcile_test.go @@ -563,3 +563,68 @@ func TestReconcileGlobalSkills_PrunesDeletedNestedRecord(t *testing.T) { t.Error("the installed parent's record must stay") } } + +// TestAdoptMovedGlobalSkills_FollowsMoveButKeepsGoneRecord verifies the sync +// variant: a moved copy takes its record, a record without a copy survives. +func TestAdoptMovedGlobalSkills_FollowsMoveButKeepsGoneRecord(t *testing.T) { + root := t.TempDir() + sourceDir := filepath.Join(root, "skills") + t.Setenv("SKILLSHARE_CONFIG", filepath.Join(root, "config.yaml")) + moved := filepath.Join(sourceDir, "new", "demo") + if err := os.MkdirAll(moved, 0755); err != nil { + t.Fatal(err) + } + if err := os.WriteFile(filepath.Join(moved, "SKILL.md"), []byte("---\nname: demo\n---\n"), 0644); err != nil { + t.Fatal(err) + } + hashes, err := install.ComputeFileHashes(moved) + if err != nil { + t.Fatal(err) + } + store := install.NewMetadataStore() + store.Set("old/demo", &install.MetadataEntry{Source: "github.com/user/repo/demo", Group: "old", FileHashes: hashes}) + store.Set("gone", &install.MetadataEntry{Source: "github.com/user/gone"}) + + if err := AdoptMovedGlobalSkills(&Config{Source: sourceDir}, store); err != nil { + t.Fatal(err) + } + + if !store.Has("new/demo") || store.Has("old/demo") { + t.Errorf("entries = %v, want old/demo moved to new/demo", store.List()) + } + if !store.Has("gone") { + t.Errorf("entries = %v, want the gone record kept", store.List()) + } +} + +// TestAdoptMovedGlobalSkills_NestedSameNameLeavesLiveRecord verifies that a +// nested skill sharing a top-level record's name does not take that record +// while the top-level directory still exists. +func TestAdoptMovedGlobalSkills_NestedSameNameLeavesLiveRecord(t *testing.T) { + root := t.TempDir() + sourceDir := filepath.Join(root, "skills") + t.Setenv("SKILLSHARE_CONFIG", filepath.Join(root, "config.yaml")) + for _, dir := range []string{"demo", "grp/demo"} { + p := filepath.Join(sourceDir, filepath.FromSlash(dir)) + if err := os.MkdirAll(p, 0755); err != nil { + t.Fatal(err) + } + if err := os.WriteFile(filepath.Join(p, "SKILL.md"), []byte("---\nname: demo\n---\n"+dir), 0644); err != nil { + t.Fatal(err) + } + } + hashes, err := install.ComputeFileHashes(filepath.Join(sourceDir, "demo")) + if err != nil { + t.Fatal(err) + } + store := install.NewMetadataStore() + store.Set("demo", &install.MetadataEntry{Source: "github.com/user/repo/demo", FileHashes: hashes}) + + if err := AdoptMovedGlobalSkills(&Config{Source: sourceDir}, store); err != nil { + t.Fatal(err) + } + + if !store.Has("demo") || store.Has("grp/demo") { + t.Errorf("entries = %v, want only the live top-level record", store.List()) + } +} diff --git a/internal/server/handler_install.go b/internal/server/handler_install.go index fce1ac8ba..c97c73fac 100644 --- a/internal/server/handler_install.go +++ b/internal/server/handler_install.go @@ -42,6 +42,21 @@ func (s *Server) reconcileSkills(sourceDir string) error { return config.ReconcileGlobalSkills(s.cfg, s.skillsStore) } +// adoptMovedSkills is reconcileSkills without the prune, for sync. It reads +// the store from disk first: the cached one may be the empty stand-in New +// uses when the file does not load, and saving that would drop every record. +func (s *Server) adoptMovedSkills() error { + st, err := install.LoadMetadataWithMigration(s.cfg.EffectiveSkillsSource(), "") + if err != nil { + return err + } + s.skillsStore = st + if s.IsProjectMode() { + return config.AdoptMovedProjectSkills(s.projectRoot, s.projectCfg, s.skillsStore, s.cfg.EffectiveSkillsSource()) + } + return config.AdoptMovedGlobalSkills(s.cfg, s.skillsStore) +} + // checkInstallInto refuses an into folder an install must not land in: inside // a skill or inside a tracked checkout, with the codes move uses. A path below // a source link is left to the install, which follows it or refuses it itself. It writes the response and returns false when it refuses. diff --git a/internal/server/handler_sync.go b/internal/server/handler_sync.go index 57cdd92f4..59f83ba5c 100644 --- a/internal/server/handler_sync.go +++ b/internal/server/handler_sync.go @@ -227,6 +227,11 @@ func (s *Server) syncResources(start time.Time, dryRun, force bool, kind, projec // Skill sync (skip when kind == "agent") if kind != kindAgent { var err error + if !dryRun { + if err := s.adoptMovedSkills(); err != nil { + warnings = append(warnings, "install metadata not updated: "+err.Error()) + } + } walk := s.skillsWalk() allSkills, ignoreStats, err = ssync.DiscoverSourceSkillsWithStatsAndContext(s.cfg.EffectiveSkillsSource(), walk) if err != nil { diff --git a/internal/server/handler_sync_test.go b/internal/server/handler_sync_test.go index bce95df6e..c4a1f1935 100644 --- a/internal/server/handler_sync_test.go +++ b/internal/server/handler_sync_test.go @@ -910,3 +910,34 @@ func TestHandleSync_ProjectTargetWithoutPathFailsAlone(t *testing.T) { t.Fatalf("expected one config failure for custom, got %+v", resp.Failed) } } + +// TestHandleSync_MalformedMetadataIsWarnedNotOverwritten verifies that sync +// refuses to adopt moved records when .metadata.json does not load, so the +// empty stand-in store is never saved over it. +func TestHandleSync_MalformedMetadataIsWarnedNotOverwritten(t *testing.T) { + tgtPath := filepath.Join(t.TempDir(), "claude-skills") + s, src := newTestServerWithTargets(t, map[string]string{"claude": tgtPath}) + addSkill(t, src, "alpha") + metaPath := filepath.Join(src, install.MetadataFileName) + if err := os.WriteFile(metaPath, []byte("{not json"), 0644); err != nil { + t.Fatal(err) + } + + req := httptest.NewRequest(http.MethodPost, "/api/sync", strings.NewReader(`{"dryRun":false}`)) + rr := httptest.NewRecorder() + s.handler.ServeHTTP(rr, req) + + if rr.Code != http.StatusOK { + t.Fatalf("expected 200, got %d: %s", rr.Code, rr.Body.String()) + } + var resp struct { + Warnings []string `json:"warnings"` + } + json.Unmarshal(rr.Body.Bytes(), &resp) + if !slices.ContainsFunc(resp.Warnings, func(w string) bool { return strings.HasPrefix(w, "install metadata not updated") }) { + t.Errorf("warnings = %v, want the metadata load failure", resp.Warnings) + } + if data, _ := os.ReadFile(metaPath); string(data) != "{not json" { + t.Errorf("metadata file = %q, want it left untouched", data) + } +} diff --git a/skills/skillshare/references/sync.md b/skills/skillshare/references/sync.md index f31bd9058..07c258670 100644 --- a/skills/skillshare/references/sync.md +++ b/skills/skillshare/references/sync.md @@ -22,6 +22,8 @@ skillshare sync --json # JSON output skillshare sync -g # Force global mode ``` +Before linking, `sync` adopts the install record of a skill moved by hand (`mv`) when exactly one unchanged copy with that name exists; it never removes a record. `--dry-run` adopts nothing. + Sync runs every target. A target whose sync fails, or whose own settings are invalid (for example a skills path that is a file), is reported as failed and skipped; the rest still sync and the command exits non-zero. Config-wide problems (source, global `mode`/`target_naming`, `git_root`, extras) still stop sync before any target runs. Under `target_naming: standard`, a skill name must equal its directory name and use at most 64 lowercase letters (any script), digits and single hyphens, with no leading or trailing `-` and no underscores; other skills are warned and skipped. `target_naming: prefixed` (copy mode only; merge or symlink targets fail validation, and `status` and `doctor` flag them before sync, `target list` too for targets under `targets:`, with the fix `mode: copy`) applies the same check, then names each skill inside a tracked repo `-` (repo folder without `_`, e.g. `mattpocock-skills-prototype`) in both the folder and the copy's `name:`, so same-named skills from different repos both sync; a name already starting with the repo is kept, and prefixed names over 64 characters are skipped. Switching between namings renames managed entries in place. ### Sync modes (quick reference) diff --git a/website/docs/how-to/daily-tasks/organizing-skills.md b/website/docs/how-to/daily-tasks/organizing-skills.md index 966c22646..9aedd057d 100644 --- a/website/docs/how-to/daily-tasks/organizing-skills.md +++ b/website/docs/how-to/daily-tasks/organizing-skills.md @@ -290,7 +290,7 @@ skillshare sync After `sync`, targets are updated automatically — old flat symlinks are cleaned up and new flattened names are created. :::warning Skills installed with `skillshare install` -Do not move an installed skill with `mv`. Its install record in `.metadata.json` is keyed by its path, so the record stays at the old path until the next `install` or **Install missing** recognizes the moved copy (same name, files unchanged since install, only one such copy) and moves it; until then `update` and `uninstall` cannot find the skill, and the project lock pin and `.skillignore` lines never follow. Use [`skillshare move`](/docs/reference/commands/move) instead. It moves the skill together with its install record, so nothing is downloaded again: +Do not move an installed skill with `mv`. Its install record in `.metadata.json` is keyed by its path, so the record stays at the old path until the next `sync`, `install` or **Install missing** recognizes the moved copy (same name, files unchanged since install, only one such copy) and moves it; until then `update` and `uninstall` cannot find the skill, and `.skillignore` lines never follow. Use [`skillshare move`](/docs/reference/commands/move) instead. It moves the skill together with its install record, so nothing is downloaded again: ```bash skillshare move react-best-practices frontend/react diff --git a/website/docs/reference/commands/move.md b/website/docs/reference/commands/move.md index 94bb91ad8..be55e414c 100644 --- a/website/docs/reference/commands/move.md +++ b/website/docs/reference/commands/move.md @@ -25,7 +25,7 @@ For skills you created yourself with `skillshare new`, a plain `mv` + `sync` wor ## Compared with `mv` -A hand `mv` renames the directory and nothing else. `sync` still updates the links in your targets, and the next `install` or **Install missing** adopts the moved copy of an installed skill and moves its record and accepted audit findings, as long as the copy has the same name, its files are unchanged since the install and there is only one such copy. Until then `update` and `uninstall` do not find the skill. +A hand `mv` renames the directory and nothing else. The next `sync`, `install` or **Install missing** adopts the moved copy of an installed skill and moves its record, accepted audit findings and project lock pin, as long as the copy has the same name, its files are unchanged since the install and there is only one such copy. Until then `update` and `uninstall` do not find the skill. `sync --dry-run` adopts nothing. What `mv` never does, and `move` does: diff --git a/website/i18n/ja/docusaurus-plugin-content-docs/current/how-to/daily-tasks/organizing-skills.md b/website/i18n/ja/docusaurus-plugin-content-docs/current/how-to/daily-tasks/organizing-skills.md index 23970e7a7..7934940ae 100644 --- a/website/i18n/ja/docusaurus-plugin-content-docs/current/how-to/daily-tasks/organizing-skills.md +++ b/website/i18n/ja/docusaurus-plugin-content-docs/current/how-to/daily-tasks/organizing-skills.md @@ -290,7 +290,7 @@ skillshare sync `sync` の後、Target は自動的に更新されます — 古いフラットなシンボリックリンクはクリーンアップされ、新しいフラット化された名前が作成されます。 :::warning `skillshare install` でインストールした Skill -インストール済みの Skill は `mv` で移動しないでください。`.metadata.json` のインストール記録はパスをキーにしているため、次に `install` または **Install missing** が移動したコピー(同名・インストール後未変更・1 つだけ)を認識して記録を移すまで、記録は古いパスに残ります。それまで `update` と `uninstall` はその Skill を見つけられず、プロジェクトのロックピンと `.skillignore` の行は追従しません。代わりに [`skillshare move`](/docs/reference/commands/move) を使ってください。Skill とインストール記録を一緒に移動するため、再ダウンロードは行われません: +インストール済みの Skill は `mv` で移動しないでください。`.metadata.json` のインストール記録はパスをキーにしているため、次に `sync`、`install` または **Install missing** が移動したコピー(同名・インストール後未変更・1 つだけ)を認識して記録を移すまで、記録は古いパスに残ります。それまで `update` と `uninstall` はその Skill を見つけられず、`.skillignore` の行は追従しません。代わりに [`skillshare move`](/docs/reference/commands/move) を使ってください。Skill とインストール記録を一緒に移動するため、再ダウンロードは行われません: ```bash skillshare move react-best-practices frontend/react diff --git a/website/i18n/ko/docusaurus-plugin-content-docs/current/how-to/daily-tasks/organizing-skills.md b/website/i18n/ko/docusaurus-plugin-content-docs/current/how-to/daily-tasks/organizing-skills.md index 5beafe454..83d094bb8 100644 --- a/website/i18n/ko/docusaurus-plugin-content-docs/current/how-to/daily-tasks/organizing-skills.md +++ b/website/i18n/ko/docusaurus-plugin-content-docs/current/how-to/daily-tasks/organizing-skills.md @@ -290,7 +290,7 @@ skillshare sync `sync` 후에는 Target이 자동으로 업데이트됩니다 — 이전의 평면 심볼릭 링크는 정리되고 새로운 평탄화된 이름이 생성됩니다. :::warning `skillshare install`로 설치한 Skill -설치한 Skill은 `mv`로 옮기지 마세요. `.metadata.json`의 설치 기록은 경로를 키로 사용하므로, 다음 `install` 또는 **Install missing**이 옮긴 복사본(같은 이름, 설치 후 변경 없음, 하나뿐)을 인식해 기록을 옮기기 전까지 기록은 이전 경로에 남습니다. 그동안 `update`와 `uninstall`은 그 Skill을 찾지 못하며, 프로젝트 잠금 핀과 `.skillignore` 줄은 따라오지 않습니다. 대신 [`skillshare move`](/docs/reference/commands/move)를 사용하세요. Skill과 설치 기록을 함께 옮기므로 다시 다운로드하지 않습니다: +설치한 Skill은 `mv`로 옮기지 마세요. `.metadata.json`의 설치 기록은 경로를 키로 사용하므로, 다음 `sync`, `install` 또는 **Install missing**이 옮긴 복사본(같은 이름, 설치 후 변경 없음, 하나뿐)을 인식해 기록을 옮기기 전까지 기록은 이전 경로에 남습니다. 그동안 `update`와 `uninstall`은 그 Skill을 찾지 못하며, `.skillignore` 줄은 따라오지 않습니다. 대신 [`skillshare move`](/docs/reference/commands/move)를 사용하세요. Skill과 설치 기록을 함께 옮기므로 다시 다운로드하지 않습니다: ```bash skillshare move react-best-practices frontend/react diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/how-to/daily-tasks/organizing-skills.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/how-to/daily-tasks/organizing-skills.md index a5b129774..84cf8faed 100644 --- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/how-to/daily-tasks/organizing-skills.md +++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/how-to/daily-tasks/organizing-skills.md @@ -290,7 +290,7 @@ skillshare sync 执行 `sync` 后,Target 会自动更新——旧的扁平符号链接会被清理,并创建新的扁平化名称。 :::warning 通过 `skillshare install` 安装的 Skill -不要用 `mv` 移动已安装的 Skill。`.metadata.json` 里的安装记录以路径为键,记录会留在旧路径,直到下一次 `install` 或 **Install missing** 认出移动后的副本(同名、安装后未修改、只有一份)并把记录移过去;在那之前 `update` 和 `uninstall` 找不到这个 Skill,项目的 lock pin 和 `.skillignore` 行也不会跟着走。请改用 [`skillshare move`](/docs/reference/commands/move)。它会把 Skill 和安装记录一起移动,不会重新下载: +不要用 `mv` 移动已安装的 Skill。`.metadata.json` 里的安装记录以路径为键,记录会留在旧路径,直到下一次 `sync`、`install` 或 **Install missing** 认出移动后的副本(同名、安装后未修改、只有一份)并把记录移过去;在那之前 `update` 和 `uninstall` 找不到这个 Skill,`.skillignore` 行也不会跟着走。请改用 [`skillshare move`](/docs/reference/commands/move)。它会把 Skill 和安装记录一起移动,不会重新下载: ```bash skillshare move react-best-practices frontend/react diff --git a/website/i18n/zh-Hant/docusaurus-plugin-content-docs/current/how-to/daily-tasks/organizing-skills.md b/website/i18n/zh-Hant/docusaurus-plugin-content-docs/current/how-to/daily-tasks/organizing-skills.md index 001f0c687..3731026b1 100644 --- a/website/i18n/zh-Hant/docusaurus-plugin-content-docs/current/how-to/daily-tasks/organizing-skills.md +++ b/website/i18n/zh-Hant/docusaurus-plugin-content-docs/current/how-to/daily-tasks/organizing-skills.md @@ -290,7 +290,7 @@ skillshare sync 執行 `sync` 後,Targets 會自動更新 — 舊的平面 symlink 會被清除,並建立新的攤平後名稱。 :::warning 透過 `skillshare install` 安裝的 Skill -不要用 `mv` 移動已安裝的 Skill。`.metadata.json` 裡的安裝紀錄以路徑為 key,紀錄會留在舊路徑,直到下一次 `install` 或 **Install missing** 認出移動後的副本(同名、安裝後未修改、只有一份)並把紀錄移過去;在那之前 `update` 和 `uninstall` 找不到這個 Skill,專案的 lock pin 和 `.skillignore` 行也不會跟著走。請改用 [`skillshare move`](/docs/reference/commands/move)。它會把 Skill 和安裝紀錄一起移動,不會重新下載: +不要用 `mv` 移動已安裝的 Skill。`.metadata.json` 裡的安裝紀錄以路徑為 key,紀錄會留在舊路徑,直到下一次 `sync`、`install` 或 **Install missing** 認出移動後的副本(同名、安裝後未修改、只有一份)並把紀錄移過去;在那之前 `update` 和 `uninstall` 找不到這個 Skill,`.skillignore` 行也不會跟著走。請改用 [`skillshare move`](/docs/reference/commands/move)。它會把 Skill 和安裝紀錄一起移動,不會重新下載: ```bash skillshare move react-best-practices frontend/react