Merge pull request #1631 from dgageot/fix-1616

Support recursive ~/.agents/skills

Author: rumpl

docs/USAGE.md

@@ -1117,7 +1117,7 @@ Skills are automatically discovered from the following locations (in order, late
 **Global locations** (from home directory):
 - `~/.codex/skills/` — Recursive search (Codex format)
 - `~/.claude/skills/` — Flat search (Claude format)
-- `~/.agents/skills/` — Flat search (Agent Skills standard)
+- `~/.agents/skills/` — Recursive search (Agent Skills standard)
 
 **Project locations** (from git root up to current directory):
 - `.claude/skills/` — Flat search, only at current working directory

pkg/skills/skills.go

@@ -32,7 +32,7 @@ type Skill struct {
 // Global locations (from home directory):
 //   - ~/.codex/skills/ (recursive)
 //   - ~/.claude/skills/ (flat)
-//   - ~/.agents/skills/ (flat)
+//   - ~/.agents/skills/ (recursive)
 //
 // Project locations (from git root up to cwd, closest wins):
 //   - .claude/skills/ (flat, only at cwd)
@@ -50,8 +50,8 @@ func Load() []Skill {
 		for _, skill := range loadSkillsFromDir(filepath.Join(homeDir, ".claude", "skills"), false) {
 			skillMap[skill.Name] = skill
 		}
-		// Load from agents user directory (flat)
-		for _, skill := range loadSkillsFromDir(filepath.Join(homeDir, ".agents", "skills"), false) {
+		// Load from agents user directory (recursive)
+		for _, skill := range loadSkillsFromDir(filepath.Join(homeDir, ".agents", "skills"), true) {
 			skillMap[skill.Name] = skill
 		}
 	}

pkg/skills/skills_test.go

@@ -337,6 +337,62 @@ description: A global agents skill
 	assert.True(t, found, "Expected to find global-skill from ~/.agents/skills")
 }
 
+func TestLoad_AgentsSkillsGlobalRecursive(t *testing.T) {
+	// Create a temp home directory with nested .agents/skills
+	tmpHome := t.TempDir()
+	t.Setenv("HOME", tmpHome)
+
+	// Create a deeply nested skill under ~/.agents/skills/
+	nestedSkillDir := filepath.Join(tmpHome, ".agents", "skills", "project-a", "skill-one")
+	require.NoError(t, os.MkdirAll(nestedSkillDir, 0o755))
+
+	skillContent := `---
+name: skill-one
+description: A nested global agents skill
+---
+
+# Nested Skill
+`
+	require.NoError(t, os.WriteFile(filepath.Join(nestedSkillDir, "SKILL.md"), []byte(skillContent), 0o644))
+
+	// Also create a flat skill to make sure both work
+	flatSkillDir := filepath.Join(tmpHome, ".agents", "skills", "flat-skill")
+	require.NoError(t, os.MkdirAll(flatSkillDir, 0o755))
+
+	flatContent := `---
+name: flat-skill
+description: A flat global agents skill
+---
+
+# Flat Skill
+`
+	require.NoError(t, os.WriteFile(filepath.Join(flatSkillDir, "SKILL.md"), []byte(flatContent), 0o644))
+
+	// Change to a temp directory that doesn't have any skills
+	tmpCwd := t.TempDir()
+	t.Chdir(tmpCwd)
+
+	skills := Load()
+
+	// Both nested and flat skills should be found
+	foundNested := false
+	foundFlat := false
+	for _, s := range skills {
+		switch s.Name {
+		case "skill-one":
+			foundNested = true
+			assert.Equal(t, "A nested global agents skill", s.Description)
+			assert.Equal(t, filepath.Join(nestedSkillDir, "SKILL.md"), s.FilePath)
+		case "flat-skill":
+			foundFlat = true
+			assert.Equal(t, "A flat global agents skill", s.Description)
+			assert.Equal(t, filepath.Join(flatSkillDir, "SKILL.md"), s.FilePath)
+		}
+	}
+	assert.True(t, foundNested, "Expected to find nested skill-one from ~/.agents/skills/project-a/skill-one")
+	assert.True(t, foundFlat, "Expected to find flat-skill from ~/.agents/skills/flat-skill")
+}
+
 func TestLoad_AgentsSkillsProjectFromNestedDir(t *testing.T) {
 	// Create a fake git repo with .agents/skills at the root
 	tmpRepo := t.TempDir()