feat(skills): support GitHub /tree/ URLs for nested skills

Parse GitHub web URLs like /tree/<ref>/path to extract the clone URL,
branch, and subdirectory path. This enables loading skills from
subdirectories within mono-repos.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: Davide Gallitelli

src/strands/vended_plugins/skills/_url_loader.py

@@ -24,6 +24,10 @@
 # Regex to strip .git suffix from URLs before ref parsing
 _GIT_SUFFIX = re.compile(r"\.git$")
 
+# Matches GitHub /tree/<ref> or /tree/<ref>/<path> (also /blob/)
+# e.g. /owner/repo/tree/main/skills/my-skill -> groups: (/owner/repo, main, skills/my-skill)
+_GITHUB_TREE_PATTERN = re.compile(r"^(/[^/]+/[^/]+)/(?:tree|blob)/([^/]+)(?:/(.+?))?/?$")
+
 
 def is_url(source: str) -> bool:
     """Check whether a skill source string looks like a remote URL.
@@ -37,31 +41,43 @@ def is_url(source: str) -> bool:
     return any(source.startswith(prefix) for prefix in _URL_PREFIXES)
 
 
-def parse_url_ref(url: str) -> tuple[str, str | None]:
-    """Parse a skill URL into a clone URL and an optional Git ref.
+def parse_url_ref(url: str) -> tuple[str, str | None, str | None]:
+    """Parse a skill URL into a clone URL, optional Git ref, and optional subpath.
 
     Supports an ``@ref`` suffix for specifying a branch, tag, or commit::
 
-        https://github.com/org/skill-repo@v1.0.0  -> (https://github.com/org/skill-repo, v1.0.0)
-        https://github.com/org/skill-repo         -> (https://github.com/org/skill-repo, None)
-        https://github.com/org/skill-repo.git@main -> (https://github.com/org/skill-repo.git, main)
-        git@github.com:org/skill-repo.git@v2      -> (git@github.com:org/skill-repo.git, v2)
+        https://github.com/org/skill-repo@v1.0.0  -> (https://github.com/org/skill-repo, v1.0.0, None)
+        https://github.com/org/skill-repo         -> (https://github.com/org/skill-repo, None, None)
+
+    Also supports GitHub web URLs with ``/tree/<ref>/path`` ::
+
+        https://github.com/org/repo/tree/main/skills/my-skill
+            -> (https://github.com/org/repo, main, skills/my-skill)
 
     Args:
-        url: The skill URL, optionally with an ``@ref`` suffix.
+        url: The skill URL, optionally with an ``@ref`` suffix or ``/tree/`` path.
 
     Returns:
-        Tuple of (clone_url, ref_or_none).
+        Tuple of (clone_url, ref_or_none, subpath_or_none).
     """
     if url.startswith(("https://", "http://", "ssh://")):
         # Find the path portion after the host
         scheme_end = url.index("//") + 2
         host_end = url.find("/", scheme_end)
         if host_end == -1:
-            return url, None
+            return url, None, None
 
         path_part = url[host_end:]
 
+        # Handle GitHub /tree/<ref>/path and /blob/<ref>/path URLs
+        tree_match = _GITHUB_TREE_PATTERN.match(path_part)
+        if tree_match:
+            owner_repo = tree_match.group(1)
+            ref = tree_match.group(2)
+            subpath = tree_match.group(3) or None
+            clone_url = url[:host_end] + owner_repo
+            return clone_url, ref, subpath
+
         # Strip .git suffix before looking for @ref so that
         # "repo.git@v1" is handled correctly
         clean_path = _GIT_SUFFIX.sub("", path_part)
@@ -73,9 +89,9 @@ def parse_url_ref(url: str) -> tuple[str, str | None]:
             base_path = clean_path[:at_idx]
             if had_git_suffix:
                 base_path += ".git"
-            return url[:host_end] + base_path, ref
+            return url[:host_end] + base_path, ref, None
 
-        return url, None
+        return url, None, None
 
     if url.startswith("git@"):
         # SSH format: git@host:owner/repo.git@ref
@@ -92,11 +108,11 @@ def parse_url_ref(url: str) -> tuple[str, str | None]:
             base_rest = clean_rest[:at_idx]
             if had_git_suffix:
                 base_rest += ".git"
