feat(skills): support recursive nested skill loading (#950)

* feat(skills): support recursive nested skill loading

* Apply suggestions from code review

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

---------

Co-authored-by: Willem Jiang <willem.jiang@gmail.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

backend/src/skills/loader.py

@@ -1,3 +1,4 @@
+import os
 from pathlib import Path
 
 from .parser import parse_skill_file
@@ -59,16 +60,16 @@ def load_skills(skills_path: Path | None = None, use_config: bool = True, enable
         if not category_path.exists() or not category_path.is_dir():
             continue
 
-        # Each subdirectory is a potential skill
-        for skill_dir in category_path.iterdir():
-            if not skill_dir.is_dir():
+        for current_root, dir_names, file_names in os.walk(category_path):
+            # Keep traversal deterministic and skip hidden directories.
+            dir_names[:] = sorted(name for name in dir_names if not name.startswith("."))
+            if "SKILL.md" not in file_names:
                 continue
 
-            skill_file = skill_dir / "SKILL.md"
-            if not skill_file.exists():
-                continue
+            skill_file = Path(current_root) / "SKILL.md"
+            relative_path = skill_file.parent.relative_to(category_path)
 
-            skill = parse_skill_file(skill_file, category=category)
+            skill = parse_skill_file(skill_file, category=category, relative_path=relative_path)
             if skill:
                 skills.append(skill)
 

backend/src/skills/parser.py

@@ -4,7 +4,7 @@ from pathlib import Path
 from .types import Skill
 
 
-def parse_skill_file(skill_file: Path, category: str) -> Skill | None:
+def parse_skill_file(skill_file: Path, category: str, relative_path: Path | None = None) -> Skill | None:
     """
     Parse a SKILL.md file and extract metadata.
 
@@ -55,6 +55,7 @@ def parse_skill_file(skill_file: Path, category: str) -> Skill | None:
             license=license_text,
             skill_dir=skill_file.parent,
             skill_file=skill_file,
+            relative_path=relative_path or Path(skill_file.parent.name),
             category=category,
             enabled=True,  # Default to enabled, actual state comes from config file
         )

backend/src/skills/types.py

@@ -11,13 +11,15 @@ class Skill:
     license: str | None
     skill_dir: Path
     skill_file: Path
+    relative_path: Path  # Relative path from category root to skill directory
     category: str  # 'public' or 'custom'
     enabled: bool = False  # Whether this skill is enabled
 
     @property
     def skill_path(self) -> str:
-        """Returns the relative path from skills root to this skill's directory"""
-        return self.skill_dir.name
+        """Returns the relative path from the category root (skills/{category}) to this skill's directory"""
+        path = self.relative_path.as_posix()
+        return "" if path == "." else path
 
     def get_container_path(self, container_base_path: str = "/mnt/skills") -> str:
         """
@@ -29,7 +31,11 @@ class Skill:
         Returns:
             Full container path to the skill directory
         """
-        return f"{container_base_path}/{self.category}/{self.skill_dir.name}"
+        category_base = f"{container_base_path}/{self.category}"
+        skill_path = self.skill_path
+        if skill_path:
+            return f"{category_base}/{skill_path}"
+        return category_base
 
     def get_container_file_path(self, container_base_path: str = "/mnt/skills") -> str:
         """
@@ -41,7 +47,7 @@ class Skill:
         Returns:
             Full container path to the skill's SKILL.md file
         """
-        return f"{container_base_path}/{self.category}/{self.skill_dir.name}/SKILL.md"
+        return f"{self.get_container_path(container_base_path)}/SKILL.md"
 
     def __repr__(self) -> str:
         return f"Skill(name={self.name!r}, description={self.description!r}, category={self.category!r})"