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