code-agnostic 0.3.13__tar.gz → 0.3.14__tar.gz

{code_agnostic-0.3.13 → code_agnostic-0.3.14}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-agnostic
-Version: 0.3.13
+Version: 0.3.14
 Summary: Centralized hub for LLM coding config: MCP, skills, rules, and agents.
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
@@ -230,7 +230,8 @@ code-agnostic skills list
 code-agnostic agents list
 ```
 
-Install a local skill directory into managed source:
+Install copies a skill into managed source first for the chosen scope. Run
+`plan` / `apply` afterward to generate target app files.
 
 ```bash
 code-agnostic skills install ./my-skill --global
@@ -241,6 +242,20 @@ code-agnostic plan
 code-agnostic apply
 ```
 
+Remote GitHub-style sources are also supported:
+
+```bash
+code-agnostic skills install owner/repo --global
+code-agnostic skills install https://github.com/owner/repo --workspace myworkspace
+code-agnostic skills install https://github.com/owner/repo/tree/main/path/to/skills --skill reviewer --skill triage --project myproject
+```
+
+Remote sources may be an `owner/repo` shorthand, a GitHub repository URL, or a
+GitHub tree URL. When a remote source contains multiple skill candidates,
+repeat `--skill` to select the intended skills; otherwise install fails instead
+of guessing. Remote installs still copy the selected skill into the
+`code-agnostic` source of truth before any generated target outputs are written.
+
 Global skills live under `~/.config/code-agnostic/skills`. Workspace-local
 skills live under `~/.config/code-agnostic/workspaces/<name>/skills` and can be
 inspected with `code-agnostic skills list -w <name>`. Project-local skills live
@@ -252,7 +267,7 @@ skills and agents are written under `~/.claude/skills` and `~/.claude/agents`,
 with workspace/project copies under repo-local `.claude/skills` and
 `.claude/agents`.
 
-Project-local skills are not first-class source inputs in `code-agnostic` yet. If a target app discovers repo-local skill folders such as `.agents/skills`, `.opencode/skills`, or user-created `.claude/skills`, treat those as unmanaged app inputs. Workspace sync writes only the exact generated paths recorded in `.sync-state.json`.
+If a target app discovers user-created repo-local skill folders such as `.agents/skills`, `.opencode/skills`, or `.claude/skills`, treat those as unmanaged app inputs unless they were generated from `code-agnostic` project source. Workspace and project sync write only the exact generated paths recorded in their `.sync-state.json` files.
 
 Planned convenience command:
 
@@ -266,7 +281,7 @@ first implementation slice.
 
 ### Workspaces
 
-Register workspace directories. Workspace rules are compiled into a canonical `AGENTS.md` at the workspace root. Repos keep their own repo-specific `AGENTS.md`; Codex receives the workspace rules through generated, git-excluded `AGENTS.override.md` files, while OpenCode workspace configs write project-root `opencode.json` files that reference the shared workspace file through `instructions`. Claude receives generated `CLAUDE.local.md` files and project MCP entries in `~/.claude.json["projects"][absolute_repo_path]["mcpServers"]`. Workspace source config, skills, and agents are propagated into repo-local generated paths for OpenCode, Cursor, Codex, and Claude; user-created project-local skill folders remain unmanaged until project-scoped installs are supported.
+Register workspace directories. Workspace rules are compiled into a canonical `AGENTS.md` at the workspace root. Repos keep their own repo-specific `AGENTS.md`; Codex receives the workspace rules through generated, git-excluded `AGENTS.override.md` files, while OpenCode workspace configs write project-root `opencode.json` files that reference the shared workspace file through `instructions`. Claude receives generated `CLAUDE.local.md` files and project MCP entries in `~/.claude.json["projects"][absolute_repo_path]["mcpServers"]`. Workspace source config, skills, and agents are propagated into repo-local generated paths for OpenCode, Cursor, Codex, and Claude; user-created target app skill folders remain unmanaged unless they were generated from managed source.
 
 Cursor propagation intentionally stays to repo-local MCP, skills, and agents; it does not copy the shared workspace `AGENTS.md` into child repos.
 

{code_agnostic-0.3.13 → code_agnostic-0.3.14}/README.md

@@ -205,7 +205,8 @@ code-agnostic skills list
 code-agnostic agents list
 ```
 
