fix(discovery): find repository-root .agents/skills (#801)

A repository-root .agents/skills now counts as a skill anchor only when the repository has no other SKILL.md outside .git and target directories, so tracked checkouts that author skills there are discovered, while repos that commit .agents/skills copies keep discovering only their authored skills.

Fixes #800
This commit is contained in:
Rusty Shackleford
2026-11-10 16:04:20 +08:00
committed by GitHub
parent cafd99e595
commit 71ff2d9e14
20 changed files with 438 additions and 13 deletions
@@ -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
+9 -2
View File
@@ -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.
+63
View File
@@ -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()
+42
View File
@@ -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()
+24
View File
@@ -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",
+37
View File
@@ -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.
+38
View File
@@ -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)
}
})
}
}
+110
View File
@@ -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}
+32 -3
View File
@@ -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
+4
View File
@@ -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
+1 -1
View File
@@ -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.
@@ -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}
@@ -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) を参照してください。
@@ -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}
@@ -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)를 참고하세요.
@@ -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}
@@ -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)。
@@ -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}
@@ -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)。
@@ -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}