From b0d87fba281cb27a8bcff17ed2d6c26c8731ec74 Mon Sep 17 00:00:00 2001 From: Willie Date: Sat, 10 Oct 2026 00:00:23 +0800 Subject: [PATCH] feat(sync): make prefixed target naming misconfigurations visible (#503) * feat(sync): make prefixed target naming misconfigurations visible Prefixed naming (#497) works, but several of its failure modes only showed up at sync time or gave advice that cannot be followed: - A collision that only prefixing creates told the user to "rename one in SKILL.md", which a tracked skill cannot do, and never said the prefix caused it. The hint now names the prefixing and points at renaming the other skill or re-tracking the repo with --name. - `target add` silently wrote mode: copy when the inherited naming is prefixed. The CLI now says so. - A target that resolves to prefixed outside copy mode was reported only by sync. status, doctor and target list (plain and JSON) now flag it, and the sync/validation and `--skills=true` errors say how to fix it. - The dim "duplicate skill names (isolated by ...)" line printed on every sync even when nothing was wrong, and before a failing sync. Isolated duplicates are not a problem, so it is dropped; the website docs still showed an outdated form of this output and are corrected in all locales. * fix(status): flag prefixed-outside-copy in the TUI list and status --json Codex review of #503 found two surfaces the new check missed: - The interactive `target list` (the default on a terminal) never read the item's naming error, so a prefixed + merge target looked healthy there. The list row now marks the mode with "!" and the detail panel shows the fix. - `status --json` (global and project) builds its target entries directly, so scripts got no signal. Each target now carries a `warning` string, matching `target list --json`. * docs(troubleshooting): sync no longer prints a message for isolated duplicates The collision troubleshooting tip still said sync shows an info message when filters isolate duplicate skill names. That line was dropped, so the tip now says sync prints nothing about them. Codex review of #503 flagged the stale English page and its four translations. * fix(config): point managed-project naming errors at the project settings The "set mode: copy on the target" hint is wrong for a target a global `projects:` entry expands into: it cannot be edited with `target` or under `targets:`, and the mode lives in the project's skills settings. The hint now depends on whether the target belongs to a managed project (Codex review of #503). The naming/mode check becomes a TargetConfig method so status, doctor and target list share it, which also lets the hint see the project root. Along the way: doctor reuses it, the TUI list renders the mode once, and reportTargetAdded takes a flag instead of comparing a mode string. * fix(config): hint the project settings for managed-project naming errors ProjectNamingError (the config-load check for a global `projects:` entry) still returned the bare naming error, so a project that inherits prefixed with a non-copy mode got no fix. It now names the project's skills settings, like the expanded targets do. The built-in skill's sync reference also mentions that status, doctor and target list flag the misconfiguration before sync. Found by the second /code-review pass on #503. * fix(sync): detect prefix collisions from the colliding paths reportCollisions decided a collision came from prefixing when its name was not also a duplicate in the source. A tracked skill that joined two ordinary skills already sharing the name was therefore sent to the "rename one in SKILL.md" hint, which a tracked skill cannot follow (Codex review of #503). A collision on a prefixed target that includes a tracked path now gets the tracked-skill hint, whatever else shares the name. The wording no longer claims prefixing renamed the skill, since a name that already starts with the repo name is unchanged. * fix(sync): use discovered repo metadata for the tracked-skill hint The collision hint treated any path segment starting with "_" as a tracked repo, so an ordinary skill under a folder such as org/_drafts (no .git) was told it could not be renamed and to re-track a repo that does not exist. It now uses DiscoveredSkill.IsInRepo, the same signal prefixed naming uses. The prefixed docs also gain the fix for a target a global `projects:` entry expands into (projects..skills.mode: copy), since `target` cannot edit those. Both from Codex review of #503. * fix(sync): keep both collision hints when targets disagree The same name can clash on a prefixed target with a tracked skill and on another target between ordinary skills only. The prefixed flag was OR-ed across targets, so the second case lost its rename/filter hint. Track both kinds separately while grouping, and print each hint that applies (Codex review of #503). * fix(sync): keep the rename hint inside a mixed collision group When a tracked skill and two ordinary skills share a prefixed name, re-tracking the repo fixes only the tracked one; the ordinary pair still clashes and is excluded. The group now also shows the rename/filter hint when at least two of its participants are not tracked (Codex review of #503). * fix(sync): offer filters in the tracked-skill collision hint Two tracked skills of the same repo with the same name collide after prefixing, and neither renaming a tracked skill nor re-tracking the repo separates them. The hint now also names include/exclude filters, so every collision on a prefixed target has an actionable remedy (Codex review of #503). * docs(sync-modes): limit the target list claim to targets under targets target list builds from the config without project expansion, so it cannot flag a target a `projects:` entry expands into; status and doctor can. The prefixed paragraph and the built-in skill reference said all three flag it (Codex review of #503). --- cmd/skillshare/doctor.go | 10 ++ cmd/skillshare/status.go | 14 ++ cmd/skillshare/status_project.go | 4 + cmd/skillshare/sync.go | 149 +++++++++--------- cmd/skillshare/target.go | 13 +- cmd/skillshare/target_agents.go | 6 + cmd/skillshare/target_agents_test.go | 12 ++ cmd/skillshare/target_list_tui.go | 5 + cmd/skillshare/target_list_tui_item.go | 8 +- cmd/skillshare/target_project.go | 5 +- cmd/skillshare/target_skills.go | 4 +- internal/config/config.go | 25 +++ internal/config/config_validate.go | 4 +- internal/config/config_validate_test.go | 43 ++++- internal/config/projects.go | 2 +- skills/skillshare/references/sync.md | 2 +- tests/integration/exclude_filter_test.go | 4 +- .../sync_target_naming_prefixed_test.go | 94 ++++++++++- tests/integration/target_skills_off_test.go | 1 + .../how-to/sharing/organization-sharing.md | 15 +- website/docs/reference/commands/doctor.md | 1 + website/docs/reference/commands/status.md | 2 + website/docs/reference/commands/target.md | 2 + website/docs/troubleshooting/common-errors.md | 2 +- website/docs/understand/sync-modes.md | 4 +- .../docs/understand/tracked-repositories.md | 17 +- .../how-to/sharing/organization-sharing.md | 15 +- .../current/reference/commands/doctor.md | 1 + .../current/reference/commands/status.md | 2 + .../current/reference/commands/target.md | 2 + .../current/troubleshooting/common-errors.md | 2 +- .../current/understand/sync-modes.md | 4 +- .../understand/tracked-repositories.md | 17 +- .../how-to/sharing/organization-sharing.md | 15 +- .../current/reference/commands/doctor.md | 1 + .../current/reference/commands/status.md | 2 + .../current/reference/commands/target.md | 2 + .../current/troubleshooting/common-errors.md | 2 +- .../current/understand/sync-modes.md | 4 +- .../understand/tracked-repositories.md | 17 +- .../how-to/sharing/organization-sharing.md | 15 +- .../current/reference/commands/doctor.md | 1 + .../current/reference/commands/status.md | 2 + .../current/reference/commands/target.md | 2 + .../current/troubleshooting/common-errors.md | 2 +- .../current/understand/sync-modes.md | 4 +- .../understand/tracked-repositories.md | 17 +- .../how-to/sharing/organization-sharing.md | 15 +- .../current/reference/commands/doctor.md | 1 + .../current/reference/commands/status.md | 2 + .../current/reference/commands/target.md | 2 + .../current/troubleshooting/common-errors.md | 2 +- .../current/understand/sync-modes.md | 4 +- .../understand/tracked-repositories.md | 17 +- 54 files changed, 415 insertions(+), 205 deletions(-) diff --git a/cmd/skillshare/doctor.go b/cmd/skillshare/doctor.go index 7bd7a2588..a4cde857c 100644 --- a/cmd/skillshare/doctor.go +++ b/cmd/skillshare/doctor.go @@ -582,6 +582,16 @@ func checkTargets(cfg *config.Config, result *doctorResult, isProject bool) map[ hasError = true continue } + if err := target.NamingModeConfigError(mode); err != nil { + row(ui.MarkFail, "skills", err.Error()+ui.DimText(" · "+mode)) + result.addError() + details = append(details, fmt.Sprintf("%s: %v", name, err)) + hasError = true + if agentsExist { + checkAgentTargetInline(name, target, builtinAgents, discoveredAgents, result, row) + } + continue + } if mode == "symlink" && (len(sc.Include) > 0 || len(sc.Exclude) > 0) { row(ui.MarkWarn, "skills", "include/exclude ignored in symlink mode") result.addWarning() diff --git a/cmd/skillshare/status.go b/cmd/skillshare/status.go index bd0d10a39..b263336a3 100644 --- a/cmd/skillshare/status.go +++ b/cmd/skillshare/status.go @@ -67,6 +67,8 @@ type statusJSONTarget struct { Exclude []string `json:"exclude"` // SkillsEnabled is false for a target with skills switched off. SkillsEnabled bool `json:"skills_enabled"` + // Warning says why sync will reject the target, with the fix. + Warning string `json:"warning,omitempty"` } type statusJSONAudit struct { @@ -175,6 +177,7 @@ func cmdStatus(args []string) error { Exclude: sc.Exclude, SkillsEnabled: sc.IsEnabled(), + Warning: namingWarning(target, tMode), }) } @@ -325,6 +328,9 @@ func printTargetsStatus(cfg *config.Config, discovered []sync.DiscoveredSkill) e sc := target.SkillsConfig() mode := getTargetMode(sc.Mode, cfg.Mode) res := getTargetStatusDetail(target, cfg.EffectiveSkillsSource(), mode) + if err := target.NamingModeConfigError(mode); err != nil { + warnings = append(warnings, name+": "+err.Error()) + } // A target with skills off expects nothing, so it has no drift. expected := 0 @@ -361,6 +367,14 @@ func printTargetsStatus(cfg *config.Config, discovered []sync.DiscoveredSkill) e return nil } +// namingWarning is the naming and mode error of a target that syncs skills, as text. +func namingWarning(target config.TargetConfig, mode string) string { + if err := target.NamingModeConfigError(mode); err != nil { + return err.Error() + } + return "" +} + func getTargetMode(targetMode, globalMode string) string { if targetMode != "" { return targetMode diff --git a/cmd/skillshare/status_project.go b/cmd/skillshare/status_project.go index a5f226fb8..1ec9ba7b6 100644 --- a/cmd/skillshare/status_project.go +++ b/cmd/skillshare/status_project.go @@ -103,6 +103,7 @@ func cmdStatusProjectJSON(root string) error { Exclude: sc.Exclude, SkillsEnabled: sc.IsEnabled(), + Warning: namingWarning(target, mode), }) } @@ -203,6 +204,9 @@ func printProjectTargetsStatus(runtime *projectRuntime, discovered []sync.Discov mode = "merge" } res := getTargetStatusDetail(target, runtime.sourcePath, mode) + if err := target.NamingModeConfigError(mode); err != nil { + warnings = append(warnings, entry.Name+": "+err.Error()) + } // A target with skills off expects nothing, so it has no drift. expected := 0 diff --git a/cmd/skillshare/sync.go b/cmd/skillshare/sync.go index f92311009..084ce432e 100644 --- a/cmd/skillshare/sync.go +++ b/cmd/skillshare/sync.go @@ -745,80 +745,87 @@ func backupTargetsBeforeSync(cfg *config.Config) { } func reportCollisions(skills []sync.DiscoveredSkill, targets map[string]config.TargetConfig) { - global, perTarget := sync.CheckNameCollisionsForTargets(skills, targets) - // A target's naming can make distinct names collide (prefixed _a/b-c vs a-b-c). - if len(global) == 0 && len(perTarget) == 0 { + _, perTarget := sync.CheckNameCollisionsForTargets(skills, targets) + // Duplicates that filters or naming keep apart are not a problem, so only collisions + // that reach a target are reported. + if len(perTarget) == 0 { return } - - if len(perTarget) > 0 { - // Deduplicate collisions across targets: group by skill name, collect affected targets - type collisionInfo struct { - Paths []string - Targets []string - } - deduped := make(map[string]*collisionInfo) - var orderedNames []string - var targetNames []string - seenTargets := make(map[string]bool) - - for _, tc := range perTarget { - if !seenTargets[tc.TargetName] { - seenTargets[tc.TargetName] = true - targetNames = append(targetNames, tc.TargetName) - } - for _, c := range tc.Collisions { - if info, ok := deduped[c.Name]; ok { - info.Targets = append(info.Targets, tc.TargetName) - } else { - deduped[c.Name] = &collisionInfo{ - Paths: c.Paths, - Targets: []string{tc.TargetName}, - } - orderedNames = append(orderedNames, c.Name) - } - } - } - - // Summary line - if len(targetNames) == len(seenTargets) && len(seenTargets) > 1 { - ui.Warning("%d duplicate skill names affect %d targets (%s)", - len(deduped), len(targetNames), strings.Join(targetNames, ", ")) - } else { - ui.Warning("%d duplicate skill names detected", len(deduped)) - } - - // One entry per collision name - for _, name := range orderedNames { - info := deduped[name] - // Show only parent directories for brevity (e.g., "skillshare/, skillshare2/") - dirs := make([]string, 0, len(info.Paths)) - for _, p := range info.Paths { - parts := strings.SplitN(p, "/", 2) - if len(parts) > 0 { - dirs = append(dirs, parts[0]+"/") - } - } - ui.Note(fmt.Sprintf("%-30s %s", name, strings.Join(dirs, " vs "))) - } - ui.Note("Rename one in SKILL.md or adjust include/exclude filters") - fmt.Println() - } else { - // Global collision exists but filters or target naming isolate them — show first few names - const maxShow = 5 - names := make([]string, 0, maxShow) - for i, c := range global { - if i >= maxShow { - break - } - names = append(names, c.Name) - } - line := fmt.Sprintf("%d duplicate skill names (isolated by target filters or naming): %s", len(global), strings.Join(names, ", ")) - if len(global) > maxShow { - line += fmt.Sprintf(", ... and %d more", len(global)-maxShow) - } - fmt.Println(theme.Dim().Render(line)) + tracked := make(map[string]bool) + for _, skill := range skills { + tracked[skill.RelPath] = skill.IsInRepo } + + // Deduplicate collisions across targets: group by skill name + type collisionInfo struct { + Paths []string + // Prefixed is set when a tracked skill collides on a prefixed target: its name + // comes from its repo, so SKILL.md is not where to change it. Other is set when + // some target's collision has no such skill. A name can have both across targets. + Prefixed, Other bool + } + deduped := make(map[string]*collisionInfo) + var orderedNames []string + var targetNames []string + seenTargets := make(map[string]bool) + + for _, tc := range perTarget { + if !seenTargets[tc.TargetName] { + seenTargets[tc.TargetName] = true + targetNames = append(targetNames, tc.TargetName) + } + target := targets[tc.TargetName] + targetPrefixed := config.EffectiveTargetNaming(target.SkillsConfig().TargetNaming) == "prefixed" + for _, c := range tc.Collisions { + info, ok := deduped[c.Name] + if !ok { + info = &collisionInfo{Paths: c.Paths} + deduped[c.Name] = info + orderedNames = append(orderedNames, c.Name) + } + trackedPaths := 0 + for _, p := range c.Paths { + if tracked[p] { + trackedPaths++ + } + } + trackedClash := targetPrefixed && trackedPaths > 0 + // Re-tracking fixes the tracked skill only: ordinary skills still clash if two remain. + info.Prefixed = info.Prefixed || trackedClash + info.Other = info.Other || !trackedClash || len(c.Paths)-trackedPaths >= 2 + } + } + + // Summary line + if len(targetNames) == len(seenTargets) && len(seenTargets) > 1 { + ui.Warning("%d duplicate skill names affect %d targets (%s)", + len(deduped), len(targetNames), strings.Join(targetNames, ", ")) + } else { + ui.Warning("%d duplicate skill names detected", len(deduped)) + } + + // One entry per collision name + var anyPrefixed, anyOther bool + for _, name := range orderedNames { + info := deduped[name] + // Show only parent directories for brevity (e.g., "skillshare/, skillshare2/") + dirs := make([]string, 0, len(info.Paths)) + for _, p := range info.Paths { + parts := strings.SplitN(p, "/", 2) + if len(parts) > 0 { + dirs = append(dirs, parts[0]+"/") + } + } + ui.Note(fmt.Sprintf("%-30s %s", name, strings.Join(dirs, " vs "))) + anyPrefixed, anyOther = anyPrefixed || info.Prefixed, anyOther || info.Other + } + if anyPrefixed { + ui.Note("A tracked skill cannot be renamed in SKILL.md: rename the other skill, re-track the repo with --name (prefixed naming puts the repo name in front), or adjust include/exclude filters") + } + if anyOther { + ui.Note("Rename one in SKILL.md or adjust include/exclude filters") + } + fmt.Println() } func printSyncHelp() { diff --git a/cmd/skillshare/target.go b/cmd/skillshare/target.go index 329221d65..1e99c24c1 100644 --- a/cmd/skillshare/target.go +++ b/cmd/skillshare/target.go @@ -228,11 +228,16 @@ func targetAdd(args []string) error { return err } - reportTargetAdded(name, path, noSkills) + reportTargetAdded(name, path, noSkills, skills.Mode != "") return nil } -func reportTargetAdded(name, path string, noSkills bool) { +// reportTargetAdded prints the result of target add. copyForced is set when the target +// was given copy mode because the naming it inherits needs it. +func reportTargetAdded(name, path string, noSkills, copyForced bool) { + if copyForced { + ui.Info("Target naming \"prefixed\" needs copy mode, so %s was added with mode copy", name) + } if noSkills { ui.Done(ui.MarkOK, fmt.Sprintf("Added target %s -> %s (skills off)", name, shortenPath(path)), 0) ui.Next(fmt.Sprintf("skillshare target %s --skills=true", name), "sync skills to this target too") @@ -276,7 +281,8 @@ func targetAddAgentConfigDir(name string, args []string, noSkills bool) error { if err := cfg.Save(); err != nil { return err } - reportTargetAdded(name, path, noSkills) + target := cfg.Targets[name] + reportTargetAdded(name, path, noSkills, target.SkillsConfig().Mode != "") return nil } @@ -577,6 +583,7 @@ type targetListJSONItem struct { AgentLocalCount *int `json:"agentLocalCount,omitempty"` AgentExpectedCount *int `json:"agentExpectedCount,omitempty"` SkillsEnabled bool `json:"skillsEnabled"` + Warning string `json:"warning,omitempty"` } func targetList(jsonOutput bool) error { diff --git a/cmd/skillshare/target_agents.go b/cmd/skillshare/target_agents.go index 9fd9d416d..48be240ad 100644 --- a/cmd/skillshare/target_agents.go +++ b/cmd/skillshare/target_agents.go @@ -40,6 +40,9 @@ func newTargetListJSONItem(item targetTUIItem) targetListJSONItem { SkillsEnabled: sc.IsEnabled(), } + if item.namingErr != nil { + jsonItem.Warning = item.namingErr.Error() + } applyTargetListAgentSummary(&jsonItem, item.agentSummary) return jsonItem } @@ -146,6 +149,9 @@ func printTargetListPlain(items []targetTUIItem) { detail = sync.EffectiveMode(sc.Mode) + " · " + config.EffectiveTargetNaming(sc.TargetNaming) + " · " + item.skillSyncText } ui.Row(ui.MarkNone, "Skills", shortenPath(displayPath)+" "+ui.DimText(detail), width) + if item.namingErr != nil { + ui.Row(ui.MarkWarn, "", item.namingErr.Error(), width) + } if f := filterSummary(sc.Include, sc.Exclude); sc.IsEnabled() && f != "" { ui.Row(ui.MarkNone, "", ui.DimText(f), width) } diff --git a/cmd/skillshare/target_agents_test.go b/cmd/skillshare/target_agents_test.go index aabba0e58..9ffd381d1 100644 --- a/cmd/skillshare/target_agents_test.go +++ b/cmd/skillshare/target_agents_test.go @@ -322,6 +322,18 @@ func TestRenderTargetDetail_AgentSection(t *testing.T) { want: []string{"Agents", ".claude/agents", "5/5 linked (directory symlink)", "ignored in symlink mode"}, notContains: []string{"team-*", "draft-*"}, }, + { + name: "naming the mode cannot honour shows the fix", + item: targetTUIItem{ + name: "claude", + skillSync: "merged (7 shared, 0 local)", + target: config.TargetConfig{ + Skills: &config.ResourceTargetConfig{Path: "/tmp/claude/skills", Mode: "merge", TargetNaming: "prefixed"}, + }, + namingErr: config.TargetNamingModeConfigError("prefixed", "merge", ""), + }, + want: []string{"set mode: copy on the target"}, + }, { name: "unsupported target omits agents section", item: targetTUIItem{ diff --git a/cmd/skillshare/target_list_tui.go b/cmd/skillshare/target_list_tui.go index 8bdf55ff0..4a7a5d239 100644 --- a/cmd/skillshare/target_list_tui.go +++ b/cmd/skillshare/target_list_tui.go @@ -197,6 +197,7 @@ func buildTargetTUIItems(isProject bool, cwd string) ([]targetTUIItem, error) { skillSyncText: skillSyncText, agentConfig: config.ResourceTargetConfig{Mode: agentSummaryMode(agentSummary), Include: agentSummaryInclude(agentSummary), Exclude: agentSummaryExclude(agentSummary)}, agentSummary: agentSummary, + namingErr: resolved.NamingModeConfigError(""), }) } } else { @@ -222,6 +223,7 @@ func buildTargetTUIItems(isProject bool, cwd string) ([]targetTUIItem, error) { skillSyncText: skillSyncText, agentConfig: config.ResourceTargetConfig{Mode: agentSummaryMode(agentSummary), Include: agentSummaryInclude(agentSummary), Exclude: agentSummaryExclude(agentSummary)}, agentSummary: agentSummary, + namingErr: t.NamingModeConfigError(cfg.Mode), }) } } @@ -973,6 +975,9 @@ func (m targetListTUIModel) renderTargetDetail(item targetTUIItem) string { if sc.IsEnabled() { row("Mode", sync.EffectiveMode(sc.Mode)) row("Naming", config.EffectiveTargetNaming(sc.TargetNaming)) + if item.namingErr != nil { + row("Warning", theme.Warning().Render(item.namingErr.Error())) + } } row("Sync", item.skillSync) // Filters are kept for turning skills back on but do nothing while off. diff --git a/cmd/skillshare/target_list_tui_item.go b/cmd/skillshare/target_list_tui_item.go index df5b54643..4d652f4fa 100644 --- a/cmd/skillshare/target_list_tui_item.go +++ b/cmd/skillshare/target_list_tui_item.go @@ -22,6 +22,8 @@ type targetTUIItem struct { skillSyncText string agentConfig config.ResourceTargetConfig agentSummary *targetsummary.AgentSummary + // namingErr is why sync will fail for this target's naming and mode, with the fix. + namingErr error } func (i targetTUIItem) FilterValue() string { return i.name } @@ -44,5 +46,9 @@ func (targetListDelegate) Render(w io.Writer, m list.Model, index int, item list if !ti.target.SkillsConfig().IsEnabled() { mode = "skills off" } - renderPrefixRow(w, alignRow(ti.name, theme.Dim().Render(mode), m.Width()-rowIndent), m.Width(), index == m.Index()) + modeStyle := theme.Dim() + if ti.namingErr != nil { + modeStyle, mode = theme.Warning(), "! "+mode + } + renderPrefixRow(w, alignRow(ti.name, modeStyle.Render(mode), m.Width()-rowIndent), m.Width(), index == m.Index()) } diff --git a/cmd/skillshare/target_project.go b/cmd/skillshare/target_project.go index e7b1d1348..09500797c 100644 --- a/cmd/skillshare/target_project.go +++ b/cmd/skillshare/target_project.go @@ -99,7 +99,8 @@ func targetAddProject(args []string, root string) error { if noSkills { entry.EnsureSkills().SetEnabled(false) } - if mode := config.NewTargetSkillsMode(cfg.TargetNaming, ""); mode != "" { + mode := config.NewTargetSkillsMode(cfg.TargetNaming, "") + if mode != "" { entry.EnsureSkills().Mode = mode // a project target defaults to merge } @@ -114,7 +115,7 @@ func targetAddProject(args []string, root string) error { } } - reportTargetAdded(name, path, noSkills) + reportTargetAdded(name, path, noSkills, mode != "") return nil } diff --git a/cmd/skillshare/target_skills.go b/cmd/skillshare/target_skills.go index e1497d29f..d6381e593 100644 --- a/cmd/skillshare/target_skills.go +++ b/cmd/skillshare/target_skills.go @@ -34,7 +34,7 @@ func setTargetSkillsGlobal(cfg *config.Config, name string, target config.Target // An off target may keep a naming its mode cannot sync. sc := target.SkillsConfig() if err := config.TargetNamingModeError(sc.TargetNaming, cmp.Or(sc.Mode, cfg.Mode)); err != nil { - return err + return fmt.Errorf("%w; set --mode copy first", err) } } res, err := switchTargetSkills(name, enabled, dryRun, func() error { @@ -55,7 +55,7 @@ func setTargetSkillsProject(cfg *config.ProjectConfig, idx int, enabled, dryRun if enabled { sc := cfg.Targets[idx].SkillsConfig() if err := config.TargetNamingModeError(sc.TargetNaming, sc.Mode); err != nil { - return err + return fmt.Errorf("%w; set --mode copy first", err) } } res, err := switchTargetSkills(name, enabled, dryRun, func() error { diff --git a/internal/config/config.go b/internal/config/config.go index b79a0e806..e8fa8974c 100644 --- a/internal/config/config.go +++ b/internal/config/config.go @@ -1,6 +1,7 @@ package config import ( + "cmp" "fmt" "os" "path/filepath" @@ -62,6 +63,30 @@ func TargetNamingModeError(naming, mode string) error { return fmt.Errorf("target naming %q requires copy mode, but the target syncs in %q mode", "prefixed", mode) } +// TargetNamingModeConfigError is TargetNamingModeError for a target as written in a +// config file, with the fix. A managed project's target has projectRoot set: it cannot +// be edited as a target, so its fix is in the project's settings. +func TargetNamingModeConfigError(naming, mode, projectRoot string) error { + err := TargetNamingModeError(naming, mode) + if err == nil { + return nil + } + if projectRoot != "" { + return fmt.Errorf("%w; set mode: copy in the project's skills settings", err) + } + return fmt.Errorf("%w; set mode: copy on the target", err) +} + +// NamingModeConfigError is TargetNamingModeConfigError for a target that syncs skills, +// nil when skills are off. defaultMode is the mode a target without its own inherits. +func (tc TargetConfig) NamingModeConfigError(defaultMode string) error { + sc := tc.SkillsConfig() + if !sc.IsEnabled() { + return nil + } + return TargetNamingModeConfigError(sc.TargetNaming, cmp.Or(sc.Mode, defaultMode), tc.projectRoot) +} + // NewTargetSkillsMode is the skills mode a new target is written with: copy when it // would otherwise inherit a naming its inherited mode cannot honour, else empty (inherit). func NewTargetSkillsMode(naming, mode string) string { diff --git a/internal/config/config_validate.go b/internal/config/config_validate.go index 1c4ae8d05..f08dade16 100644 --- a/internal/config/config_validate.go +++ b/internal/config/config_validate.go @@ -98,7 +98,7 @@ func validateGlobalTarget(name string, target TargetConfig, globalMode, globalNa } naming, mode := cmp.Or(sc.TargetNaming, globalNaming), cmp.Or(sc.Mode, globalMode) // Skills off syncs no skill, and the target's agents must still sync. - if err := TargetNamingModeError(naming, mode); err != nil && sc.IsEnabled() { + if err := TargetNamingModeConfigError(naming, mode, target.ProjectRoot()); err != nil && sc.IsEnabled() { problems = append(problems, err.Error()) } if sc.Path == "" { @@ -195,7 +195,7 @@ func validateProjectTarget(entry ProjectTargetEntry, projectRoot, sourcePath, ag if !IsValidTargetNaming(sc.TargetNaming) { return append(problems, fmt.Sprintf("invalid target naming %q (valid: %s)", sc.TargetNaming, strings.Join(ValidTargetNamings, ", "))) } - if err := TargetNamingModeError(sc.TargetNaming, sc.Mode); err != nil && sc.IsEnabled() { + if err := TargetNamingModeConfigError(sc.TargetNaming, sc.Mode, ""); err != nil && sc.IsEnabled() { problems = append(problems, err.Error()) } diff --git a/internal/config/config_validate_test.go b/internal/config/config_validate_test.go index 4f8d42125..675ad8ae2 100644 --- a/internal/config/config_validate_test.go +++ b/internal/config/config_validate_test.go @@ -541,7 +541,7 @@ func TestValidateConfigForSync_PrefixedNamingRequiresCopyMode(t *testing.T) { }, } _, invalid, err := ValidateConfigForSync(cfg) - if err != nil || len(invalid) != 1 || invalid["merge"] == nil || !strings.Contains(invalid["merge"].Error(), `target naming "prefixed" requires copy mode`) { + if err != nil || len(invalid) != 1 || invalid["merge"] == nil || !strings.Contains(invalid["merge"].Error(), `target naming "prefixed" requires copy mode`) || !strings.Contains(invalid["merge"].Error(), "set mode: copy on the target") { t.Fatalf("err = %v, invalid = %v; want only merge invalid", err, invalid) } } @@ -572,9 +572,13 @@ func TestValidateConfig_ProjectPrefixedNamingRequiresCopyMode(t *testing.T) { cfg := &Config{Source: t.TempDir(), Mode: "merge", Projects: map[string]ManagedProject{ "~/work/app": {Skills: &ResourceTargetConfig{TargetNaming: "prefixed"}}, }} - if _, err := ValidateConfig(cfg); err == nil || !strings.Contains(err.Error(), `projects: ~/work/app: target naming "prefixed" requires copy mode`) { + _, err := ValidateConfig(cfg) + if err == nil || !strings.Contains(err.Error(), `projects: ~/work/app: target naming "prefixed" requires copy mode`) { t.Fatalf("err = %v, want the project's prefixed naming rejected", err) } + if !strings.Contains(err.Error(), "set mode: copy in the project's skills settings") { + t.Fatalf("err = %v, want the project settings hint", err) + } } func TestValidateConfigForSync_SkillsOffSkipsNamingModeCheck(t *testing.T) { @@ -599,3 +603,38 @@ func TestValidateConfigForSync_SkillsOffSkipsNamingModeCheck(t *testing.T) { t.Fatalf("managed project: %v", err) } } + +func TestTargetConfig_NamingModeConfigError(t *testing.T) { + off := false + for _, tc := range []struct { + name string + tc TargetConfig + mode string + fix string // empty when no error is expected + }{ + {"prefixed inheriting merge", TargetConfig{Skills: &ResourceTargetConfig{TargetNaming: "prefixed"}}, "merge", "set mode: copy on the target"}, + {"prefixed inheriting the default", TargetConfig{Skills: &ResourceTargetConfig{TargetNaming: "prefixed"}}, "", "set mode: copy on the target"}, + {"own copy mode wins", TargetConfig{Skills: &ResourceTargetConfig{TargetNaming: "prefixed", Mode: "copy"}}, "merge", ""}, + {"skills off", TargetConfig{Skills: &ResourceTargetConfig{TargetNaming: "prefixed", Enabled: &off}}, "merge", ""}, + // A managed project's target cannot be edited as a target; its project settings hold the mode. + {"managed project target", TargetConfig{Skills: &ResourceTargetConfig{TargetNaming: "prefixed"}, projectRoot: "/work/app"}, "merge", "set mode: copy in the project's skills settings"}, + } { + err := tc.tc.NamingModeConfigError(tc.mode) + switch { + case tc.fix == "" && err != nil: + t.Errorf("%s: unexpected error %v", tc.name, err) + case tc.fix != "" && (err == nil || !strings.Contains(err.Error(), tc.fix)): + t.Errorf("%s: error = %v, want fix %q", tc.name, err, tc.fix) + } + } +} + +func TestValidateConfigForSync_ManagedProjectPrefixedHintPointsAtProject(t *testing.T) { + problems := validateGlobalTarget("app@claude", TargetConfig{ + Skills: &ResourceTargetConfig{Path: filepath.Join(t.TempDir(), "skills")}, + projectRoot: "/work/app", + }, "merge", "prefixed") + if len(problems) != 1 || !strings.Contains(problems[0], "in the project's skills settings") { + t.Fatalf("problems = %v, want the project settings hint", problems) + } +} diff --git a/internal/config/projects.go b/internal/config/projects.go index 78e2d8fbb..4ee9639c4 100644 --- a/internal/config/projects.go +++ b/internal/config/projects.go @@ -227,7 +227,7 @@ func (c *Config) ValidateProjects(projects map[string]ManagedProject) error { func (c *Config) ProjectNamingError(projects map[string]ManagedProject, mode string) error { for _, root := range slices.Sorted(maps.Keys(projects)) { if sk := projects[root].Skills; sk != nil && sk.IsEnabled() { - if err := TargetNamingModeError(cmp.Or(sk.TargetNaming, c.TargetNaming), cmp.Or(sk.Mode, mode)); err != nil { + if err := TargetNamingModeConfigError(cmp.Or(sk.TargetNaming, c.TargetNaming), cmp.Or(sk.Mode, mode), root); err != nil { return fmt.Errorf("projects: %s: %w", root, err) } } diff --git a/skills/skillshare/references/sync.md b/skills/skillshare/references/sync.md index f7c4e9d35..f31bd9058 100644 --- a/skills/skillshare/references/sync.md +++ b/skills/skillshare/references/sync.md @@ -22,7 +22,7 @@ skillshare sync --json # JSON output skillshare sync -g # Force global mode ``` -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) 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 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/tests/integration/exclude_filter_test.go b/tests/integration/exclude_filter_test.go index b5a8697cc..3235067de 100644 --- a/tests/integration/exclude_filter_test.go +++ b/tests/integration/exclude_filter_test.go @@ -297,8 +297,8 @@ targets: // Should NOT show "Name conflicts detected" (warning-level header) result.AssertOutputNotContains(t, "Name conflicts detected") - // Should show info-level message about isolated duplicates - result.AssertAnyOutputContains(t, "isolated by target filters") + // Isolated duplicates are not a problem, so sync stays quiet about them + result.AssertOutputNotContains(t, "duplicate skill names") // Verify correct skills landed on correct targets if !sb.IsSymlink(filepath.Join(codexTarget, "codex-plan")) { diff --git a/tests/integration/sync_target_naming_prefixed_test.go b/tests/integration/sync_target_naming_prefixed_test.go index 4c6fc593f..ecd5fc687 100644 --- a/tests/integration/sync_target_naming_prefixed_test.go +++ b/tests/integration/sync_target_naming_prefixed_test.go @@ -101,11 +101,25 @@ func TestSync_TargetNamingPrefixed_RejectedOutsideCopyMode(t *testing.T) { result := sb.RunCLI("sync") result.AssertFailure(t) result.AssertAnyOutputContains(t, `target naming "prefixed" requires copy mode`) + result.AssertAnyOutputContains(t, "set mode: copy on the target") if entries := sb.ListDir(targetPath); len(entries) != 0 { t.Fatalf("merge target was written: %v", entries) } } +func TestPrefixedNamingOutsideCopyMode_IsFlaggedBeforeSync(t *testing.T) { + sb := testutil.NewSandbox(t) + defer sb.Cleanup() + targetPath := prefixedFixture(t, sb) + writeNamingConfig(sb, targetPath, "prefixed", "merge") + + for _, args := range [][]string{{"status"}, {"status", "--json"}, {"doctor"}, {"target", "list", "--no-tui"}, {"target", "list", "--json"}} { + t.Run(strings.Join(args, " "), func(t *testing.T) { + sb.RunCLI(args...).AssertAnyOutputContains(t, "set mode: copy on the target") + }) + } +} + func TestSync_TargetNamingPrefixed_SwitchesRenameInPlace(t *testing.T) { steps := []struct { naming string @@ -297,7 +311,9 @@ func TestTargetAdd_GlobalPrefixedNamingUnderMergeUsesCopyMode(t *testing.T) { writeNamingConfig(sb, targetPath, "prefixed", "copy") sb.WriteConfig(strings.Replace(sb.ReadFile(sb.ConfigPath), "targets:", "mode: merge\ntargets:", 1)) - sb.RunCLI("target", "add", "cursor", sb.CreateTarget("cursor")).AssertSuccess(t) + added := sb.RunCLI("target", "add", "cursor", sb.CreateTarget("cursor")) + added.AssertSuccess(t) + added.AssertOutputContains(t, "mode copy") sb.RunCLI("sync").AssertOutputNotContains(t, "requires copy mode") } @@ -335,6 +351,78 @@ func TestSync_TargetNamingPrefixed_ReportsCollisionsOnlyThePrefixCreates(t *test result.AssertSuccess(t) result.AssertOutputContains(t, "duplicate skill names") result.AssertOutputContains(t, "_a/ vs a-b-c/") + // The tracked skill cannot be renamed in SKILL.md; say what prefixing did and what to change. + result.AssertOutputContains(t, "A tracked skill cannot be renamed in SKILL.md") + result.AssertOutputContains(t, "--name") + result.AssertOutputNotContains(t, "Rename one in SKILL.md") +} + +func TestSync_TargetNamingPrefixed_CollisionHintStaysWhenSourceAlreadyHasDuplicates(t *testing.T) { + sb := testutil.NewSandbox(t) + defer sb.Cleanup() + // Two ordinary skills already share a name; the tracked skill joins them once prefixed. + sb.CreateNestedSkill("_alpha/prototype", map[string]string{"SKILL.md": "---\nname: prototype\n---\n# A"}) + sb.CreateSkill("alpha-prototype", map[string]string{"SKILL.md": "---\nname: alpha-prototype\n---\n# One"}) + sb.CreateNestedSkill("team/alpha-prototype", map[string]string{"SKILL.md": "---\nname: alpha-prototype\n---\n# Two"}) + targetPath := sb.CreateTarget("claude") + writeNamingConfig(sb, targetPath, "prefixed", "copy") + + result := sb.RunCLI("sync") + result.AssertOutputContains(t, "A tracked skill cannot be renamed in SKILL.md") + result.AssertOutputContains(t, "--name") + // Re-tracking leaves the two ordinary skills clashing, so their remedy stays too. + result.AssertOutputContains(t, "Rename one in SKILL.md") +} + +func TestSync_TargetNamingPrefixed_CollisionPrintsBothHintsAcrossTargets(t *testing.T) { + sb := testutil.NewSandbox(t) + defer sb.Cleanup() + // On the prefixed target the tracked skill joins the clash; on the standard one only the ordinary pair clashes. + sb.CreateNestedSkill("_alpha/prototype", map[string]string{"SKILL.md": "---\nname: prototype\n---\n# A"}) + sb.CreateSkill("alpha-prototype", map[string]string{"SKILL.md": "---\nname: alpha-prototype\n---\n# One"}) + sb.CreateNestedSkill("team/alpha-prototype", map[string]string{"SKILL.md": "---\nname: alpha-prototype\n---\n# Two"}) + sb.WriteConfig(`source: ` + sb.SourcePath + ` +targets: + claude: + skills: + path: ` + sb.CreateTarget("claude") + ` + mode: copy + target_naming: prefixed + codex: + skills: + path: ` + sb.CreateTarget("codex") + ` + mode: copy + target_naming: standard +`) + + result := sb.RunCLI("sync") + result.AssertOutputContains(t, "A tracked skill cannot be renamed in SKILL.md") + result.AssertOutputContains(t, "Rename one in SKILL.md") +} + +func TestSync_TargetNamingPrefixed_SameRepoDuplicateStillOffersFilters(t *testing.T) { + sb := testutil.NewSandbox(t) + defer sb.Cleanup() + // Re-tracking cannot separate two skills of one repo, so filters must be offered. + sb.CreateNestedSkill("_repo/a/dup", map[string]string{"SKILL.md": "---\nname: dup\n---\n# A"}) + sb.CreateNestedSkill("_repo/b/dup", map[string]string{"SKILL.md": "---\nname: dup\n---\n# B"}) + writeNamingConfig(sb, sb.CreateTarget("claude"), "prefixed", "copy") + + sb.RunCLI("sync").AssertOutputContains(t, "adjust include/exclude filters") +} + +func TestSync_TargetNamingPrefixed_UnderscoreFolderWithoutRepoIsNotTracked(t *testing.T) { + sb := testutil.NewSandbox(t) + defer sb.Cleanup() + // "_drafts" is an ordinary folder here (no .git), so nothing is tracked or re-trackable. + sb.CreateNestedSkill("org/_drafts/dup", map[string]string{"SKILL.md": "---\nname: dup\n---\n# One"}) + sb.CreateSkill("dup", map[string]string{"SKILL.md": "---\nname: dup\n---\n# Two"}) + targetPath := sb.CreateTarget("claude") + writeNamingConfig(sb, targetPath, "prefixed", "copy") + + result := sb.RunCLI("sync") + result.AssertOutputContains(t, "Rename one in SKILL.md") + result.AssertOutputNotContains(t, "A tracked skill cannot be renamed") } func TestSync_TargetNamingPrefixed_FromMergeFlatPrunesLinksAndCopies(t *testing.T) { @@ -348,8 +436,8 @@ func TestSync_TargetNamingPrefixed_FromMergeFlatPrunesLinksAndCopies(t *testing. writeNamingConfig(sb, targetPath, "prefixed", "copy") result := sb.RunCLI("sync") result.AssertSuccess(t) - // Prefixing, not a filter, keeps the two prototypes apart. - result.AssertAnyOutputContains(t, "isolated by target filters or naming") + // Prefixing keeps the two prototypes apart, so there is nothing to report. + result.AssertOutputNotContains(t, "duplicate skill names") assertEntries(t, sb, targetPath, "bmad-ux", "emil-design-prototype", "mattpocock-skills-prototype", "my-skill") } diff --git a/tests/integration/target_skills_off_test.go b/tests/integration/target_skills_off_test.go index 889feb9ab..0561c7130 100644 --- a/tests/integration/target_skills_off_test.go +++ b/tests/integration/target_skills_off_test.go @@ -253,4 +253,5 @@ targets: result := sb.RunCLI("target", "claude", "--skills=true") result.AssertFailure(t) result.AssertAnyOutputContains(t, "requires copy mode") + result.AssertAnyOutputContains(t, "set --mode copy first") } diff --git a/website/docs/how-to/sharing/organization-sharing.md b/website/docs/how-to/sharing/organization-sharing.md index 0bd6c93b6..dc8296f9f 100644 --- a/website/docs/how-to/sharing/organization-sharing.md +++ b/website/docs/how-to/sharing/organization-sharing.md @@ -154,20 +154,15 @@ See [Tracked Repositories](/docs/understand/tracked-repositories#nested-skills-- When multiple skills share the same `name` field, sync checks whether they actually land on the same target after `include`/`exclude` filters are applied. -**Filters isolate the collision** — informational only: - -``` -ℹ Duplicate skill names exist but are isolated by target filters: - 'ui' (2 definitions) -``` +**Filters isolate the collision** — nothing is printed; the skills never reach the same target. **Collision reaches the same target** — actionable warning: ``` -⚠ Target 'claude': skill name 'ui' is defined in multiple places: - - _team-a/frontend/ui - - _team-b/components/ui -Rename one in SKILL.md or adjust include/exclude filters +! 1 duplicate skill names detected + ui _team-a/ vs _team-b/ + Rename one in SKILL.md or adjust include/exclude filters + 1 name collision(s) excluded ``` **Solution:** Use namespaced names or route with filters: diff --git a/website/docs/reference/commands/doctor.md b/website/docs/reference/commands/doctor.md index 435bd7d73..e079b5551 100644 --- a/website/docs/reference/commands/doctor.md +++ b/website/docs/reference/commands/doctor.md @@ -135,6 +135,7 @@ Each target shows sub-items for **skills** and **agents** (when agents are confi - `merge` mode: skipped (local skills are expected) - `copy` mode: manifest-managed copies are ignored; only local colliding copies are warned - Valid include/exclude glob patterns +- Naming and mode: a target that resolves to `prefixed` outside copy mode is an error, because sync would skip it - Info-level per-target compatibility hint when applicable (example target priority: `cursor` → `antigravity` → `copilot` → `opencode`; no hint when these targets are absent) ### Path Overlap diff --git a/website/docs/reference/commands/status.md b/website/docs/reference/commands/status.md index 5b8776cfb..96b310fdc 100644 --- a/website/docs/reference/commands/status.md +++ b/website/docs/reference/commands/status.md @@ -168,6 +168,8 @@ skillshare status --json } ``` +A target gets a `warning` string only when sync would reject it, for example `prefixed` naming outside copy mode; the text says how to fix it. + A tracked repo whose git status cannot be read has `"status": "unknown"` and `message` holding the error; `dirty` is then false and not meaningful. The `source.skillignore` field is present only when at least one `.skillignore` or `.skillignore.local` file exists. When absent: `"skillignore": { "active": false }`. The `files` array includes `.skillignore.local` paths when present. In text mode, the `.skillignore` line shows `(.local active)` when any `.skillignore.local` is in effect. diff --git a/website/docs/reference/commands/target.md b/website/docs/reference/commands/target.md index ce1e49e8a..a5f3caf30 100644 --- a/website/docs/reference/commands/target.md +++ b/website/docs/reference/commands/target.md @@ -157,6 +157,8 @@ skillshare target list --json } ``` +`warning` is added only when sync would reject the target, for example `prefixed` naming outside copy mode; the text says how to fix it. + ### target info / settings Show target details or change settings. diff --git a/website/docs/troubleshooting/common-errors.md b/website/docs/troubleshooting/common-errors.md index bd3bb6166..f8658d174 100644 --- a/website/docs/troubleshooting/common-errors.md +++ b/website/docs/troubleshooting/common-errors.md @@ -596,7 +596,7 @@ targets: ``` :::tip -If filters already isolate the duplicates, sync shows an info message instead of a warning — no action needed. +If filters already isolate the duplicates, sync prints nothing about them — no action needed. See [Target Filters](/docs/reference/targets/configuration#include--exclude-target-filters) for full syntax. ::: diff --git a/website/docs/understand/sync-modes.md b/website/docs/understand/sync-modes.md index 2d9ffcd88..fb6423e66 100644 --- a/website/docs/understand/sync-modes.md +++ b/website/docs/understand/sync-modes.md @@ -263,12 +263,12 @@ skillshare sync - A name that already starts with the repo name is not prefixed again: `_bmad/skills/bmad-ux` stays `bmad-ux`. - Skills outside tracked repos keep their name. -- The source skill must pass the `standard` checks first. A prefixed name longer than 64 characters is skipped with a warning, and names that still collide are skipped as in `standard`. +- The source skill must pass the `standard` checks first. A prefixed name longer than 64 characters is skipped with a warning, and names that still collide are skipped as in `standard`. A tracked skill cannot be renamed in `SKILL.md`, so sync then suggests renaming the other skill or re-tracking the repo with `--name`. - For a shorter prefix, track the repo under a short name: `skillshare install --track --name mp` gives `mp-prototype`. - Relative links to sibling skills (`../other-skill/`) are not rewritten, the same as `flat` in copy mode. - The name becomes what the tool shows; in Claude Code it is the slash command, e.g. `/mattpocock-skills-prototype`. -`prefixed` needs copy mode because merge links point at the source, where `name:` cannot change. A target that resolves to `prefixed` in merge or symlink mode fails validation and is skipped by sync. When a new target would inherit `prefixed` in a mode other than copy (a project target defaults to merge), `target add` gives it copy mode. +`prefixed` needs copy mode because merge links point at the source, where `name:` cannot change. A target that resolves to `prefixed` in merge or symlink mode fails validation and is skipped by sync. When a new target would inherit `prefixed` in a mode other than copy (a project target defaults to merge), `target add` gives it copy mode. `target add` says so when it does, and `status` and `doctor` flag a target that resolves to `prefixed` without copy mode before you sync, and so does `target list` for the targets in `targets:`; the fix is `mode: copy` on the target, or `projects..skills.mode: copy` for a target a `projects:` entry expands into. ```yaml targets: diff --git a/website/docs/understand/tracked-repositories.md b/website/docs/understand/tracked-repositories.md index 5a19f314f..2878e4712 100644 --- a/website/docs/understand/tracked-repositories.md +++ b/website/docs/understand/tracked-repositories.md @@ -284,22 +284,19 @@ Tags and commit SHAs cannot be combined with `--track`: a tracked repo pulls fro When multiple skills share the same `name` field, sync checks whether they actually land on the same target after `include`/`exclude` filters are applied. -**Filters isolate the collision** — informational only: - -``` -ℹ Duplicate skill names exist but are isolated by target filters: - 'ui' (2 definitions) -``` +**Filters isolate the collision** — nothing is printed; the skills never reach the same target. **Collision reaches the same target** — actionable warning: ``` -⚠ Target 'claude': skill name 'ui' is defined in multiple places: - - _team-a/frontend/ui - - _team-b/components/ui -Rename one in SKILL.md or adjust include/exclude filters +! 1 duplicate skill names detected + ui _team-a/ vs _team-b/ + Rename one in SKILL.md or adjust include/exclude filters + 1 name collision(s) excluded ``` +With `target_naming: prefixed`, a tracked skill can also collide with a skill that already has its prefixed name (`_alpha/prototype` becomes `alpha-prototype`). A tracked skill cannot be renamed in `SKILL.md`, so sync suggests renaming the other skill or re-tracking the repo with `--name`. + **Best practice** — namespace your skills or use filters: ```yaml diff --git a/website/i18n/ja/docusaurus-plugin-content-docs/current/how-to/sharing/organization-sharing.md b/website/i18n/ja/docusaurus-plugin-content-docs/current/how-to/sharing/organization-sharing.md index 34839744b..ca1252aae 100644 --- a/website/i18n/ja/docusaurus-plugin-content-docs/current/how-to/sharing/organization-sharing.md +++ b/website/i18n/ja/docusaurus-plugin-content-docs/current/how-to/sharing/organization-sharing.md @@ -158,20 +158,15 @@ _org-skills/ 複数の Skill が同じ `name` フィールドを共有する場合、Sync は `include`/`exclude` フィルターの適用後、 それらが実際に同じ Target に配置されるかどうかをチェックします。 -**フィルターが衝突を分離する** — 情報提供のみ: - -``` -ℹ Duplicate skill names exist but are isolated by target filters: - 'ui' (2 definitions) -``` +**フィルターによって衝突が分離される場合** — 何も出力されません。これらの Skill が同じ Target に配置されることはありません。 **衝突が同じ Target に到達する** — 対応が必要な警告: ``` -⚠ Target 'claude': skill name 'ui' is defined in multiple places: - - _team-a/frontend/ui - - _team-b/components/ui -Rename one in SKILL.md or adjust include/exclude filters +! 1 duplicate skill names detected + ui _team-a/ vs _team-b/ + Rename one in SKILL.md or adjust include/exclude filters + 1 name collision(s) excluded ``` **解決策:** 名前空間化された名前を使うか、フィルターでルーティングします。 diff --git a/website/i18n/ja/docusaurus-plugin-content-docs/current/reference/commands/doctor.md b/website/i18n/ja/docusaurus-plugin-content-docs/current/reference/commands/doctor.md index fbd9ecd66..51a01549b 100644 --- a/website/i18n/ja/docusaurus-plugin-content-docs/current/reference/commands/doctor.md +++ b/website/i18n/ja/docusaurus-plugin-content-docs/current/reference/commands/doctor.md @@ -135,6 +135,7 @@ Source link の確認はグローバルモードとプロジェクトモード - `merge` モード: スキップ(ローカルの Skill は想定内のため) - `copy` モード: マニフェストで管理されているコピーは無視され、ローカルで衝突しているコピーのみ警告 - 有効な include/exclude glob パターン +- Naming と mode:copy 以外の mode で `prefixed` に解決される Target はエラーになります。sync がスキップするためです - 該当する場合、Target ごとの情報レベルの互換性ヒント(Target の優先順位の例: `cursor` → `antigravity` → `copilot` → `opencode`。これらの Target が存在しない場合はヒントなし) ### パスの重複 diff --git a/website/i18n/ja/docusaurus-plugin-content-docs/current/reference/commands/status.md b/website/i18n/ja/docusaurus-plugin-content-docs/current/reference/commands/status.md index 269c82b0c..9d5a6a81f 100644 --- a/website/i18n/ja/docusaurus-plugin-content-docs/current/reference/commands/status.md +++ b/website/i18n/ja/docusaurus-plugin-content-docs/current/reference/commands/status.md @@ -168,6 +168,8 @@ skillshare status --json } ``` +`warning` 文字列は、sync がその Target を拒否する場合(例:copy 以外の mode での `prefixed` naming)にのみ付き、修正方法も示されます。 + git status を読み取れない tracked repo は `"status": "unknown"` となり、`message` にエラーが入ります。この場合 `dirty` は false で、意味を持ちません。 `source.skillignore` フィールドは、少なくとも 1 つの `.skillignore` または `.skillignore.local` ファイルが存在する場合にのみ存在します。存在しない場合: `"skillignore": { "active": false }`。`files` 配列には、存在する場合 `.skillignore.local` のパスも含まれます。テキストモードでは、`.skillignore.local` が有効な場合、`.skillignore` の行に `(.local active)` と表示されます。 diff --git a/website/i18n/ja/docusaurus-plugin-content-docs/current/reference/commands/target.md b/website/i18n/ja/docusaurus-plugin-content-docs/current/reference/commands/target.md index 7d7f87c91..aa4e51a50 100644 --- a/website/i18n/ja/docusaurus-plugin-content-docs/current/reference/commands/target.md +++ b/website/i18n/ja/docusaurus-plugin-content-docs/current/reference/commands/target.md @@ -157,6 +157,8 @@ skillshare target list --json } ``` +`warning` は、sync がその Target を拒否する場合(例:copy 以外の mode での `prefixed` naming)にのみ追加され、修正方法も示されます。 + ### target info / settings Target の詳細を表示、または設定を変更します。 diff --git a/website/i18n/ja/docusaurus-plugin-content-docs/current/troubleshooting/common-errors.md b/website/i18n/ja/docusaurus-plugin-content-docs/current/troubleshooting/common-errors.md index 04fd4be47..d037306c3 100644 --- a/website/i18n/ja/docusaurus-plugin-content-docs/current/troubleshooting/common-errors.md +++ b/website/i18n/ja/docusaurus-plugin-content-docs/current/troubleshooting/common-errors.md @@ -607,7 +607,7 @@ targets: ``` :::tip -フィルターがすでに重複を分離している場合、sync は警告ではなく情報メッセージを表示します — +フィルターがすでに重複を分離している場合、sync はそれについて何も出力しません — 対応は不要です。 完全な構文は [Target フィルター](/docs/reference/targets/configuration#include--exclude-target-filters) を参照してください。 diff --git a/website/i18n/ja/docusaurus-plugin-content-docs/current/understand/sync-modes.md b/website/i18n/ja/docusaurus-plugin-content-docs/current/understand/sync-modes.md index 2da332658..1a13fce7b 100644 --- a/website/i18n/ja/docusaurus-plugin-content-docs/current/understand/sync-modes.md +++ b/website/i18n/ja/docusaurus-plugin-content-docs/current/understand/sync-modes.md @@ -264,12 +264,12 @@ skillshare sync - 名前がすでに repo 名で始まっている場合は、再度プレフィックスを付けません: `_bmad/skills/bmad-ux` は `bmad-ux` のままです。 - tracked repo の外にある Skill は名前をそのまま保ちます。 -- source の Skill は、まず `standard` のチェックを通過する必要があります。prefixed 名が 64 文字を超える場合は警告付きでスキップされ、それでも名前が衝突する場合は `standard` と同様にスキップされます。 +- source の Skill は、まず `standard` のチェックを通過する必要があります。prefixed 名が 64 文字を超える場合は警告付きでスキップされ、それでも名前が衝突する場合は `standard` と同様にスキップされます。tracked Skill は `SKILL.md` で名前を変更できないため、sync はもう一方の Skill の名前を変えるか、`--name` で repo を再度 track することを提案します。 - より短いプレフィックスにしたい場合は、repo を短い名前で track します: `skillshare install --track --name mp` は `mp-prototype` になります。 - 兄弟 Skill への相対リンク(`../other-skill/`)は書き換えられません。これは copy mode の `flat` と同じです。 - この名前がツールに表示される名前になります。Claude Code ではスラッシュコマンドになります。例: `/mattpocock-skills-prototype`。 -`prefixed` は copy mode が必要です。merge のリンクは source を指しており、そこでは `name:` を変更できないためです。merge mode または symlink mode で `prefixed` に解決される Target は、バリデーションに失敗し、sync でスキップされます。新しい Target が copy 以外の mode で `prefixed` を継承する場合(プロジェクトの Target は既定で merge)、`target add` はその Target を copy mode にします。 +`prefixed` は copy mode が必要です。merge のリンクは source を指しており、そこでは `name:` を変更できないためです。merge mode または symlink mode で `prefixed` に解決される Target は、バリデーションに失敗し、sync でスキップされます。新しい Target が copy 以外の mode で `prefixed` を継承する場合(プロジェクトの Target は既定で merge)、`target add` はその Target を copy mode にします。`target add` はそうしたときにその旨を表示します。また `status` と `doctor` は、copy 以外の mode で `prefixed` に解決される Target を sync の前に警告します。`targets:` にある Target については `target list` も同様です。対処は、その Target に `mode: copy` を設定することです。`projects:` エントリから展開された Target の場合は `projects..skills.mode: copy` を設定します。 ```yaml targets: diff --git a/website/i18n/ja/docusaurus-plugin-content-docs/current/understand/tracked-repositories.md b/website/i18n/ja/docusaurus-plugin-content-docs/current/understand/tracked-repositories.md index 2f3a27048..54f7a590a 100644 --- a/website/i18n/ja/docusaurus-plugin-content-docs/current/understand/tracked-repositories.md +++ b/website/i18n/ja/docusaurus-plugin-content-docs/current/understand/tracked-repositories.md @@ -284,22 +284,19 @@ skillshare install github.com/team/skills --branch 8f14e45 --all 複数の Skill が同じ `name` フィールドを共有している場合、sync は `include`/`exclude` フィルターの適用後に、それらが実際に同じ Target に配置されるかどうかを確認します。 -**フィルターによって衝突が分離される場合** — 情報提供のみ: - -``` -ℹ Duplicate skill names exist but are isolated by target filters: - 'ui' (2 definitions) -``` +**フィルターによって衝突が分離される場合** — 何も出力されません。これらの Skill が同じ Target に配置されることはありません。 **衝突が同じ Target に達する場合** — 対応が必要な警告: ``` -⚠ Target 'claude': skill name 'ui' is defined in multiple places: - - _team-a/frontend/ui - - _team-b/components/ui -Rename one in SKILL.md or adjust include/exclude filters +! 1 duplicate skill names detected + ui _team-a/ vs _team-b/ + Rename one in SKILL.md or adjust include/exclude filters + 1 name collision(s) excluded ``` +`target_naming: prefixed` では、tracked Skill が、すでにその prefixed 名を持つ Skill と衝突することもあります(`_alpha/prototype` は `alpha-prototype` になります)。tracked Skill は `SKILL.md` で名前を変更できないため、sync はもう一方の Skill の名前を変えるか、`--name` で repo を再度 track することを提案します。 + **ベストプラクティス** — Skill に名前空間を付けるか、フィルターを使用します: ```yaml diff --git a/website/i18n/ko/docusaurus-plugin-content-docs/current/how-to/sharing/organization-sharing.md b/website/i18n/ko/docusaurus-plugin-content-docs/current/how-to/sharing/organization-sharing.md index f7a952171..479dbf93c 100644 --- a/website/i18n/ko/docusaurus-plugin-content-docs/current/how-to/sharing/organization-sharing.md +++ b/website/i18n/ko/docusaurus-plugin-content-docs/current/how-to/sharing/organization-sharing.md @@ -154,20 +154,15 @@ _org-skills/ 여러 Skill이 같은 `name` 필드를 공유하는 경우, sync는 `include`/`exclude` 필터가 적용된 후 실제로 동일한 Target에 도달하는지 확인합니다. -**필터가 충돌을 격리함** — 정보성 알림만 표시: - -``` -ℹ Duplicate skill names exist but are isolated by target filters: - 'ui' (2 definitions) -``` +**필터가 충돌을 격리함** — 아무것도 출력되지 않습니다. 해당 skill은 같은 target에 도달하지 않습니다. **충돌이 동일한 Target에 도달함** — 조치가 필요한 경고: ``` -⚠ Target 'claude': skill name 'ui' is defined in multiple places: - - _team-a/frontend/ui - - _team-b/components/ui -Rename one in SKILL.md or adjust include/exclude filters +! 1 duplicate skill names detected + ui _team-a/ vs _team-b/ + Rename one in SKILL.md or adjust include/exclude filters + 1 name collision(s) excluded ``` **해결 방법:** 네임스페이스가 적용된 이름을 사용하거나 필터로 라우팅하세요: diff --git a/website/i18n/ko/docusaurus-plugin-content-docs/current/reference/commands/doctor.md b/website/i18n/ko/docusaurus-plugin-content-docs/current/reference/commands/doctor.md index 4a149eab7..d2adb632d 100644 --- a/website/i18n/ko/docusaurus-plugin-content-docs/current/reference/commands/doctor.md +++ b/website/i18n/ko/docusaurus-plugin-content-docs/current/reference/commands/doctor.md @@ -135,6 +135,7 @@ Source link 검사는 global과 project mode 모두에서 수행됩니다. sourc - `merge` 모드: 건너뜀 (local skill은 예상된 것) - `copy` 모드: manifest로 관리되는 복사본은 무시하며, local 충돌 복사본만 경고 - 유효한 include/exclude glob 패턴 +- Naming과 mode: copy 이외의 mode에서 `prefixed`로 결정되는 target은 sync가 건너뛰므로 오류로 표시됩니다 - 해당하는 경우 target별 호환성 힌트 (info 수준) (예시 target 우선순위: `cursor` → `antigravity` → `copilot` → `opencode`; 이 target들이 없으면 힌트 없음) ### Path Overlap diff --git a/website/i18n/ko/docusaurus-plugin-content-docs/current/reference/commands/status.md b/website/i18n/ko/docusaurus-plugin-content-docs/current/reference/commands/status.md index 87bc89145..00024c8ca 100644 --- a/website/i18n/ko/docusaurus-plugin-content-docs/current/reference/commands/status.md +++ b/website/i18n/ko/docusaurus-plugin-content-docs/current/reference/commands/status.md @@ -168,6 +168,8 @@ skillshare status --json } ``` +`warning` 문자열은 sync가 해당 target을 거부할 때만 붙습니다(예: copy 이외의 mode에서 `prefixed` naming). 문구에 해결 방법이 포함됩니다. + git status를 읽을 수 없는 tracked repo는 `"status": "unknown"`이 되고 `message`에 오류가 담깁니다. 이때 `dirty`는 false이며 의미가 없습니다. `source.skillignore` 필드는 `.skillignore` 또는 `.skillignore.local` file이 하나 이상 존재할 때만 나타납니다. 없을 경우: `"skillignore": { "active": false }`. `files` 배열은 존재하는 경우 `.skillignore.local` 경로를 포함합니다. text mode에서는 `.skillignore.local`이 적용 중이면 `.skillignore` 줄에 `(.local active)`가 표시됩니다. diff --git a/website/i18n/ko/docusaurus-plugin-content-docs/current/reference/commands/target.md b/website/i18n/ko/docusaurus-plugin-content-docs/current/reference/commands/target.md index 337d4015a..d1288fa84 100644 --- a/website/i18n/ko/docusaurus-plugin-content-docs/current/reference/commands/target.md +++ b/website/i18n/ko/docusaurus-plugin-content-docs/current/reference/commands/target.md @@ -157,6 +157,8 @@ skillshare target list --json } ``` +`warning`은 sync가 해당 target을 거부할 때만 추가됩니다(예: copy 이외의 mode에서 `prefixed` naming). 문구에 해결 방법이 포함됩니다. + ### target info / settings target 세부 정보를 표시하거나 설정을 변경합니다. diff --git a/website/i18n/ko/docusaurus-plugin-content-docs/current/troubleshooting/common-errors.md b/website/i18n/ko/docusaurus-plugin-content-docs/current/troubleshooting/common-errors.md index f3169f068..762cae2c1 100644 --- a/website/i18n/ko/docusaurus-plugin-content-docs/current/troubleshooting/common-errors.md +++ b/website/i18n/ko/docusaurus-plugin-content-docs/current/troubleshooting/common-errors.md @@ -560,7 +560,7 @@ targets: ``` :::tip -필터가 이미 중복 항목을 분리하고 있다면, sync는 경고 대신 정보 메시지를 표시합니다 — 별도 조치가 필요 없습니다. +필터가 이미 중복 항목을 분리하고 있다면, sync는 이에 대해 아무것도 출력하지 않습니다 — 별도 조치가 필요 없습니다. 전체 문법은 [Target Filters](/docs/reference/targets/configuration#include--exclude-target-filters)를 참고하세요. ::: diff --git a/website/i18n/ko/docusaurus-plugin-content-docs/current/understand/sync-modes.md b/website/i18n/ko/docusaurus-plugin-content-docs/current/understand/sync-modes.md index 6158bad94..b3916a31c 100644 --- a/website/i18n/ko/docusaurus-plugin-content-docs/current/understand/sync-modes.md +++ b/website/i18n/ko/docusaurus-plugin-content-docs/current/understand/sync-modes.md @@ -263,12 +263,12 @@ skillshare sync - 이름이 이미 repo 이름으로 시작하면 접두사를 다시 붙이지 않습니다: `_bmad/skills/bmad-ux`는 `bmad-ux`로 유지됩니다. - tracked repo 밖의 skill은 이름을 그대로 유지합니다. -- source skill은 먼저 `standard` 검사를 통과해야 합니다. 접두사가 붙은 이름이 64자를 넘으면 경고와 함께 건너뛰어지고, 그래도 이름이 충돌하면 `standard`와 같이 건너뛰어집니다. +- source skill은 먼저 `standard` 검사를 통과해야 합니다. 접두사가 붙은 이름이 64자를 넘으면 경고와 함께 건너뛰어지고, 그래도 이름이 충돌하면 `standard`와 같이 건너뛰어집니다. tracked skill은 `SKILL.md`에서 이름을 바꿀 수 없으므로 sync는 다른 skill의 이름을 바꾸거나 `--name`으로 repo를 다시 track하도록 안내합니다. - 더 짧은 접두사가 필요하면 repo를 짧은 이름으로 track하세요: `skillshare install --track --name mp`는 `mp-prototype`을 만듭니다. - 형제 skill로의 상대 링크(`../other-skill/`)는 다시 쓰이지 않으며, 이는 copy mode의 `flat`과 같습니다. - 이 이름이 도구에 표시되는 이름이 됩니다. Claude Code에서는 slash command이며, 예: `/mattpocock-skills-prototype`. -`prefixed`는 merge 링크가 source를 가리키고 그곳의 `name:`은 바꿀 수 없으므로 copy mode가 필요합니다. merge 또는 symlink mode에서 `prefixed`로 결정되는 target은 검증에 실패하며 sync에서 건너뛰어집니다. 새 target이 copy 이외의 mode에서 `prefixed`를 상속하게 되면(프로젝트 target 기본값은 merge) `target add`는 새 target을 copy mode로 추가합니다. +`prefixed`는 merge 링크가 source를 가리키고 그곳의 `name:`은 바꿀 수 없으므로 copy mode가 필요합니다. merge 또는 symlink mode에서 `prefixed`로 결정되는 target은 검증에 실패하며 sync에서 건너뛰어집니다. 새 target이 copy 이외의 mode에서 `prefixed`를 상속하게 되면(프로젝트 target 기본값은 merge) `target add`는 새 target을 copy mode로 추가합니다. `target add`는 그렇게 할 때 알려 주며, `status`와 `doctor`는 copy 이외의 mode에서 `prefixed`로 결정되는 target을 sync 전에 표시하며, `targets:`에 있는 target은 `target list`도 표시합니다. 해결 방법은 해당 target에 `mode: copy`를 설정하는 것입니다. `projects:` 항목에서 확장된 target이라면 `projects..skills.mode: copy`를 설정하세요. ```yaml targets: diff --git a/website/i18n/ko/docusaurus-plugin-content-docs/current/understand/tracked-repositories.md b/website/i18n/ko/docusaurus-plugin-content-docs/current/understand/tracked-repositories.md index bb87df4f4..71974a201 100644 --- a/website/i18n/ko/docusaurus-plugin-content-docs/current/understand/tracked-repositories.md +++ b/website/i18n/ko/docusaurus-plugin-content-docs/current/understand/tracked-repositories.md @@ -284,22 +284,19 @@ tag와 commit SHA는 `--track`과 함께 사용할 수 없습니다. tracked rep 여러 skill이 같은 `name` 필드를 공유할 때, sync는 `include`/`exclude` 필터가 적용된 후 실제로 동일한 target에 도달하는지 확인합니다. -**필터가 충돌을 격리함** — 정보성 메시지일 뿐입니다: - -``` -ℹ Duplicate skill names exist but are isolated by target filters: - 'ui' (2 definitions) -``` +**필터가 충돌을 격리함** — 아무것도 출력되지 않습니다. 해당 skill은 같은 target에 도달하지 않습니다. **충돌이 동일한 target에 도달함** — 실행 가능한 경고입니다: ``` -⚠ Target 'claude': skill name 'ui' is defined in multiple places: - - _team-a/frontend/ui - - _team-b/components/ui -Rename one in SKILL.md or adjust include/exclude filters +! 1 duplicate skill names detected + ui _team-a/ vs _team-b/ + Rename one in SKILL.md or adjust include/exclude filters + 1 name collision(s) excluded ``` +`target_naming: prefixed`에서는 tracked skill이 이미 그 접두사 이름을 가진 skill과 충돌할 수도 있습니다(`_alpha/prototype`은 `alpha-prototype`이 됩니다). tracked skill은 `SKILL.md`에서 이름을 바꿀 수 없으므로 sync는 다른 skill의 이름을 바꾸거나 `--name`으로 repo를 다시 track하도록 안내합니다. + **모범 사례** — skill에 네임스페이스를 부여하거나 필터를 사용하세요: ```yaml diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/how-to/sharing/organization-sharing.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/how-to/sharing/organization-sharing.md index 31ef81aed..aeab7beb3 100644 --- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/how-to/sharing/organization-sharing.md +++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/how-to/sharing/organization-sharing.md @@ -154,20 +154,15 @@ _org-skills/ 当多个 Skill 共享相同的 `name` 字段时,sync 会检查它们在套用 `include`/`exclude` 过滤器后,是否真的会落在同一个 Target 上。 -**过滤器隔离了冲突**——仅供参考: - -``` -ℹ Duplicate skill names exist but are isolated by target filters: - 'ui' (2 definitions) -``` +**过滤器隔离了冲突** —— 不会输出任何内容,这些 Skill 不会落到同一个 Target。 **冲突落在同一个 Target 上**——需要处理的警告: ``` -⚠ Target 'claude': skill name 'ui' is defined in multiple places: - - _team-a/frontend/ui - - _team-b/components/ui -Rename one in SKILL.md or adjust include/exclude filters +! 1 duplicate skill names detected + ui _team-a/ vs _team-b/ + Rename one in SKILL.md or adjust include/exclude filters + 1 name collision(s) excluded ``` **解法:** 使用带命名空间的名称,或用过滤器分流: diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/commands/doctor.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/commands/doctor.md index d41ab1bda..efa6a4b60 100644 --- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/commands/doctor.md +++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/commands/doctor.md @@ -135,6 +135,7 @@ Source link 检查在 global 与 project mode 都会执行。source 根目录按 - `merge` 模式:跳过(本地 skills 是预期存在的) - `copy` 模式:忽略由 manifest 管理的副本;只警告本地冲突的副本 - 有效的 include/exclude glob 模式 +- Naming 与 mode:在 copy 以外的模式下解析为 `prefixed` 的 target 会被标为错误,因为 sync 会跳过它 - 适用时给出的 info 级别的每个 target 兼容性提示(示例 target 优先级:`cursor` → `antigravity` → `copilot` → `opencode`;这些 targets 都不存在时不给提示) ### Path Overlap diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/commands/status.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/commands/status.md index e3f9a27c6..8d8c2321f 100644 --- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/commands/status.md +++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/commands/status.md @@ -168,6 +168,8 @@ skillshare status --json } ``` +只有 sync 会拒绝某个 target 时,该 target 才会有 `warning` 字符串,例如在 copy 以外的模式下使用 `prefixed` naming;文字中会说明如何修正。 + 无法读取 git status 的 tracked repo 会显示 `"status": "unknown"`,`message` 中包含错误信息;此时 `dirty` 为 false,且没有意义。 `source.skillignore` 字段仅在至少存在一个 `.skillignore` 或 `.skillignore.local` 文件时出现。不存在时:`"skillignore": { "active": false }`。`files` 数组在 `.skillignore.local` 存在时会包含其路径。在文本模式下,当任何 `.skillignore.local` 生效时,`.skillignore` 那一行会显示 `(.local active)`。 diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/commands/target.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/commands/target.md index 6da372189..d2fd987c2 100644 --- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/commands/target.md +++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/commands/target.md @@ -157,6 +157,8 @@ skillshare target list --json } ``` +只有 sync 会拒绝该 target 时才会出现 `warning`,例如在 copy 以外的模式下使用 `prefixed` naming;文字中会说明如何修正。 + ### target info / settings 显示 target 详情或更改设置。 diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/troubleshooting/common-errors.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/troubleshooting/common-errors.md index 0e25e85ae..2253d831d 100644 --- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/troubleshooting/common-errors.md +++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/troubleshooting/common-errors.md @@ -560,7 +560,7 @@ targets: ``` :::tip -如果过滤器已经把重复项隔离开来,sync 只会显示信息提示而不是警告——不需要额外处理。 +如果过滤器已经把重复项隔离开来,sync 不会输出任何相关内容——不需要额外处理。 完整语法参见 [Target Filters](/docs/reference/targets/configuration#include--exclude-target-filters)。 ::: diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/understand/sync-modes.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/understand/sync-modes.md index 3368f8958..1ac3ef9e3 100644 --- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/understand/sync-modes.md +++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/understand/sync-modes.md @@ -263,12 +263,12 @@ skillshare sync - 名称已经以 repo 名开头时不会重复加前缀:`_bmad/skills/bmad-ux` 仍是 `bmad-ux`。 - 不在 tracked repo 内的 skill 保持原名。 -- source skill 必须先通过 `standard` 检查。带前缀的名称超过 64 个字符时会收到警告并被跳过,仍然冲突的名称与 `standard` 一样被跳过。 +- source skill 必须先通过 `standard` 检查。带前缀的名称超过 64 个字符时会收到警告并被跳过,仍然冲突的名称与 `standard` 一样被跳过。tracked skill 不能在 `SKILL.md` 中改名,因此 sync 会建议重命名另一个 skill,或用 `--name` 重新 track 该 repo。 - 想要更短的前缀,可以用较短的名称 track repo:`skillshare install --track --name mp` 会得到 `mp-prototype`。 - 指向同级 skill 的相对链接(`../other-skill/`)不会被改写,与 copy 模式下的 `flat` 相同。 - 该名称就是工具中显示的名称;在 Claude Code 中它是 slash command,例如 `/mattpocock-skills-prototype`。 -`prefixed` 需要 copy 模式,因为 merge 链接指向 source,而 source 中的 `name:` 不能被修改。在 merge 或 symlink 模式下解析为 `prefixed` 的 target 会校验失败,并被 sync 跳过。新 target 若会在 copy 以外的模式下继承 `prefixed`(项目 target 默认为 merge),`target add` 会让它使用 copy 模式。 +`prefixed` 需要 copy 模式,因为 merge 链接指向 source,而 source 中的 `name:` 不能被修改。在 merge 或 symlink 模式下解析为 `prefixed` 的 target 会校验失败,并被 sync 跳过。新 target 若会在 copy 以外的模式下继承 `prefixed`(项目 target 默认为 merge),`target add` 会让它使用 copy 模式。`target add` 这样做时会提示;`status` 和 `doctor` 会在 sync 之前标出在 copy 以外的模式下解析为 `prefixed` 的 target,`target list` 对 `targets:` 中的 target 也会如此,修正方法是在该 target 上设置 `mode: copy`;若该 target 由 `projects:` 条目展开而来,则设置 `projects..skills.mode: copy`。 ```yaml targets: diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/understand/tracked-repositories.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/understand/tracked-repositories.md index 76f1249f8..20d41f519 100644 --- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/understand/tracked-repositories.md +++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/understand/tracked-repositories.md @@ -284,22 +284,19 @@ Tag 和 commit SHA 不能与 `--track` 组合使用:tracked 仓库从分支 pu 当多个 Skill 共享相同的 `name` 字段时,Sync 会检查在应用 `include`/`exclude` 过滤器后,它们是否会实际落到同一个 Target 上。 -**过滤器隔离了冲突** —— 仅作提示: - -``` -ℹ Duplicate skill names exist but are isolated by target filters: - 'ui' (2 definitions) -``` +**过滤器隔离了冲突** —— 不会输出任何内容,这些 Skill 不会落到同一个 Target。 **冲突落到了同一个 Target** —— 需要处理的警告: ``` -⚠ Target 'claude': skill name 'ui' is defined in multiple places: - - _team-a/frontend/ui - - _team-b/components/ui -Rename one in SKILL.md or adjust include/exclude filters +! 1 duplicate skill names detected + ui _team-a/ vs _team-b/ + Rename one in SKILL.md or adjust include/exclude filters + 1 name collision(s) excluded ``` +使用 `target_naming: prefixed` 时,tracked skill 也可能与已使用该前缀名称的 skill 冲突(`_alpha/prototype` 会变成 `alpha-prototype`)。tracked skill 不能在 `SKILL.md` 中改名,因此 Sync 会建议重命名另一个 skill,或用 `--name` 重新 track 该 repo。 + **最佳实践** —— 为 Skill 命名空间化,或使用过滤器: ```yaml diff --git a/website/i18n/zh-Hant/docusaurus-plugin-content-docs/current/how-to/sharing/organization-sharing.md b/website/i18n/zh-Hant/docusaurus-plugin-content-docs/current/how-to/sharing/organization-sharing.md index 52f766fdf..53d212957 100644 --- a/website/i18n/zh-Hant/docusaurus-plugin-content-docs/current/how-to/sharing/organization-sharing.md +++ b/website/i18n/zh-Hant/docusaurus-plugin-content-docs/current/how-to/sharing/organization-sharing.md @@ -154,20 +154,15 @@ _org-skills/ 當多個 skills 共用相同的 `name` 欄位時,sync 會檢查在套用 `include`/`exclude` 篩選條件後,它們是否真的會落在同一個 target 上。 -**篩選條件隔離了衝突** — 僅供參考: - -``` -ℹ Duplicate skill names exist but are isolated by target filters: - 'ui' (2 definitions) -``` +**過濾已隔離衝突** — 不會輸出任何內容,這些 skills 不會落到同一個 target。 **衝突發生在同一個 target 上** — 需要處理的警告: ``` -⚠ Target 'claude': skill name 'ui' is defined in multiple places: - - _team-a/frontend/ui - - _team-b/components/ui -Rename one in SKILL.md or adjust include/exclude filters +! 1 duplicate skill names detected + ui _team-a/ vs _team-b/ + Rename one in SKILL.md or adjust include/exclude filters + 1 name collision(s) excluded ``` **解決方式:** 使用具命名空間的名稱,或用篩選條件分流: diff --git a/website/i18n/zh-Hant/docusaurus-plugin-content-docs/current/reference/commands/doctor.md b/website/i18n/zh-Hant/docusaurus-plugin-content-docs/current/reference/commands/doctor.md index 497b3f72f..3f9198009 100644 --- a/website/i18n/zh-Hant/docusaurus-plugin-content-docs/current/reference/commands/doctor.md +++ b/website/i18n/zh-Hant/docusaurus-plugin-content-docs/current/reference/commands/doctor.md @@ -135,6 +135,7 @@ Source link 檢查在 global 與 project mode 都會執行。source 根目錄依 - `merge` 模式:跳過(本機 skills 屬於預期情況) - `copy` 模式:由 manifest 管理的副本會被忽略;只有本機衝突的副本會被警告 - 有效的 include/exclude glob patterns +- Naming 與 mode:在 copy 以外的 mode 下解析為 `prefixed` 的 target 會被標為錯誤,因為 sync 會略過它 - 適用時提供資訊層級的每個 target 相容性提示(範例 target 優先順序:`cursor` → `antigravity` → `copilot` → `opencode`;若這些 targets 都不存在則不會顯示提示) ### Path Overlap diff --git a/website/i18n/zh-Hant/docusaurus-plugin-content-docs/current/reference/commands/status.md b/website/i18n/zh-Hant/docusaurus-plugin-content-docs/current/reference/commands/status.md index a9802a0c6..07c724898 100644 --- a/website/i18n/zh-Hant/docusaurus-plugin-content-docs/current/reference/commands/status.md +++ b/website/i18n/zh-Hant/docusaurus-plugin-content-docs/current/reference/commands/status.md @@ -168,6 +168,8 @@ skillshare status --json } ``` +只有 sync 會拒絕某個 target 時,該 target 才會有 `warning` 字串,例如在 copy 以外的 mode 下使用 `prefixed` naming;文字中會說明如何修正。 + 無法讀取 git status 的 tracked repo 會顯示 `"status": "unknown"`,`message` 中包含錯誤訊息;此時 `dirty` 為 false,且不具意義。 `source.skillignore` 欄位只有在至少存在一個 `.skillignore` 或 `.skillignore.local` 檔案時才會出現。若不存在則為:`"skillignore": { "active": false }`。`files` 陣列在有 `.skillignore.local` 時也會包含其路徑。在文字模式下,若有任何 `.skillignore.local` 生效,`.skillignore` 那一行會顯示 `(.local active)`。 diff --git a/website/i18n/zh-Hant/docusaurus-plugin-content-docs/current/reference/commands/target.md b/website/i18n/zh-Hant/docusaurus-plugin-content-docs/current/reference/commands/target.md index 9d35357b7..9f6cd2c1d 100644 --- a/website/i18n/zh-Hant/docusaurus-plugin-content-docs/current/reference/commands/target.md +++ b/website/i18n/zh-Hant/docusaurus-plugin-content-docs/current/reference/commands/target.md @@ -157,6 +157,8 @@ skillshare target list --json } ``` +只有 sync 會拒絕該 target 時才會出現 `warning`,例如在 copy 以外的 mode 下使用 `prefixed` naming;文字中會說明如何修正。 + ### target info / settings 顯示 target 詳細資訊或變更設定。 diff --git a/website/i18n/zh-Hant/docusaurus-plugin-content-docs/current/troubleshooting/common-errors.md b/website/i18n/zh-Hant/docusaurus-plugin-content-docs/current/troubleshooting/common-errors.md index 9346faac0..af5a8d685 100644 --- a/website/i18n/zh-Hant/docusaurus-plugin-content-docs/current/troubleshooting/common-errors.md +++ b/website/i18n/zh-Hant/docusaurus-plugin-content-docs/current/troubleshooting/common-errors.md @@ -560,7 +560,7 @@ targets: ``` :::tip -如果篩選條件已經隔離了重複項目,sync 會顯示資訊訊息而非警告 — 無需採取行動。 +如果篩選條件已經隔離了重複項目,sync 不會輸出任何相關內容 — 無需採取行動。 完整語法請參閱 [Target 篩選條件](/docs/reference/targets/configuration#include--exclude-target-filters)。 ::: diff --git a/website/i18n/zh-Hant/docusaurus-plugin-content-docs/current/understand/sync-modes.md b/website/i18n/zh-Hant/docusaurus-plugin-content-docs/current/understand/sync-modes.md index 340571c93..39e904fd4 100644 --- a/website/i18n/zh-Hant/docusaurus-plugin-content-docs/current/understand/sync-modes.md +++ b/website/i18n/zh-Hant/docusaurus-plugin-content-docs/current/understand/sync-modes.md @@ -263,12 +263,12 @@ skillshare sync - 名稱已經以 repo 名稱開頭時,不會重複加前綴:`_bmad/skills/bmad-ux` 仍是 `bmad-ux`。 - 不在 tracked repo 內的 skill 維持原名。 -- source skill 必須先通過 `standard` 檢查。加上前綴後的名稱超過 64 個字元時會顯示警告並被略過,仍然衝突的名稱與 `standard` 一樣被略過。 +- source skill 必須先通過 `standard` 檢查。加上前綴後的名稱超過 64 個字元時會顯示警告並被略過,仍然衝突的名稱與 `standard` 一樣被略過。tracked skill 無法在 `SKILL.md` 中改名,因此 sync 會建議重新命名另一個 skill,或以 `--name` 重新 track 該 repo。 - 想要更短的前綴,可以用較短的名稱 track repo:`skillshare install --track --name mp` 會得到 `mp-prototype`。 - 指向同層 skill 的相對連結(`../other-skill/`)不會被改寫,與 copy mode 下的 `flat` 相同。 - 該名稱就是工具中顯示的名稱;在 Claude Code 中它是 slash command,例如 `/mattpocock-skills-prototype`。 -`prefixed` 需要 copy mode,因為 merge 連結指向 source,而 source 中的 `name:` 不能被修改。在 merge 或 symlink mode 下解析為 `prefixed` 的 target 會驗證失敗,並被 sync 略過。新 target 若會在 copy 以外的 mode 下繼承 `prefixed`(專案 target 預設為 merge),`target add` 會讓它使用 copy mode。 +`prefixed` 需要 copy mode,因為 merge 連結指向 source,而 source 中的 `name:` 不能被修改。在 merge 或 symlink mode 下解析為 `prefixed` 的 target 會驗證失敗,並被 sync 略過。新 target 若會在 copy 以外的 mode 下繼承 `prefixed`(專案 target 預設為 merge),`target add` 會讓它使用 copy mode。`target add` 這麼做時會提示;`status` 和 `doctor` 會在 sync 之前標出在 copy 以外的 mode 下解析為 `prefixed` 的 target,`target list` 對 `targets:` 中的 target 也會如此,修正方式是在該 target 上設定 `mode: copy`;若該 target 由 `projects:` 項目展開而來,則設定 `projects..skills.mode: copy`。 ```yaml targets: diff --git a/website/i18n/zh-Hant/docusaurus-plugin-content-docs/current/understand/tracked-repositories.md b/website/i18n/zh-Hant/docusaurus-plugin-content-docs/current/understand/tracked-repositories.md index eb78a54a8..907ca4db3 100644 --- a/website/i18n/zh-Hant/docusaurus-plugin-content-docs/current/understand/tracked-repositories.md +++ b/website/i18n/zh-Hant/docusaurus-plugin-content-docs/current/understand/tracked-repositories.md @@ -284,22 +284,19 @@ Tag 與 commit SHA 不能搭配 `--track`:tracked repo 是從 branch pull,de 當多個 skills 共用相同的 `name` 欄位時,sync 會檢查它們在套用 `include`/`exclude` 過濾之後,是否真的落到同一個 target 上。 -**過濾已隔離衝突** — 僅供參考: - -``` -ℹ Duplicate skill names exist but are isolated by target filters: - 'ui' (2 definitions) -``` +**過濾已隔離衝突** — 不會輸出任何內容,這些 skills 不會落到同一個 target。 **衝突延伸到同一個 target** — 可採取行動的警告: ``` -⚠ Target 'claude': skill name 'ui' is defined in multiple places: - - _team-a/frontend/ui - - _team-b/components/ui -Rename one in SKILL.md or adjust include/exclude filters +! 1 duplicate skill names detected + ui _team-a/ vs _team-b/ + Rename one in SKILL.md or adjust include/exclude filters + 1 name collision(s) excluded ``` +使用 `target_naming: prefixed` 時,tracked skill 也可能與已使用該前綴名稱的 skill 衝突(`_alpha/prototype` 會變成 `alpha-prototype`)。tracked skill 無法在 `SKILL.md` 中改名,因此 sync 會建議重新命名另一個 skill,或以 `--name` 重新 track 該 repo。 + **最佳做法** — 為 skills 加上命名空間,或使用過濾: ```yaml