-Install a local skill directory into managed source:
+Install copies a skill into managed source first for the chosen scope. Run
+`plan` / `apply` afterward to generate target app files.
 
 ```bash
 code-agnostic skills install ./my-skill --global
@@ -216,6 +217,20 @@ code-agnostic plan
 code-agnostic apply
 ```
 
+Remote GitHub-style sources are also supported:
+
+```bash
+code-agnostic skills install owner/repo --global
+code-agnostic skills install https://github.com/owner/repo --workspace myworkspace
+code-agnostic skills install https://github.com/owner/repo/tree/main/path/to/skills --skill reviewer --skill triage --project myproject
+```
+
+Remote sources may be an `owner/repo` shorthand, a GitHub repository URL, or a
+GitHub tree URL. When a remote source contains multiple skill candidates,
+repeat `--skill` to select the intended skills; otherwise install fails instead
+of guessing. Remote installs still copy the selected skill into the
+`code-agnostic` source of truth before any generated target outputs are written.
+
 Global skills live under `~/.config/code-agnostic/skills`. Workspace-local
 skills live under `~/.config/code-agnostic/workspaces/<name>/skills` and can be
 inspected with `code-agnostic skills list -w <name>`. Project-local skills live
@@ -227,7 +242,7 @@ skills and agents are written under `~/.claude/skills` and `~/.claude/agents`,
 with workspace/project copies under repo-local `.claude/skills` and
 `.claude/agents`.
 
-Project-local skills are not first-class source inputs in `code-agnostic` yet. If a target app discovers repo-local skill folders such as `.agents/skills`, `.opencode/skills`, or user-created `.claude/skills`, treat those as unmanaged app inputs. Workspace sync writes only the exact generated paths recorded in `.sync-state.json`.
+If a target app discovers user-created repo-local skill folders such as `.agents/skills`, `.opencode/skills`, or `.claude/skills`, treat those as unmanaged app inputs unless they were generated from `code-agnostic` project source. Workspace and project sync write only the exact generated paths recorded in their `.sync-state.json` files.
 
 Planned convenience command:
 
@@ -241,7 +256,7 @@ first implementation slice.
 
 ### Workspaces
 
-Register workspace directories. Workspace rules are compiled into a canonical `AGENTS.md` at the workspace root. Repos keep their own repo-specific `AGENTS.md`; Codex receives the workspace rules through generated, git-excluded `AGENTS.override.md` files, while OpenCode workspace configs write project-root `opencode.json` files that reference the shared workspace file through `instructions`. Claude receives generated `CLAUDE.local.md` files and project MCP entries in `~/.claude.json["projects"][absolute_repo_path]["mcpServers"]`. Workspace source config, skills, and agents are propagated into repo-local generated paths for OpenCode, Cursor, Codex, and Claude; user-created project-local skill folders remain unmanaged until project-scoped installs are supported.
+Register workspace directories. Workspace rules are compiled into a canonical `AGENTS.md` at the workspace root. Repos keep their own repo-specific `AGENTS.md`; Codex receives the workspace rules through generated, git-excluded `AGENTS.override.md` files, while OpenCode workspace configs write project-root `opencode.json` files that reference the shared workspace file through `instructions`. Claude receives generated `CLAUDE.local.md` files and project MCP entries in `~/.claude.json["projects"][absolute_repo_path]["mcpServers"]`. Workspace source config, skills, and agents are propagated into repo-local generated paths for OpenCode, Cursor, Codex, and Claude; user-created target app skill folders remain unmanaged unless they were generated from managed source.
 
 Cursor propagation intentionally stays to repo-local MCP, skills, and agents; it does not copy the shared workspace `AGENTS.md` into child repos.
 

{code_agnostic-0.3.13 → code_agnostic-0.3.14}/code_agnostic/__init__.py

@@ -1,3 +1,3 @@
 __all__ = ["__version__"]
 
-__version__ = "0.3.13"
+__version__ = "0.3.14"

{code_agnostic-0.3.13 → code_agnostic-0.3.14}/code_agnostic/cli/commands/skills.py

@@ -10,17 +10,15 @@ from code_agnostic.cli.helpers import validate_resource_name, workspace_config_r
 from code_agnostic.cli.options import workspace_option
 from code_agnostic.core.repository import CoreRepository
 from code_agnostic.errors import SyncAppError