-            return url[: first_at + 1] + base_rest, ref
+            return url[: first_at + 1] + base_rest, ref, None
 
-        return url, None
+        return url, None, None
 
-    return url, None
+    return url, None, None
 
 
 def cache_key(url: str, ref: str | None) -> str:
@@ -117,6 +133,7 @@ def clone_skill_repo(
     url: str,
     *,
     ref: str | None = None,
+    subpath: str | None = None,
     cache_dir: Path | None = None,
 ) -> Path:
     """Clone a skill repository to a local cache directory.
@@ -125,14 +142,19 @@ def clone_skill_repo(
     is passed as ``--branch`` (works for branches and tags). Repositories are
     cached by a hash of (url, ref) so repeated loads are instant.
 
+    If ``subpath`` is provided, the returned path points to that subdirectory
+    within the cloned repository (useful for mono-repos containing skills in
+    nested directories).
+
     Args:
         url: The Git clone URL.
         ref: Optional branch or tag to check out.
+        subpath: Optional path within the repo to return (e.g. ``skills/my-skill``).
         cache_dir: Override the default cache directory
             (``~/.cache/strands/skills/``).
 
     Returns:
-        Path to the cloned repository root.
+        Path to the cloned repository root, or to ``subpath`` within it.
 
     Raises:
         RuntimeError: If the clone fails or ``git`` is not installed.
@@ -143,32 +165,38 @@ def clone_skill_repo(
     key = cache_key(url, ref)
     target = cache_dir / key
 
-    if target.exists():
+    if not target.exists():
+        logger.info("url=<%s>, ref=<%s> | cloning skill repository", url, ref)
+
+        cmd: list[str] = ["git", "clone", "--depth", "1"]
+        if ref:
+            cmd.extend(["--branch", ref])
+        cmd.extend([url, str(target)])
+
+        try:
+            subprocess.run(  # noqa: S603
+                cmd,
+                check=True,
+                capture_output=True,
+                text=True,
+                timeout=120,
+            )
+        except subprocess.CalledProcessError as e:
+            # Clean up any partial clone
+            if target.exists():
+                shutil.rmtree(target)
+            raise RuntimeError(
+                f"url=<{url}>, ref=<{ref}> | failed to clone skill repository: {e.stderr.strip()}"
+            ) from e
+        except FileNotFoundError as e:
+            raise RuntimeError("git is required to load skills from URLs but was not found on PATH") from e
+    else:
         logger.debug("url=<%s>, ref=<%s> | using cached skill at %s", url, ref, target)
-        return target
-
-    logger.info("url=<%s>, ref=<%s> | cloning skill repository", url, ref)
-
-    cmd: list[str] = ["git", "clone", "--depth", "1"]
-    if ref:
-        cmd.extend(["--branch", ref])
-    cmd.extend([url, str(target)])
-
-    try:
-        subprocess.run(  # noqa: S603
-            cmd,
-            check=True,
-            capture_output=True,
-            text=True,
-            timeout=120,
-        )
-    except subprocess.CalledProcessError as e:
-        # Clean up any partial clone
-        if target.exists():
-            shutil.rmtree(target)
-        raise RuntimeError(f"url=<{url}>, ref=<{ref}> | failed to clone skill repository: {e.stderr.strip()}") from e
-    except FileNotFoundError as e:
-        raise RuntimeError("git is required to load skills from URLs but was not found on PATH") from e
-
-    logger.debug("url=<%s>, ref=<%s> | cloned to %s", url, ref, target)
-    return target
+
+    result = target / subpath if subpath else target
+
+    if subpath and not result.is_dir():
+        raise RuntimeError(f"url=<{url}>, subpath=<{subpath}> | subdirectory does not exist in cloned repository")
+
+    logger.debug("url=<%s>, ref=<%s> | resolved to %s", url, ref, result)
+    return result

src/strands/vended_plugins/skills/skill.py

@@ -352,8 +352,13 @@ def from_url(
 
             skills = Skill.from_url("https://github.com/org/my-skill@v1.0.0")
 
+        Also supports GitHub web URLs pointing to subdirectories::
+
+            skills = Skill.from_url("https://github.com/org/repo/tree/main/skills/my-skill")
+
         Args:
-            url: A Git-cloneable URL, optionally with an ``@ref`` suffix.
+            url: A Git-cloneable URL, optionally with an ``@ref`` suffix or
+                a GitHub ``/tree/<ref>/path`` URL.
             cache_dir: Override the default cache directory
                 (``~/.cache/strands/skills/``).
             strict: If True, raise on any validation issue. If False (default),
@@ -371,8 +376,8 @@ def from_url(
         if not is_url(url):
             raise ValueError(f"url=<{url}> | not a valid remote URL")
 
-        clean_url, ref = parse_url_ref(url)
-        repo_path = clone_skill_repo(clean_url, ref=ref, cache_dir=cache_dir)
+        clean_url, ref, subpath = parse_url_ref(url)
+        repo_path = clone_skill_repo(clean_url, ref=ref, subpath=subpath, cache_dir=cache_dir)
 
         # If the repo root is itself a skill, load it directly
         has_skill_md = (repo_path / "SKILL.md").is_file() or (repo_path / "skill.md").is_file()

tests/strands/vended_plugins/skills/test_agent_skills.py

@@ -670,7 +670,7 @@ def _mock_clone(self, tmp_path, skill_name="url-skill", description="A URL skill
         """Create a mock clone function that creates a skill directory."""
         skill_dir = tmp_path / "cloned"
 
-        def fake_clone(url, *, ref=None, cache_dir=None):
+        def fake_clone(url, *, ref=None, subpath=None, cache_dir=None):
             skill_dir.mkdir(parents=True, exist_ok=True)
             content = f"---\nname: {skill_name}\ndescription: {description}\n---\n# Instructions\n"
             (skill_dir / "SKILL.md").write_text(content)
@@ -688,7 +688,7 @@ def test_resolve_url_source(self, tmp_path):
             patch(f"{self._URL_LOADER}.clone_skill_repo", side_effect=fake_clone),
             patch(
                 f"{self._URL_LOADER}.parse_url_ref",
-                return_value=("https://github.com/org/url-skill", None),
+                return_value=("https://github.com/org/url-skill", None, None),
             ),
         ):
             plugin = AgentSkills(skills=["https://github.com/org/url-skill"])
@@ -707,7 +707,7 @@ def test_resolve_mixed_url_and_local(self, tmp_path):
             patch(f"{self._URL_LOADER}.clone_skill_repo", side_effect=fake_clone),
             patch(
                 f"{self._URL_LOADER}.parse_url_ref",
-                return_value=("https://github.com/org/url-skill", None),
+                return_value=("https://github.com/org/url-skill", None, None),
             ),
         ):
             plugin = AgentSkills(
@@ -729,7 +729,7 @@ def test_resolve_url_failure_skips_gracefully(self, caplog):
         with (
             patch(
                 f"{self._URL_LOADER}.parse_url_ref",
-                return_value=("https://github.com/org/broken", None),
+                return_value=("https://github.com/org/broken", None, None),
             ),
             patch(
                 f"{self._URL_LOADER}.clone_skill_repo",
@@ -749,7 +749,7 @@ def test_cache_dir_forwarded(self, tmp_path):
         fake_clone = self._mock_clone(tmp_path)
         captured_cache = []
 
-        def tracking_clone(url, *, ref=None, cache_dir=None):
+        def tracking_clone(url, *, ref=None, subpath=None, cache_dir=None):
             captured_cache.append(cache_dir)
             return fake_clone(url, ref=ref, cache_dir=cache_dir)
 
@@ -759,7 +759,7 @@ def tracking_clone(url, *, ref=None, cache_dir=None):
             patch(f"{self._URL_LOADER}.clone_skill_repo", side_effect=tracking_clone),
             patch(
                 f"{self._URL_LOADER}.parse_url_ref",
-                return_value=("https://github.com/org/url-skill", None),
+                return_value=("https://github.com/org/url-skill", None, None),
             ),
         ):
             AgentSkills(skills=["https://github.com/org/url-skill"], cache_dir=custom_cache)

tests/strands/vended_plugins/skills/test_skill.py

@@ -560,7 +560,7 @@ def _mock_clone(self, tmp_path, skill_name="my-skill", description="A remote ski
         """Create a mock clone function that creates a skill directory."""
         skill_dir = tmp_path / "cloned"
 
-        def fake_clone(url, *, ref=None, cache_dir=None):
+        def fake_clone(url, *, ref=None, subpath=None, cache_dir=None):
             skill_dir.mkdir(parents=True, exist_ok=True)
             content = f"---\nname: {skill_name}\ndescription: {description}\n---\n{body}\n"
             (skill_dir / "SKILL.md").write_text(content)
@@ -572,7 +572,7 @@ def _mock_clone_multi(self, tmp_path):
         """Create a mock clone function that creates a parent dir with multiple skills."""
         parent_dir = tmp_path / "cloned"
 
-        def fake_clone(url, *, ref=None, cache_dir=None):
+        def fake_clone(url, *, ref=None, subpath=None, cache_dir=None):
             parent_dir.mkdir(parents=True, exist_ok=True)
             for name in ("skill-a", "skill-b"):
                 child = parent_dir / name
@@ -590,7 +590,7 @@ def test_from_url_single_skill(self, tmp_path):
 
         with (
             patch(f"{self._URL_LOADER}.clone_skill_repo", side_effect=fake_clone),
-            patch(f"{self._URL_LOADER}.parse_url_ref", return_value=("https://github.com/org/my-skill", None)),
+            patch(f"{self._URL_LOADER}.parse_url_ref", return_value=("https://github.com/org/my-skill", None, None)),
         ):
             skills = Skill.from_url("https://github.com/org/my-skill")
 
@@ -609,7 +609,7 @@ def test_from_url_multiple_skills(self, tmp_path):
             patch(f"{self._URL_LOADER}.clone_skill_repo", side_effect=fake_clone),
             patch(
                 f"{self._URL_LOADER}.parse_url_ref",
-                return_value=("https://github.com/org/skills-collection", None),
+                return_value=("https://github.com/org/skills-collection", None, None),
             ),
         ):
             skills = Skill.from_url("https://github.com/org/skills-collection")
@@ -625,15 +625,15 @@ def test_from_url_with_ref(self, tmp_path):
         fake_clone = self._mock_clone(tmp_path)
         captured_ref = []
 
-        def tracking_clone(url, *, ref=None, cache_dir=None):
+        def tracking_clone(url, *, ref=None, subpath=None, cache_dir=None):
             captured_ref.append(ref)
             return fake_clone(url, ref=ref, cache_dir=cache_dir)
 
         with (
             patch(f"{self._URL_LOADER}.clone_skill_repo", side_effect=tracking_clone),
             patch(
                 f"{self._URL_LOADER}.parse_url_ref",
-                return_value=("https://github.com/org/my-skill", "v1.0.0"),
+                return_value=("https://github.com/org/my-skill", "v1.0.0", None),
             ),
         ):
             Skill.from_url("https://github.com/org/my-skill@v1.0.0")
@@ -652,7 +652,7 @@ def test_from_url_clone_failure_raises(self):
         with (
             patch(
                 f"{self._URL_LOADER}.parse_url_ref",
-                return_value=("https://github.com/org/broken", None),
+                return_value=("https://github.com/org/broken", None, None),
             ),
             patch(
                 f"{self._URL_LOADER}.clone_skill_repo",
@@ -669,7 +669,7 @@ def test_from_url_passes_cache_dir(self, tmp_path):
         fake_clone = self._mock_clone(tmp_path)
         captured_cache = []
 
-        def tracking_clone(url, *, ref=None, cache_dir=None):
+        def tracking_clone(url, *, ref=None, subpath=None, cache_dir=None):
             captured_cache.append(cache_dir)
             return fake_clone(url, ref=ref, cache_dir=cache_dir)
 
@@ -679,7 +679,7 @@ def tracking_clone(url, *, ref=None, cache_dir=None):
             patch(f"{self._URL_LOADER}.clone_skill_repo", side_effect=tracking_clone),
             patch(
                 f"{self._URL_LOADER}.parse_url_ref",
-                return_value=("https://github.com/org/my-skill", None),
+                return_value=("https://github.com/org/my-skill", None, None),
             ),
         ):
             Skill.from_url("https://github.com/org/my-skill", cache_dir=custom_cache)