diff --git a/ai_docs/tests/discovery_skip_target_dotdirs_runbook.md b/ai_docs/tests/discovery_skip_target_dotdirs_runbook.md index 3dfaecb5f..871da39e1 100644 --- a/ai_docs/tests/discovery_skip_target_dotdirs_runbook.md +++ b/ai_docs/tests/discovery_skip_target_dotdirs_runbook.md @@ -1,10 +1,12 @@ # Discovery: Skip Target Dotdirs Runbook -Verifies that `discoverSkills` skips known target directories (`.claude/`, `.cursor/`, `.skillshare/`) during install discovery, while still finding skills in non-target hidden directories (`.curated/`, `.system/`). +Verifies that `discoverSkills` skips known target directories (`.claude/`, `.cursor/`, `.skillshare/`) during install discovery, while still finding skills in non-target hidden directories (`.curated/`, `.system/`). A repository-root `.agents/skills/` is discovered only when the repository has no other skills. ## Scope - `internal/install/install_discovery.go` — `discoverSkills` skip logic +- `internal/sourcewalk/walk.go` — `AgentsSkillsDir` repository-root `.agents/skills` rule +- `internal/sync/discover_walk.go` — the same rule for tracked repos during sync - `internal/config/targets.go` — `ProjectTargetDotDirs()` function - `cmd/skillshare/main.go` — injection of target dotdirs at startup @@ -18,10 +20,12 @@ Verifies that `discoverSkills` skips known target directories (`.claude/`, `.cur ### Step 1: Create repos for testing -Creates three bare repos: +Creates five bare repos: 1. `repo1.git` — source skills + `.claude/` and `.cursor/` target copies 2. `repo2.git` — non-target hidden dirs (`.curated/`, `.system/`) + `.claude/` target copy 3. `repo3.git` — normal skill + `.skillshare/` config dir with stray SKILL.md +4. `repo4.git` — `skills/` + `.agents/skills/` copies of the same names +5. `repo5.git` — skills only in `.agents/skills/` (issue #800) ```bash BASE=/tmp/e2e-dotdir-test @@ -87,6 +91,22 @@ name: stray git add -A && git commit -m "init" git remote add origin "$BASE/repo3.git" && git push origin master +# --- Repos 4 and 5: repository-root .agents/skills --- +mkrepo() { # repo name, then path:body pairs + local repo=$1; shift + git init -q --bare "$BASE/$repo.git" + local W=$(mktemp -d) + cd "$W" && git init -q && git config user.email "t@t" && git config user.name "T" + for spec in "$@"; do + p=${spec%%:*}; body=${spec#*:} + mkdir -p "$p" + printf -- "---\nname: %s\n---\n# %s\n" "$(basename "$p")" "$body" > "$p/SKILL.md" + done + git add -A && git commit -qm init && git push -q "$BASE/$repo.git" HEAD:master +} +mkrepo repo4 skills/alpha:authored skills/beta:authored .agents/skills/alpha:copy .agents/skills/beta:copy +mkrepo repo5 .agents/skills/psychopomp:authored .agents/skills/explainer-motion:authored + echo "ALL REPOS CREATED" ``` @@ -150,9 +170,50 @@ ss install "file:///tmp/e2e-dotdir-test/repo3.git" --all --json --force 2>/dev/n Expected: - 1 +### Step 8: Install repo4 — authored skills win over `.agents/skills` copies + +```bash +ss install "file:///tmp/e2e-dotdir-test/repo4.git" --all --json 2>/dev/null | jq -r '.skills | sort | join(",")' +SRC=$(ss status --json 2>/dev/null | jq -r .source.path) +tail -1 "$SRC/alpha/SKILL.md" +``` + +Expected: +- alpha,beta +- # authored + +### Step 9: Track repo5 — skills only in `.agents/skills` are counted and synced + +```bash +ss install "file:///tmp/e2e-dotdir-test/repo5.git" --track --json 2>/dev/null | jq -r '.skills | sort | join(",")' +ss sync >/dev/null 2>&1 +ss list --json 2>/dev/null | jq -r '.[].name' | grep '^_repo5' +``` + +Expected: +- explainer-motion,psychopomp +- _repo5.git__.agents__skills__explainer-motion +- _repo5.git__.agents__skills__psychopomp + +### Step 10: Track repo4 — sync lists no `.agents/skills` duplicates + +```bash +ss install "file:///tmp/e2e-dotdir-test/repo4.git" --track --json 2>/dev/null | jq -r '.skills | sort | join(",")' +ss sync >/dev/null 2>&1 +ss list --json 2>/dev/null | jq -r '.[].name' | grep '^_repo4' +``` + +Expected: +- alpha,beta +- _repo4.git__skills__alpha +- _repo4.git__skills__beta +- No `_repo4.git__.agents__` entries + ## Pass Criteria -- All 7 steps pass +- All 10 steps pass - Repo 1: Only 3 source skills discovered (`.claude/` and `.cursor/` copies excluded) - Repo 2: 3 skills from `.curated/` and `.system/` discovered; `.claude/` copy excluded - Repo 3: Only 1 skill; `.skillshare/` directory entirely skipped +- Repo 4: Only the `skills/` copies are installed and synced; `.agents/skills/` copies excluded +- Repo 5: Both `.agents/skills/` skills are counted on tracked install and synced diff --git a/internal/install/install_discovery.go b/internal/install/install_discovery.go index 0f0c49028..872e9d1de 100644 --- a/internal/install/install_discovery.go +++ b/internal/install/install_discovery.go @@ -7,6 +7,7 @@ import ( "strings" "skillshare/internal/skillignore" + "skillshare/internal/sourcewalk" "skillshare/internal/utils" "skillshare/internal/validate" ) @@ -242,7 +243,7 @@ func applySkillInstallNames(skills []SkillInfo, repoPath, rootName string) { func discoverSkillsByDirectory(repoPath string, includeRoot bool) []SkillInfo { var skills []SkillInfo - filepath.Walk(repoPath, func(path string, info os.FileInfo, err error) error { + visit := func(path string, info os.FileInfo, err error) error { if err != nil { return nil } @@ -285,7 +286,13 @@ func discoverSkillsByDirectory(repoPath string, includeRoot bool) []SkillInfo { } return nil - }) + } + filepath.Walk(repoPath, visit) + if len(skills) == 0 { + if dir, ok := sourcewalk.AgentsSkillsDir(repoPath, TargetDotDirs); ok { + filepath.Walk(dir, visit) + } + } // Apply .skillignore filtering. // Skill paths are directories (they contain SKILL.md), so pass isDir=true. diff --git a/internal/install/install_test.go b/internal/install/install_test.go index c3a430a94..acd1fbc90 100644 --- a/internal/install/install_test.go +++ b/internal/install/install_test.go @@ -8,10 +8,73 @@ import ( "os" "os/exec" "path/filepath" + "slices" "strings" "testing" ) +func TestDiscoverSkills_RepoAgentsSkills(t *testing.T) { + orig := TargetDotDirs + TargetDotDirs = map[string]bool{".agents": true, ".claude": true} + defer func() { TargetDotDirs = orig }() + + tests := []struct { + name string + skills []string + ignore string + want []string + }{ + { + name: "only .agents/skills", + skills: []string{".agents/skills/one", ".agents/skills/two", ".agents/other/no", ".agents/skills/one/.claude/skills/no"}, + want: []string{".agents/skills/one", ".agents/skills/two"}, + }, + { + name: "skills and .agents/skills copies", + skills: []string{"skills/x", ".agents/skills/x"}, + want: []string{"skills/x"}, + }, + { + name: ".agents/skills skill ignored", + skills: []string{".agents/skills/one", ".agents/skills/two"}, + ignore: ".agents/skills/two\n", + want: []string{".agents/skills/one"}, + }, + { + name: "authored skills ignored", + skills: []string{"skills/x", ".agents/skills/x"}, + ignore: "skills/x\n", + want: nil, + }, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + repo := t.TempDir() + for _, p := range tt.skills { + dir := filepath.Join(repo, p) + if err := os.MkdirAll(dir, 0755); err != nil { + t.Fatal(err) + } + if err := os.WriteFile(filepath.Join(dir, "SKILL.md"), []byte("# Skill"), 0644); err != nil { + t.Fatal(err) + } + } + if tt.ignore != "" { + if err := os.WriteFile(filepath.Join(repo, ".skillignore"), []byte(tt.ignore), 0644); err != nil { + t.Fatal(err) + } + } + var got []string + for _, skill := range discoverSkills(repo, true) { + got = append(got, skill.Path) + } + if !slices.Equal(got, tt.want) { + t.Errorf("discoverSkills() = %v, want %v", got, tt.want) + } + }) + } +} + func TestDiscoverSkills_RootOnly(t *testing.T) { // Setup: repo with SKILL.md at root only repoPath := t.TempDir() diff --git a/internal/install/install_tracked_test.go b/internal/install/install_tracked_test.go index d3702a188..77e38f083 100644 --- a/internal/install/install_tracked_test.go +++ b/internal/install/install_tracked_test.go @@ -648,6 +648,48 @@ func TestInstallTrackedRepo_UpdateAcceptsSourceThatIsTheDestination(t *testing.T } } +// TestInstallTrackedRepo_CountsRepoAgentsSkills covers issue #800: a repo that +// authors its skills only in .agents/skills reports them on install and update. +func TestInstallTrackedRepo_CountsRepoAgentsSkills(t *testing.T) { + if _, err := exec.LookPath("git"); err != nil { + t.Skip("git not available") + } + orig := TargetDotDirs + TargetDotDirs = map[string]bool{".agents": true} + defer func() { TargetDotDirs = orig }() + + tmp := t.TempDir() + work := filepath.Join(tmp, "work") + mustRunGit(t, "", "init", "-b", "main", work) + mustRunGit(t, work, "config", "user.email", "test@test.com") + mustRunGit(t, work, "config", "user.name", "Test") + for _, name := range []string{"one", "two"} { + dir := filepath.Join(work, ".agents", "skills", name) + if err := os.MkdirAll(dir, 0755); err != nil { + t.Fatal(err) + } + if err := os.WriteFile(filepath.Join(dir, "SKILL.md"), []byte("# "+name), 0644); err != nil { + t.Fatal(err) + } + } + mustRunGit(t, work, "add", ".") + mustRunGit(t, work, "commit", "-m", "init") + remote := filepath.Join(tmp, "remote.git") + mustRunGit(t, "", "clone", "--bare", work, remote) + + source := &Source{Type: SourceTypeGitHTTPS, Raw: fileURL(remote), CloneURL: fileURL(remote)} + sourceDir := t.TempDir() + for _, opts := range []InstallOptions{{Name: "foo"}, {Name: "foo", Update: true}} { + result, err := InstallTrackedRepo(source, sourceDir, opts) + if err != nil { + t.Fatalf("InstallTrackedRepo(update=%t): %v", opts.Update, err) + } + if result.SkillCount != 2 { + t.Errorf("update=%t: SkillCount = %d (%v), want 2", opts.Update, result.SkillCount, result.Skills) + } + } +} + func TestInstallTrackedRepo_ForceReportsRootSkillUnderFinalName(t *testing.T) { remoteURL := makeRemote(t, "") sourceDir := t.TempDir() diff --git a/internal/sourcewalk/allowlist.json b/internal/sourcewalk/allowlist.json index e41aeeaab..903b60831 100644 --- a/internal/sourcewalk/allowlist.json +++ b/internal/sourcewalk/allowlist.json @@ -527,6 +527,14 @@ "reason": "clone", "note": "Discover skills in downloaded repository; followed repo-root consumer deferred to step 3" }, + { + "file": "internal/install/install_discovery.go", + "function": "discoverSkillsByDirectory", + "callee": "filepath.Walk", + "root": "dir", + "reason": "clone", + "note": "Repository-root .agents/skills when the repository has no other skills" + }, { "file": "internal/install/install_discovery.go", "function": "scanAgentDir", @@ -807,6 +815,14 @@ "reason": "sourcewalk", "note": "Contents of a first-level link the follow policy validated; paths are remapped to the logical link path" }, + { + "file": "internal/sourcewalk/walk.go", + "function": "AgentsSkillsDir", + "callee": "filepath.Walk", + "root": "root", + "reason": "git-root", + "note": "Check whether a repository has skills outside .agents and target dot dirs" + }, { "file": "internal/sync/agent_sync.go", "function": "FindLocalAgents", @@ -983,6 +999,14 @@ "reason": "target", "note": "Merge existing target contents into source during migration" }, + { + "file": "internal/sync/discover_walk.go", + "function": "walkRepoAgentsSkills", + "callee": "filepath.Walk", + "root": "dir", + "reason": "git-root", + "note": "Tracked repository's .agents/skills when the repository has no other skills; links are not followed" + }, { "file": "internal/targetsummary/agents.go", "function": "countHealthyAgentLinks", diff --git a/internal/sourcewalk/walk.go b/internal/sourcewalk/walk.go index 97f3f3215..834bd8b3f 100644 --- a/internal/sourcewalk/walk.go +++ b/internal/sourcewalk/walk.go @@ -4,6 +4,7 @@ package sourcewalk import ( + "errors" "io/fs" "os" "path/filepath" @@ -30,6 +31,42 @@ func SkipTargetDotDir(walkRoot, path string, info os.FileInfo) bool { return filepath.Dir(path) != walkRoot } +var errSkillFound = errors.New("skill found") + +// AgentsSkillsDir returns repoRoot/.agents/skills when the repository authors +// its skills there. .agents is usually a target copy of skills/, so it counts +// only when no SKILL.md exists elsewhere in the repository outside .git and +// the target dot dirs in dotDirs. Ignore rules are not applied: a repository +// whose authored skills are all ignored must not fall back to its copies. +func AgentsSkillsDir(repoRoot string, dotDirs map[string]bool) (string, bool) { + if !dotDirs[".agents"] { + return "", false + } + dir := filepath.Join(repoRoot, ".agents", "skills") + if info, err := os.Lstat(dir); err != nil || !info.IsDir() { + return "", false + } + // Scan the resolved root: filepath.Walk does not descend into a root that + // is a link, which would hide the authored skills of a linked repository. + root := utils.ResolveSymlink(repoRoot) + err := filepath.Walk(root, func(path string, info os.FileInfo, err error) error { + if err != nil { + return nil + } + if info.IsDir() && path != root && (info.Name() == ".git" || dotDirs[info.Name()]) { + return filepath.SkipDir + } + if !info.IsDir() && info.Name() == "SKILL.md" { + return errSkillFound + } + return nil + }) + if err != nil { + return "", false + } + return dir, true +} + // Options is the operation's traversal policy. The zero value follows no links. type Options struct { // Follow, when set, follows directory links directly under the source root. diff --git a/internal/sourcewalk/walk_test.go b/internal/sourcewalk/walk_test.go index a8a0fc1f3..7dfde49b5 100644 --- a/internal/sourcewalk/walk_test.go +++ b/internal/sourcewalk/walk_test.go @@ -246,3 +246,41 @@ func TestReadDirLogicalErrorPaths(t *testing.T) { t.Fatalf("ReadDir error: %v != %v", gotErr, wantErr) } } + +// TestAgentsSkillsDirThroughLinkedRoot checks that a repository reached +// through a link (a followed source link, or `install ./link`) is scanned +// for authored skills instead of being treated as empty. +func TestAgentsSkillsDirThroughLinkedRoot(t *testing.T) { + dotDirs := map[string]bool{".agents": true} + for _, tt := range []struct { + name string + skills []string + want bool + }{ + {"authored skills", []string{"skills/x", ".agents/skills/x"}, false}, + {"only .agents/skills", []string{".agents/skills/x"}, true}, + } { + t.Run(tt.name, func(t *testing.T) { + repo := t.TempDir() + for _, p := range tt.skills { + if err := os.MkdirAll(filepath.Join(repo, p), 0755); err != nil { + t.Fatal(err) + } + if err := os.WriteFile(filepath.Join(repo, p, "SKILL.md"), []byte("# x"), 0644); err != nil { + t.Fatal(err) + } + } + link := filepath.Join(t.TempDir(), "repo") + if err := os.Symlink(repo, link); err != nil { + t.Fatal(err) + } + dir, ok := AgentsSkillsDir(link, dotDirs) + if ok != tt.want { + t.Fatalf("AgentsSkillsDir() ok = %v, want %v", ok, tt.want) + } + if ok && dir != filepath.Join(link, ".agents", "skills") { + t.Errorf("AgentsSkillsDir() dir = %q, want it under the link", dir) + } + }) + } +} diff --git a/internal/sync/discover_test.go b/internal/sync/discover_test.go index 17250992a..966d447d7 100644 --- a/internal/sync/discover_test.go +++ b/internal/sync/discover_test.go @@ -1,6 +1,7 @@ package sync import ( + "fmt" "os" "path/filepath" "strings" @@ -100,6 +101,115 @@ func TestDiscoverSourceSkills_SkipsTargetDotDirs(t *testing.T) { } } +func TestDiscoverSourceSkills_TrackedRepoAgentsSkills(t *testing.T) { + orig := sourcewalk.TargetDotDirs + sourcewalk.TargetDotDirs = map[string]bool{".agents": true, ".claude": true} + defer func() { sourcewalk.TargetDotDirs = orig }() + src := t.TempDir() + // _repo authors its skills only in .agents/skills; _both ships + // .agents/skills copies of its skills/ and _ignored ignores its only + // authored skill, so neither falls back to the copies. + repos := map[string][]string{ + "_repo": {".agents", ".agents/skills/one", ".agents/skills/two", ".agents/other/no", ".agents/skills/one/.claude/skills/no", ".claude/skills/no"}, + "_both": {"skills/regular", ".agents/skills/regular", "skills/regular/.agents/skills/no"}, + "_ignored": {"skills/hidden", ".agents/skills/hidden"}, + } + for name, paths := range repos { + repo := filepath.Join(src, name) + if err := os.MkdirAll(filepath.Join(repo, ".git"), 0755); err != nil { + t.Fatal(err) + } + for _, p := range paths { + writeSkillMD(t, filepath.Join(repo, p), "---\nname: test\n---\n") + } + } + if err := os.WriteFile(filepath.Join(src, "_ignored", ".skillignore"), []byte("skills/hidden\n"), 0644); err != nil { + t.Fatal(err) + } + for _, discover := range []struct { + name string + run func(string) ([]DiscoveredSkill, error) + }{ + {"full", func(s string) ([]DiscoveredSkill, error) { return DiscoverSourceSkills(s) }}, + {"lite", func(s string) ([]DiscoveredSkill, error) { + skills, _, err := DiscoverSourceSkillsLite(s) + return skills, err + }}, + {"stats", func(s string) ([]DiscoveredSkill, error) { + skills, _, err := DiscoverSourceSkillsWithStats(s) + return skills, err + }}, + {"all", func(s string) ([]DiscoveredSkill, error) { return DiscoverSourceSkillsAll(s) }}, + } { + t.Run(discover.name, func(t *testing.T) { + skills, err := discover.run(src) + if err != nil { + t.Fatal(err) + } + got := map[string]bool{} + for _, s := range skills { + if s.Disabled { + continue + } + got[s.RelPath] = true + repo, _, _ := strings.Cut(s.RelPath, "/") + if !s.IsInRepo || s.RepoRelPath != repo || s.SourcePath != filepath.Join(src, s.RelPath) { + t.Errorf("incorrect tracked identity: %+v", s) + } + if s.FlatName != strings.ReplaceAll(s.RelPath, "/", "__") { + t.Errorf("incorrect flattened name: %+v", s) + } + } + for _, p := range []string{"_repo/.agents/skills/one", "_repo/.agents/skills/two", "_both/skills/regular"} { + if !got[p] { + t.Errorf("missing %s: %v", p, got) + } + } + if len(got) != 3 { + t.Errorf("unexpected skills: %v", got) + } + }) + } +} + +func TestDiscoverSourceSkills_RepoAgentsSkillsIgnoreAndLinks(t *testing.T) { + orig := sourcewalk.TargetDotDirs + sourcewalk.TargetDotDirs = map[string]bool{".agents": true} + defer func() { sourcewalk.TargetDotDirs = orig }() + + for _, tracked := range []bool{false, true} { + t.Run(fmt.Sprintf("tracked=%t", tracked), func(t *testing.T) { + src := t.TempDir() + repo := src + prefix := "" + if tracked { + repo = filepath.Join(src, "group", "_repo") + prefix = "group/_repo/" + if err := os.MkdirAll(filepath.Join(repo, ".git"), 0755); err != nil { + t.Fatal(err) + } + } + writeSkillMD(t, filepath.Join(repo, ".agents/skills/visible"), "# Visible") + writeSkillMD(t, filepath.Join(repo, ".agents/skills/ignored"), "# Ignored") + if err := os.WriteFile(filepath.Join(repo, ".skillignore"), []byte(".agents/skills/ignored\n"), 0644); err != nil { + t.Fatal(err) + } + outside := t.TempDir() + writeSkillMD(t, outside, "# Linked") + if err := os.Symlink(outside, filepath.Join(repo, ".agents/skills/linked")); err != nil { + t.Fatal(err) + } + skills, err := DiscoverSourceSkills(src) + if err != nil { + t.Fatal(err) + } + if len(skills) != 1 || skills[0].RelPath != prefix+".agents/skills/visible" { + t.Fatalf("expected only the visible skill, got %+v", skills) + } + }) + } +} + func TestDiscoverSourceSkills_SourceRootNamedAsTargetDotDir(t *testing.T) { orig := sourcewalk.TargetDotDirs sourcewalk.TargetDotDirs = map[string]bool{".claude": true, ".skillshare": true} diff --git a/internal/sync/discover_walk.go b/internal/sync/discover_walk.go index 8eff1434e..ebe32bcc5 100644 --- a/internal/sync/discover_walk.go +++ b/internal/sync/discover_walk.go @@ -178,7 +178,7 @@ func discoverSourceSkillsInternal(sourcePath string, opts discoverOptions) ([]Di } } - err := sourcewalk.Walk(walkRoot, opts.walk, func(path string, info os.FileInfo, err error) error { + visit := func(path string, info os.FileInfo, err error) error { if err != nil { return nil // Skip inaccessible paths } @@ -345,8 +345,11 @@ func discoverSourceSkillsInternal(sourcePath string, opts discoverOptions) ([]Di } return nil - }) - + } + err := sourcewalk.Walk(walkRoot, opts.walk, visit) + if err == nil { + err = walkRepoAgentsSkills(walkRoot, repoRoots, skills, visit) + } if err != nil { return nil, nil, nil, fmt.Errorf("failed to walk source directory: %w", err) } @@ -359,6 +362,32 @@ func discoverSourceSkillsInternal(sourcePath string, opts discoverOptions) ([]Di return skills, trackedRepos, stats, nil } +// walkRepoAgentsSkills walks the .agents/skills directory of each tracked repo +// that yielded no skills, for repositories that author their skills only there. +func walkRepoAgentsSkills(walkRoot string, repoRoots map[string]bool, skills []DiscoveredSkill, visit filepath.WalkFunc) error { + found := make(map[string]bool, len(repoRoots)) + for _, s := range skills { + found[s.RepoRelPath] = true + } + roots := make([]string, 0, len(repoRoots)) + for root := range repoRoots { + if !found[root] { + roots = append(roots, root) + } + } + sort.Strings(roots) + for _, root := range roots { + dir, ok := sourcewalk.AgentsSkillsDir(filepath.Join(walkRoot, filepath.FromSlash(root)), sourcewalk.TargetDotDirs) + if !ok { + continue + } + if err := filepath.Walk(dir, visit); err != nil { + return err + } + } + return nil +} + // applyTargetOverrides replaces the frontmatter targets of tracked-repo skills // with the overrides stored in the source's .metadata.json, so every consumer // of discovery sees the same effective targets. An empty override means all diff --git a/skills/skillshare/references/install.md b/skills/skillshare/references/install.md index cd6502b42..cd2511ccf 100644 --- a/skills/skillshare/references/install.md +++ b/skills/skillshare/references/install.md @@ -13,6 +13,10 @@ a valid `SKILL.md` frontmatter `name` is used, lowercased with spaces normalized or conflicting frontmatter names fall back to the directory name. `--name` overrides the default; updates preserve existing install names. Tracked repository naming is unchanged. +Discovery skips target directories such as `.claude/` and `.agents/`, which usually +hold copies of a repository's skills. A repository with no other skills has its +root `.agents/skills/` discovered instead. + ### Source Formats ```bash diff --git a/website/docs/reference/commands/install.md b/website/docs/reference/commands/install.md index 9bfcbc23e..a992b4cd6 100644 --- a/website/docs/reference/commands/install.md +++ b/website/docs/reference/commands/install.md @@ -129,7 +129,7 @@ $ skillshare install anthropics/skills ↑↓ move · space toggle · ctrl+a all · enter confirm · / filter · esc cancel ``` -Discovery scans all directories for `SKILL.md` files, skipping only `.git`. This means skills inside hidden directories like `.curated/` or `.system/` are discovered automatically. When multiple skills are found, the prompt lists skills from the same folder together and shows each one's description and folder; press `/` to narrow a long list. +Discovery scans all directories for `SKILL.md` files except `.git` and target directories such as `.claude/` and `.agents/`, which usually hold copies of the repository's skills. Other hidden directories like `.curated/` or `.system/` are scanned, so their skills are discovered automatically. A repository with no other skills has its root `.agents/skills/` scanned instead. When multiple skills are found, the prompt lists skills from the same folder together and shows each one's description and folder; press `/` to narrow a long list. If the repository contains a `.skillignore` file at its root, matching skills are automatically excluded from discovery. See [.skillignore](#skillignore) below. diff --git a/website/docs/understand/tracked-repositories.md b/website/docs/understand/tracked-repositories.md index 30838ad35..103e2cfac 100644 --- a/website/docs/understand/tracked-repositories.md +++ b/website/docs/understand/tracked-repositories.md @@ -109,6 +109,8 @@ _team-skills/ Auto-flattening works for **all skills**, not just tracked repos. You can organize your personal skills in folders too. See [Organize with Folders](/docs/understand/source-and-targets#organize-with-folders-auto-flattening). ::: +Target directories inside a tracked repo, such as `.claude/skills/` or `.agents/skills/`, usually hold copies of the repo's skills, so sync skips them. The exception is a repo whose only skills are in its root `.agents/skills/`: those skills are discovered, so `_psychopomp/.agents/skills/explainer-motion/` syncs as `_psychopomp__.agents__skills__explainer-motion`. + --- ## Rehydrating After a Fresh Clone {#rehydrating-after-a-fresh-clone} diff --git a/website/i18n/ja/docusaurus-plugin-content-docs/current/reference/commands/install.md b/website/i18n/ja/docusaurus-plugin-content-docs/current/reference/commands/install.md index 3a3081722..79ea263cb 100644 --- a/website/i18n/ja/docusaurus-plugin-content-docs/current/reference/commands/install.md +++ b/website/i18n/ja/docusaurus-plugin-content-docs/current/reference/commands/install.md @@ -127,7 +127,7 @@ $ skillshare install anthropics/skills ↑↓ move · space toggle · ctrl+a all · enter confirm · / filter · esc cancel ``` -ディスカバリーは `.git` のみをスキップし、すべてのディレクトリを `SKILL.md` ファイルについてスキャンします。つまり、`.curated/` や `.system/` のような隠しディレクトリ内の Skill も自動的に検出されます。複数の Skill が見つかった場合、選択プロンプトは同じフォルダの Skill をまとめて並べ、各 Skill の説明とフォルダを表示します。リストが長いときは `/` で絞り込めます。 +ディスカバリーは、`.git` と、通常リポジトリの Skill のコピーを置く `.claude/` や `.agents/` などのターゲットディレクトリを除き、すべてのディレクトリを `SKILL.md` ファイルについてスキャンします。`.curated/` や `.system/` のようなその他の隠しディレクトリはスキャンされるため、その中の Skill も自動的に検出されます。ほかに Skill がないリポジトリでは、代わりにルートの `.agents/skills/` がスキャンされます。複数の Skill が見つかった場合、選択プロンプトは同じフォルダの Skill をまとめて並べ、各 Skill の説明とフォルダを表示します。リストが長いときは `/` で絞り込めます。 リポジトリのルートに `.skillignore` ファイルがある場合、一致する Skill はディスカバリーから自動的に除外されます。詳細は下記の [.skillignore](#skillignore) を参照してください。 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 038938d7d..e8015930d 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 @@ -109,6 +109,8 @@ _team-skills/ 自動フラット化は追跡リポジトリだけでなく、**すべての Skill** で機能します。個人の Skill もフォルダで整理できます。詳しくは [フォルダで整理する](/docs/understand/source-and-targets#organize-with-folders-auto-flattening) を参照してください。 ::: +追跡リポジトリ内の `.claude/skills/` や `.agents/skills/` などのターゲットディレクトリには通常リポジトリの Skill のコピーが置かれるため、sync はそれらをスキップします。例外は Skill がルートの `.agents/skills/` にしかないリポジトリで、その Skill は検出されます。たとえば `_psychopomp/.agents/skills/explainer-motion/` は `_psychopomp__.agents__skills__explainer-motion` として同期されます。 + --- ## 新規クローン後の復元 {#rehydrating-after-a-fresh-clone} diff --git a/website/i18n/ko/docusaurus-plugin-content-docs/current/reference/commands/install.md b/website/i18n/ko/docusaurus-plugin-content-docs/current/reference/commands/install.md index 8a8ad583c..2866cca11 100644 --- a/website/i18n/ko/docusaurus-plugin-content-docs/current/reference/commands/install.md +++ b/website/i18n/ko/docusaurus-plugin-content-docs/current/reference/commands/install.md @@ -127,7 +127,7 @@ $ skillshare install anthropics/skills ↑↓ move · space toggle · ctrl+a all · enter confirm · / filter · esc cancel ``` -Discovery는 `.git`만 건너뛰고 모든 디렉터리에서 `SKILL.md` 파일을 스캔합니다. 즉 `.curated/`나 `.system/`과 같은 숨김 디렉터리 안의 skill도 자동으로 발견됩니다. 여러 skill이 발견되면, 선택 화면은 같은 폴더의 skill을 함께 나열하고 각 skill의 설명과 폴더를 보여 줍니다. 목록이 길면 `/`로 필터링할 수 있습니다. +Discovery는 `.git`과, 보통 저장소 skill의 복사본을 담는 `.claude/`, `.agents/` 같은 타깃 디렉터리를 제외한 모든 디렉터리에서 `SKILL.md` 파일을 스캔합니다. `.curated/`나 `.system/`과 같은 그 밖의 숨김 디렉터리는 스캔되므로 그 안의 skill도 자동으로 발견됩니다. 다른 skill이 없는 저장소는 대신 루트의 `.agents/skills/`를 스캔합니다. 여러 skill이 발견되면, 선택 화면은 같은 폴더의 skill을 함께 나열하고 각 skill의 설명과 폴더를 보여 줍니다. 목록이 길면 `/`로 필터링할 수 있습니다. repository 루트에 `.skillignore` 파일이 있으면, 일치하는 skill은 discovery에서 자동으로 제외됩니다. 아래 [.skillignore](#skillignore)를 참고하세요. 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 04ed8988e..275a3c477 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 @@ -109,6 +109,8 @@ _team-skills/ 자동 평탄화는 **모든 skill**에 적용되며, tracked repo에만 국한되지 않습니다. 개인 skill도 폴더로 정리할 수 있습니다. [폴더로 정리하기](/docs/understand/source-and-targets#organize-with-folders-auto-flattening)를 참고하세요. ::: +tracked repo 안의 `.claude/skills/`나 `.agents/skills/` 같은 타깃 디렉터리는 보통 repo skill의 복사본을 담고 있으므로 sync가 건너뜁니다. 예외는 skill이 루트의 `.agents/skills/`에만 있는 repo로, 이 경우 그 skill이 발견됩니다. 예를 들어 `_psychopomp/.agents/skills/explainer-motion/`은 `_psychopomp__.agents__skills__explainer-motion`으로 동기화됩니다. + --- ## 새 Clone 이후 복구하기 {#rehydrating-after-a-fresh-clone} diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/commands/install.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/commands/install.md index 7d195bf05..2097c6d89 100644 --- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/commands/install.md +++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/commands/install.md @@ -127,7 +127,7 @@ $ skillshare install anthropics/skills ↑↓ move · space toggle · ctrl+a all · enter confirm · / filter · esc cancel ``` -Discovery 会扫描所有目录以查找 `SKILL.md` 文件,仅跳过 `.git`。这意味着位于隐藏目录(如 `.curated/` 或 `.system/`)中的 Skill 也会被自动发现。当发现多个 Skill 时,选择提示会把同一文件夹中的 Skill 排在一起,并显示每个 Skill 的描述和所在文件夹;列表较长时按 `/` 筛选。 +Discovery 会扫描所有目录以查找 `SKILL.md` 文件,但会跳过 `.git` 以及 `.claude/`、`.agents/` 等目标目录,这些目录通常存放仓库中 Skill 的副本。其他隐藏目录(如 `.curated/` 或 `.system/`)会被扫描,其中的 Skill 也会被自动发现。如果仓库没有其他 Skill,则改为扫描根目录的 `.agents/skills/`。当发现多个 Skill 时,选择提示会把同一文件夹中的 Skill 排在一起,并显示每个 Skill 的描述和所在文件夹;列表较长时按 `/` 筛选。 如果仓库根目录下存在 `.skillignore` 文件,匹配的 Skill 会被自动从 discovery 中排除。参见下方的 [.skillignore](#skillignore)。 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 1c7693cd6..38d3bab6e 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 @@ -109,6 +109,8 @@ _team-skills/ 自动扁平化适用于**所有 Skill**,不仅限于 Tracked Repo。你也可以用文件夹组织自己的 Skill。参见 [Organize with Folders](/docs/understand/source-and-targets#organize-with-folders-auto-flattening)。 ::: +Tracked Repo 中的 `.claude/skills/`、`.agents/skills/` 等目标目录通常存放 repo 中 Skill 的副本,因此 sync 会跳过它们。例外是 Skill 只位于根目录 `.agents/skills/` 的 repo:这些 Skill 会被发现,例如 `_psychopomp/.agents/skills/explainer-motion/` 会同步为 `_psychopomp__.agents__skills__explainer-motion`。 + --- ## 全新克隆后的重新水合(Rehydrating) {#rehydrating-after-a-fresh-clone} diff --git a/website/i18n/zh-Hant/docusaurus-plugin-content-docs/current/reference/commands/install.md b/website/i18n/zh-Hant/docusaurus-plugin-content-docs/current/reference/commands/install.md index 4ff57a599..e04d753be 100644 --- a/website/i18n/zh-Hant/docusaurus-plugin-content-docs/current/reference/commands/install.md +++ b/website/i18n/zh-Hant/docusaurus-plugin-content-docs/current/reference/commands/install.md @@ -127,7 +127,7 @@ $ skillshare install anthropics/skills ↑↓ move · space toggle · ctrl+a all · enter confirm · / filter · esc cancel ``` -Discovery 會掃描所有目錄尋找 `SKILL.md` 檔案,只跳過 `.git`。這代表 `.curated/` 或 `.system/` 之類隱藏目錄中的 skills 也會被自動發現。當找到多個 skills 時,選擇提示會把同一個資料夾的 skills 排在一起,並顯示每個 skill 的說明與所在資料夾;清單很長時按 `/` 篩選。 +Discovery 會掃描所有目錄尋找 `SKILL.md` 檔案,但會跳過 `.git` 以及 `.claude/`、`.agents/` 等 target 目錄,這些目錄通常放的是 repo 中 skills 的副本。其他隱藏目錄(如 `.curated/` 或 `.system/`)會被掃描,其中的 skills 也會被自動發現。如果 repo 沒有其他 skills,則改為掃描根目錄的 `.agents/skills/`。當找到多個 skills 時,選擇提示會把同一個資料夾的 skills 排在一起,並顯示每個 skill 的說明與所在資料夾;清單很長時按 `/` 篩選。 如果 repository 根目錄有 `.skillignore` 檔案,符合的 skills 會自動從 discovery 中排除。見下方 [.skillignore](#skillignore)。 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 06b1833b5..ae872319e 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 @@ -109,6 +109,8 @@ _team-skills/ 自動扁平化適用於**所有 skills**,不只是 tracked repos。你也可以用資料夾整理自己的個人 skills。詳見 [Organize with Folders](/docs/understand/source-and-targets#organize-with-folders-auto-flattening)。 ::: +Tracked repo 中的 `.claude/skills/`、`.agents/skills/` 等 target 目錄通常放的是 repo 中 skills 的副本,所以 sync 會跳過它們。例外是 skills 只放在根目錄 `.agents/skills/` 的 repo:這些 skills 會被發現,例如 `_psychopomp/.agents/skills/explainer-motion/` 會同步為 `_psychopomp__.agents__skills__explainer-motion`。 + --- ## 全新 Clone 之後的復原 {#rehydrating-after-a-fresh-clone}