+from code_agnostic.skills.install_sources import (
+    SkillInstallSourceError,
+    cleanup_skill_install_resolution,
+    resolve_skill_install_source,
+)
 from code_agnostic.tui import SyncConsoleUI
 from code_agnostic.utils import compact_home_path
 
 
-def _is_skill_source(path: Path) -> bool:
-    return path.is_dir() and (
-        (path / "SKILL.md").exists()
-        or ((path / "meta.yaml").exists() and (path / "prompt.md").exists())
-    )
-
-
 def _entries_containing_cwd(
     entries: list[dict[str, str]], cwd: Path
 ) -> list[dict[str, str]]:
@@ -85,6 +83,32 @@ def _install_root(
     )
 
 
+def _preflight_skill_destinations(
+    source_dirs: tuple[Path, ...], root: Path, scope: str
+) -> list[tuple[str, Path, Path]]:
+    installs: list[tuple[str, Path, Path]] = []
+    names = _validate_skill_source_names(source_dirs)
+    for name, source_dir in zip(names, source_dirs, strict=True):
+        destination = root / "skills" / name
+        if destination.exists():
+            raise click.ClickException(f"Skill already exists: {scope}:{name}")
+        installs.append((name, source_dir, destination))
+    return installs
+
+
+def _validate_skill_source_names(source_dirs: tuple[Path, ...]) -> list[str]:
+    names: list[str] = []
+    seen_names: set[str] = set()
+    for source_dir in source_dirs:
+        name = source_dir.name
+        validate_resource_name(name, "skill")
+        if name in seen_names:
+            raise click.ClickException(f"Duplicate skill name in source: {name}")
+        seen_names.add(name)
+        names.append(name)
+    return names
+
+
 @click.group(
     help=(
         "Manage source skill definitions. Commands use global source by default; "
@@ -95,28 +119,37 @@ def skills() -> None:
     pass
 
 
-@skills.command("install", help="Install a local skill directory into source config.")
-@click.argument("source", type=click.Path(path_type=Path))
+@skills.command("install", help="Install a skill source into source config.")
+@click.argument("source")
+@click.option(
+    "--skill",
+    "skill_selectors",
+    multiple=True,
+    help="Select a skill by name or source path; repeat to install multiple.",
+)
 @click.option("--global", "global_scope", is_flag=True, help="Install globally.")
 @workspace_option()
 @click.option("--project", help="Install into a registered project source.")
 @click.pass_obj
 def skills_install(
     obj: dict[str, str],
-    source: Path,
+    source: str,
+    skill_selectors: tuple[str, ...],
     global_scope: bool,
     workspace: str | None,
     project: str | None,
 ) -> None:
-    source = source.expanduser().resolve()
-    if not _is_skill_source(source):
-        raise click.ClickException(
-            "Invalid skill source: expected a directory containing SKILL.md "
-            "or meta.yaml and prompt.md."
-        )
-
-    name = source.name
-    validate_resource_name(name, "skill")
+    resolution = None
+    source_path = Path(source).expanduser()
+    if source_path.exists():
+        try:
+            resolution = resolve_skill_install_source(
+                source,
+                skill_selectors=skill_selectors,
+            )
+            _validate_skill_source_names(resolution.skill_dirs)
+        except SkillInstallSourceError as exc:
+            raise click.ClickException(str(exc)) from exc
 
     core = CoreRepository()
     root, scope, scope_note = _install_root(
@@ -125,17 +158,28 @@ def skills_install(
         workspace=workspace,
         project=project,
     )
-    destination = root / "skills" / name
-    if destination.exists():
-        raise click.ClickException(f"Skill already exists: {scope}:{name}")
-
-    destination.parent.mkdir(parents=True, exist_ok=True)
-    shutil.copytree(source, destination)
-    if scope_note is not None:
-        click.echo(scope_note)
-    click.echo(f"Installed {scope} skill: {name}")
-    click.echo(f"Source: {compact_home_path(source)}")
-    click.echo(f"Destination: {compact_home_path(destination)}")
+    try:
+        if resolution is None:
+            resolution = resolve_skill_install_source(
+                source,
+                skill_selectors=skill_selectors,
+            )
+        installs = _preflight_skill_destinations(resolution.skill_dirs, root, scope)
+        for _name, _source_dir, destination in installs:
+            destination.parent.mkdir(parents=True, exist_ok=True)
+        for name, source_dir, destination in installs:
+            shutil.copytree(source_dir, destination)
+            if scope_note is not None:
+                click.echo(scope_note)
+                scope_note = None
+            click.echo(f"Installed {scope} skill: {name}")
+            click.echo(f"Source: {compact_home_path(source_dir)}")
+            click.echo(f"Destination: {compact_home_path(destination)}")
+    except SkillInstallSourceError as exc:
+        raise click.ClickException(str(exc)) from exc
+    finally:
+        if resolution is not None:
+            cleanup_skill_install_resolution(resolution)
 
 
 @skills.command("list", help="List global skills, or workspace skills with -w.")

code_agnostic-0.3.14/code_agnostic/skills/install_sources.py

@@ -0,0 +1,369 @@
+"""Resolve skill install sources into local skill directories."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import os
+from pathlib import Path
+import re
+import shutil
+import stat
+import subprocess
+import tempfile
+from urllib.parse import unquote, urlparse
+
+from code_agnostic.errors import SyncAppError
+
+_GITHUB_SHORTHAND_RE = re.compile(
+    r"^(?P<owner>[A-Za-z0-9_.-]+)/(?P<repo>[A-Za-z0-9_.-]+)$"
+)
+
+
+class SkillInstallSourceError(SyncAppError):
+    """Raised when a skill install source cannot be resolved."""
+
+
+@dataclass(frozen=True)
+class ParsedSkillInstallSource:
+    raw: str
+    kind: str
+    path: Path | None = None
+    clone_url: str | None = None
+    tree_parts: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True)
+class SkillInstallCandidate:
+    name: str
+    path: Path
+    relative_path: str
+
+
+@dataclass(frozen=True)
+class SkillInstallResolution:
+    source: str
+    root: Path
+    skill_dirs: tuple[Path, ...]
+    candidates: tuple[SkillInstallCandidate, ...]
+    checkout_dir: Path | None = None
+    work_dir: Path | None = None
+
+
+def parse_skill_install_source(source: str | Path) -> ParsedSkillInstallSource:
+    """Parse a local path or supported GitHub source."""
+
+    raw = str(source)
+    path = Path(raw).expanduser()
+    if path.exists():
+        return ParsedSkillInstallSource(
+            raw=raw,
+            kind="local",
+            path=path.resolve(),
+        )
+
+    github_source = _parse_github_source(raw)
+    if github_source is not None:
+        return github_source
+
+    if urlparse(raw).scheme:
+        raise SkillInstallSourceError(f"Unsupported skill source URL: {raw}")
+
+    raise SkillInstallSourceError(f"Skill source does not exist: {path}")
+
+
+def resolve_skill_install_source(
+    source: str | Path,
+    *,
+    skill_selectors: list[str] | tuple[str, ...] = (),
+    work_dir: Path | None = None,
+) -> SkillInstallResolution:
+    """Resolve a source into selected local skill directories.
+
+    Remote sources are cloned into ``work_dir`` when provided, or into a new
+    temporary directory. The caller owns cleanup for returned paths.
+    """
+
+    parsed = parse_skill_install_source(source)
+    checkout_dir: Path | None = None
+    checkout_work_dir: Path | None = None
+
+    try:
+        if parsed.kind == "local":
+            if parsed.path is None:
+                raise SkillInstallSourceError(
+                    f"Invalid local skill source: {parsed.raw}"
+                )
+            root = parsed.path
+        elif parsed.kind == "github":
+            if parsed.clone_url is None:
+                raise SkillInstallSourceError(
+                    f"Invalid GitHub skill source: {parsed.raw}"
+                )
+            checkout_dir, checkout_work_dir = _clone_git_source(
+                parsed.clone_url, work_dir=work_dir
+            )
+            root = checkout_dir
+            if parsed.tree_parts:
+                subpath = _checkout_tree_parts(checkout_dir, parsed.tree_parts)
+                root = checkout_dir / subpath
+        else:
+            raise SkillInstallSourceError(f"Unsupported skill source: {parsed.raw}")
+
+        candidates = _discover_skill_candidates(root)
+        selected = _select_candidates(parsed.raw, candidates, skill_selectors)
+        return SkillInstallResolution(
+            source=parsed.raw,
+            root=root,
+            skill_dirs=tuple(candidate.path for candidate in selected),
+            candidates=tuple(selected),
+            checkout_dir=checkout_dir,
+            work_dir=checkout_work_dir,
+        )
+    except Exception:
+        if checkout_work_dir is not None and work_dir is None:
+            _remove_tree(checkout_work_dir)
+        raise
+
+
+def cleanup_skill_install_resolution(resolution: SkillInstallResolution) -> None:
+    """Remove temporary checkout files created for a resolution."""
+
+    if resolution.work_dir is not None:
+        _remove_tree(resolution.work_dir)
+
+
+def _parse_github_source(raw: str) -> ParsedSkillInstallSource | None:
+    shorthand = _GITHUB_SHORTHAND_RE.match(raw)
+    if shorthand is not None:
+        owner = shorthand.group("owner")
+        repo = shorthand.group("repo").removesuffix(".git")
+        return ParsedSkillInstallSource(
+            raw=raw,
+            kind="github",
+            clone_url=_github_clone_url(owner, repo),
+        )
+
+    parsed = urlparse(raw)
+    if parsed.scheme not in {"http", "https"} or parsed.netloc.lower() != "github.com":
+        return None
+
+    parts = [unquote(part) for part in parsed.path.split("/") if part]
+    if len(parts) < 2:
+        raise SkillInstallSourceError(f"Invalid GitHub skill source: {raw}")
+
+    owner = parts[0]
+    repo = parts[1].removesuffix(".git")
+    if len(parts) == 2:
+        return ParsedSkillInstallSource(
+            raw=raw,
+            kind="github",
+            clone_url=_github_clone_url(owner, repo),
+        )
+
+    if len(parts) >= 4 and parts[2] == "tree":
+        tree_parts = tuple(parts[3:])
+        _validate_tree_parts(raw, tree_parts)
+        return ParsedSkillInstallSource(
+            raw=raw,
+            kind="github",
+            clone_url=_github_clone_url(owner, repo),
+            tree_parts=tree_parts,
+        )
+
+    raise SkillInstallSourceError(
+        "Unsupported GitHub skill source path. Expected a repository URL or "
+        f"/tree/<ref>/<path>: {raw}"
+    )
+
+
+def _github_clone_url(owner: str, repo: str) -> str:
+    return f"https://github.com/{owner}/{repo}.git"
+
+
+def _validate_tree_parts(raw: str, parts: tuple[str, ...]) -> None:
+    if not parts or any(part in {"", ".."} for part in parts):
+        raise SkillInstallSourceError(f"Invalid GitHub tree source: {raw}")
+
+
+def _clone_git_source(source: str, *, work_dir: Path | None) -> tuple[Path, Path]:
+    checkout_work_dir = (
+        work_dir.expanduser().resolve()
+        if work_dir is not None
+        else Path(tempfile.mkdtemp(prefix="code-agnostic-skill-source-"))
+    )
+    checkout_work_dir.mkdir(parents=True, exist_ok=True)
+    checkout_dir = _unique_child(checkout_work_dir, "checkout")
+    try:
+        _run_git(["clone", "--quiet", source, str(checkout_dir)])
+        return checkout_dir, checkout_work_dir
+    except Exception:
+        if work_dir is None:
+            _remove_tree(checkout_work_dir)
+        raise
+
+
+def _checkout_tree_parts(checkout_dir: Path, tree_parts: tuple[str, ...]) -> Path:
+    for ref_part_count in range(len(tree_parts), 0, -1):
+        ref = "/".join(tree_parts[:ref_part_count])
+        result = _run_git(
+            ["checkout", "--quiet", ref],
+            cwd=checkout_dir,
+            check=False,
+        )
+        if result.returncode == 0:
+            path_parts = tree_parts[ref_part_count:]
+            subpath = Path(*path_parts) if path_parts else Path()
+            target = checkout_dir / subpath
+            if not target.exists():
+                raise SkillInstallSourceError(
+                    f"GitHub tree path does not exist after checkout: {subpath}"
+                )
+            return subpath
+
+    raise SkillInstallSourceError(
+        "Could not check out a ref from GitHub tree source: " + "/".join(tree_parts)
+    )
+
+
+def _run_git(
+    args: list[str],
+    *,
+    cwd: Path | None = None,
+    check: bool = True,
+) -> subprocess.CompletedProcess[str]:
+    try:
+        result = subprocess.run(
+            ["git", *args],
+            cwd=cwd,
+            check=False,
+            capture_output=True,
+            text=True,
+        )
+    except FileNotFoundError as exc:
+        raise SkillInstallSourceError(
+            "git is required to resolve this skill source"
+        ) from exc
+
+    if check and result.returncode != 0:
+        detail = result.stderr.strip() or result.stdout.strip() or "git command failed"
+        raise SkillInstallSourceError(detail)
+    return result
+
+
+def _unique_child(parent: Path, name: str) -> Path:
+    candidate = parent / name
+    if not candidate.exists():
+        return candidate
+    index = 2
+    while True:
+        candidate = parent / f"{name}-{index}"
+        if not candidate.exists():
+            return candidate
+        index += 1
+
+
+def _remove_tree(path: Path) -> None:
+    def handle_readonly(
+        func: object,
+        path_string: str,
+        _exc_info: object,
+    ) -> None:
+        os.chmod(path_string, stat.S_IWRITE)
+        func(path_string)  # type: ignore[operator]
+
+    shutil.rmtree(path, onerror=handle_readonly)
+
+
+def _discover_skill_candidates(root: Path) -> list[SkillInstallCandidate]:
+    if not root.exists():
+        raise SkillInstallSourceError(f"Skill source path does not exist: {root}")
+    if not root.is_dir():
+        raise SkillInstallSourceError(f"Skill source is not a directory: {root}")
+    if _is_skill_source(root):
+        return [_candidate_for(root, root)]
+
+    candidates: list[SkillInstallCandidate] = []
+    for dirpath, dirnames, _filenames in os.walk(root):
+        dirnames[:] = [
+            dirname for dirname in dirnames if dirname not in {".git", "__pycache__"}
+        ]
+        path = Path(dirpath)
+        if _is_skill_source(path):
+            candidates.append(_candidate_for(path, root))
+            dirnames[:] = []
+
+    return sorted(candidates, key=lambda candidate: candidate.relative_path)
+
+
+def _is_skill_source(path: Path) -> bool:
+    return path.is_dir() and (
+        (path / "SKILL.md").exists()
+        or ((path / "meta.yaml").exists() and (path / "prompt.md").exists())
+    )
+
+
+def _candidate_for(path: Path, root: Path) -> SkillInstallCandidate:
+    relative_path = "." if path == root else path.relative_to(root).as_posix()
+    return SkillInstallCandidate(
+        name=path.name,
+        path=path,
+        relative_path=relative_path,
+    )
+
+
+def _select_candidates(
+    source: str,
+    candidates: list[SkillInstallCandidate],
+    selectors: list[str] | tuple[str, ...],
+) -> list[SkillInstallCandidate]:
+    if not candidates:
+        raise SkillInstallSourceError(f"No skill directories found in source: {source}")
+
+    if not selectors:
+        if len(candidates) == 1:
+            return candidates
+        raise SkillInstallSourceError(
+            "Multiple skill candidates found in source: "
+            + _format_candidates(candidates)
+            + ". Pass --skill with one or more candidate names or paths."
+        )
+
+    selected: list[SkillInstallCandidate] = []
+    selected_paths: set[Path] = set()
+    for selector in selectors:
+        normalized = _normalize_selector(selector)
+        matches = [
+            candidate
+            for candidate in candidates
+            if normalized in {candidate.name, candidate.relative_path}
+        ]
+        if not matches:
+            raise SkillInstallSourceError(
+                f"Skill selector did not match any candidates: {selector}. "
+                f"Available candidates: {_format_candidates(candidates)}"
+            )
+        if len(matches) > 1:
+            raise SkillInstallSourceError(
+                f"Skill selector is ambiguous: {selector}. "
+                f"Matched candidates: {_format_candidates(matches)}. "
+                "Pass --skill with a candidate path."
+            )
+        match = matches[0]
+        if match.path not in selected_paths:
+            selected.append(match)
+            selected_paths.add(match.path)
+
+    return selected
+
+
+def _normalize_selector(selector: str) -> str:
+    normalized = selector.strip().replace("\\", "/").strip("/")
+    while normalized.startswith("./"):
+        normalized = normalized[2:]
+    if not normalized:
+        raise SkillInstallSourceError("Skill selector cannot be empty")
+    return normalized
+
+
+def _format_candidates(candidates: list[SkillInstallCandidate]) -> str:
+    return ", ".join(candidate.relative_path for candidate in candidates)