skilly 0.0.2__py3-none-any.whl

skilly/__init__.py

@@ -0,0 +1,7 @@
+from skilly.util import get_project_skills
+from skilly.skills import Skill
+
+__all__ = [
+    "Skill",
+    "get_project_skills",
+]

skilly/cli/root.py

@@ -0,0 +1,22 @@
+from pathlib import Path
+
+from cyclopts import App
+from skilly.cli.util import util_cli
+
+
+cli = App()
+
+cli.command(util_cli)
+
+
+@cli.command()
+def list() -> None:
+    from skilly.parsers import parse_toml
+    from skilly.parsers import PyProjectInfo
+    from skilly.skills import VenvSkills
+
+    toml = parse_toml(Path("pyproject.toml"))
+    info = PyProjectInfo.from_pyproject_toml(toml)
+    venv_skills = VenvSkills.from_dir(Path(".venv"))
+    for skill in venv_skills.filter_skills(info.dependencies):
+        print(f"{skill.skill.name}: {skill.skill.description}")

skilly/cli/util.py

@@ -0,0 +1,32 @@
+from typing import Sequence
+from pathlib import Path
+from cyclopts import App
+
+util_cli = App("util")
+
+
+@util_cli.command()
+def dependencies(
+    file: Path = Path("pyproject.toml"), dev: bool = False, extras: Sequence[str] = ()
+) -> None:
+    # Todo: Sequence[str] might be wrong here for now
+    from skilly.parsers import parse_toml, PyProjectInfo
+
+    toml = parse_toml(file)
+    info = PyProjectInfo.from_pyproject_toml(
+        toml, include_dev=dev, include_extras=extras
+    )
+    for dep in info.dependencies:
+        print(dep.name)
+
+
+@util_cli.command()
+def venv(path: Path = Path(".venv")) -> None:
+
+    from skilly.skills import VenvSkills
+
+    skills = VenvSkills.from_dir(path)
+    for skill in skills.skills:
+        print(
+            f"{skill.skill.name}[{skill.package_name}=={skill.package_version}]: {skill.skill.description}"
+        )

skilly/filesystem.py

@@ -0,0 +1,35 @@
+import os
+from pathlib import Path
+from typing import Protocol, Sequence, Final
+
+
+class FileSystem(Protocol):
+    def read_file(self, path: Path) -> str:
+        """Read a file and return its contents."""
+
+    def list_files(self, path: Path) -> Sequence[str]:
+        """List child entry names in a directory."""
+
+    def is_dir(self, path: Path) -> bool:
+        """Return whether the path is a directory."""
+
+    def resolve(self, path: Path) -> Path:
+        """Return a normalized absolute path."""
+
+
+class DefaultFileSystem(FileSystem):
+    def read_file(self, path: Path) -> str:
+        with open(path, encoding="utf-8") as file_handle:
+            return file_handle.read()
+
+    def list_files(self, path: Path) -> Sequence[str]:
+        return os.listdir(path)
+
+    def is_dir(self, path: Path) -> bool:
+        return os.path.isdir(path)
+
+    def resolve(self, path: Path) -> Path:
+        return path.resolve()
+
+
+DEFAULT_FILE_SYSTEM: Final[FileSystem] = DefaultFileSystem()

skilly/parsers.py

@@ -0,0 +1,54 @@
+import tomllib
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Sequence
+
+from packaging.requirements import Requirement
+
+from .filesystem import DEFAULT_FILE_SYSTEM, FileSystem
+
+
+@dataclass(frozen=True)
+class PyProjectInfo:
+    dependencies: list[Requirement]
+
+    @classmethod
+    def _get_extra_requirements(
+        cls,
+        toml: dict[str, Any],
+        extras: Sequence[str],
+    ) -> list[Requirement]:
+        dependency_groups = toml.get("dependency-groups", {})
+        extra_requirements = []
+        for extra in dependency_groups.keys():
+            if extra in extras:
+                for dep in dependency_groups[extra]:
+                    extra_requirements.append(Requirement(dep))
+
+        return extra_requirements
+
+    @classmethod
+    def from_pyproject_toml(
+        cls,
+        toml: dict[str, Any],
+        include_dev: bool = False,
+        include_extras: Sequence[str] = (),
+    ) -> "PyProjectInfo":
+        dependencies = []
+        for dep in toml.get("project", {}).get("dependencies", []):
+            dependencies.append(Requirement(dep))
+
+        extras = set(include_extras)
+        if include_dev:
+            extras.add("dev")
+
+        dependencies.extend(cls._get_extra_requirements(toml, extras))
+        return cls(dependencies=dependencies)
+
+
+def parse_toml(
+    path: Path,
+    file_system: FileSystem = DEFAULT_FILE_SYSTEM,
+) -> dict[str, Any]:
+    data = file_system.read_file(path)
+    return tomllib.loads(data)

skilly/skills.py

@@ -0,0 +1,431 @@
+import csv
+from dataclasses import dataclass, field
+from email.parser import Parser
+from pathlib import Path, PurePosixPath
+from typing import Sequence
+
+from packaging.requirements import Requirement
+
+from .filesystem import DEFAULT_FILE_SYSTEM, FileSystem
+
+
+@dataclass(frozen=True)
+class Skill:
+    name: str
+    description: str
+    path: Path
+    body: str = ""
+    license: str | None = None
+    compatibility: str | None = None
+    metadata: dict[str, str] = field(default_factory=dict)
+    allowed_tools: str | None = None
+
+    @classmethod
+    def from_text(
+        cls,
+        text: str,
+        *,
+        path: Path | None = None,
+        file_system: FileSystem = DEFAULT_FILE_SYSTEM,
+    ) -> "Skill":
+        if path is None:
+            skill_path = Path("SKILL.md")
+        else:
+            skill_path = file_system.resolve(path)
+
+        frontmatter, body = _split_frontmatter(text)
+        raw_metadata = _parse_frontmatter(frontmatter)
+
+        raw_skill_metadata = raw_metadata.get("metadata")
+        if isinstance(raw_skill_metadata, dict):
+            skill_metadata = {
+                str(key): value
+                for key, value in raw_skill_metadata.items()
+                if isinstance(value, str)
+            }
+        else:
+            skill_metadata = {}
+
+        return cls(
+            name=raw_metadata.get("name")
+            if isinstance(raw_metadata.get("name"), str)
+            else "",
+            description=raw_metadata.get("description")
+            if isinstance(raw_metadata.get("description"), str)
+            else "",
+            path=skill_path,
+            body=body,
+            license=raw_metadata.get("license")
+            if isinstance(raw_metadata.get("license"), str)
+            else None,
+            compatibility=raw_metadata.get("compatibility")
+            if isinstance(raw_metadata.get("compatibility"), str)
+            else None,
+            metadata=skill_metadata,
+            allowed_tools=raw_metadata.get("allowed-tools")
+            if isinstance(raw_metadata.get("allowed-tools"), str)
+            else None,
+        )
+
+    @classmethod
+    def from_file(
+        cls,
+        path: Path,
+        *,
+        file_system: FileSystem = DEFAULT_FILE_SYSTEM,
+    ) -> "Skill":
+        text = file_system.read_file(path)
+        return cls.from_text(text, path=path, file_system=file_system)
+
+    @classmethod
+    def from_dir(
+        cls,
+        path: Path,
+        *,
+        file_system: FileSystem = DEFAULT_FILE_SYSTEM,
+    ) -> "Skill":
+        return cls.from_file(path / "SKILL.md", file_system=file_system)
+
+
+@dataclass(frozen=True)
+class DiscoveredSkill:
+    package_name: str
+    skill: Skill
+    package_version: str = ""
+
+
+@dataclass(frozen=True)
+class VenvSkills:
+    skills: list[DiscoveredSkill]
+    path: Path
+    site_packages_dir: Path | None = None
+    warnings: list[str] = field(default_factory=list)
+
+    def filter_skills(self, packages: Sequence[Requirement]) -> list[DiscoveredSkill]:
+        package_names = [p.name for p in packages]
+        return [skill for skill in self.skills if skill.package_name in package_names]
+
+    @classmethod
+    def from_dir(
+        cls,
+        path: Path = Path(".venv"),
+        *,
+        file_system: FileSystem = DEFAULT_FILE_SYSTEM,
+    ) -> "VenvSkills":
+        venv_path = file_system.resolve(path)
+        site_packages_dir = _get_site_packages_dir(venv_path, file_system=file_system)
+        warnings: list[str] = []
+        skills: list[DiscoveredSkill] = []
+        seen_skill_dirs: set[Path] = set()
+
+        if site_packages_dir is None or not file_system.is_dir(site_packages_dir):
+            warnings.append(f"Site-packages directory not found for virtualenv: {path}")
+            return cls(
+                skills=[],
+                path=venv_path,
+                site_packages_dir=site_packages_dir,
+                warnings=warnings,
+            )
+
+        for dist_info in _find_dist_info_dirs(
+            site_packages_dir, file_system=file_system
+        ):
+            distribution = _read_distribution_info(dist_info, file_system=file_system)
+            if distribution is None:
+                warnings.append(f"Skipping invalid distribution metadata: {dist_info}")
+                continue
+
+            found = _scan_distribution_records(
+                site_packages_dir=site_packages_dir,
+                dist_info=dist_info,
+                package_name=distribution.name,
+                package_version=distribution.version,
+                seen_skill_dirs=seen_skill_dirs,
+                file_system=file_system,
+            )
+            skills.extend(found.skills)
+            warnings.extend(found.warnings)
+
+        skills.sort(
+            key=lambda item: (item.package_name, item.package_version, item.skill.name)
+        )
+        warnings.sort()
+        return cls(
+            skills=skills,
+            path=venv_path,
+            site_packages_dir=site_packages_dir,
+            warnings=warnings,
+        )
+
+
+@dataclass(frozen=True)
+class _DistributionInfo:
+    name: str
+    version: str
+
+
+@dataclass(frozen=True)
+class _ScanResult:
+    skills: list[DiscoveredSkill] = field(default_factory=list)
+    warnings: list[str] = field(default_factory=list)
+
+
+def _get_site_packages_dir(venv_path: Path, *, file_system: FileSystem) -> Path | None:
+    windows_site_packages = venv_path / "Lib" / "site-packages"
+    if file_system.is_dir(windows_site_packages):
+        return windows_site_packages
+
+    for lib_name in ("lib", "lib64"):
+        lib_dir = venv_path / lib_name
+        if not file_system.is_dir(lib_dir):
+            continue
+        for child in _child_paths(lib_dir, file_system=file_system, reverse=True):
+            site_packages = child / "site-packages"
+            if (
+                child.name.startswith("python")
+                and file_system.is_dir(child)
+                and file_system.is_dir(site_packages)
+            ):
+                return site_packages
+
+    return None
+
+
+def _read_distribution_info(
+    dist_info: Path,
+    *,
+    file_system: FileSystem,
+) -> _DistributionInfo | None:
+    metadata_path = dist_info / "METADATA"
+    try:
+        metadata_text = file_system.read_file(metadata_path)
+    except OSError:
+        return None
+
+    metadata = Parser().parsestr(metadata_text)
+    name = metadata.get("Name")
+    if not isinstance(name, str) or not name:
+        return None
+
+    version = metadata.get("Version", "")
+    return _DistributionInfo(
+        name=name, version=version if isinstance(version, str) else ""
+    )
+
+
+def _scan_distribution_records(
+    *,
+    site_packages_dir: Path,
+    dist_info: Path,
+    package_name: str,
+    package_version: str,
+    seen_skill_dirs: set[Path],
+    file_system: FileSystem,
+) -> _ScanResult:
+    record_path = dist_info / "RECORD"
+    try:
+        record_text = file_system.read_file(record_path)
+    except OSError:
+        return _ScanResult()
+
+    skills: list[DiscoveredSkill] = []
+    warnings: list[str] = []
+    for row in csv.reader(record_text.splitlines()):
+        if not row:
+            continue
+
+        installed_path = row[0]
+        if not _is_skill_file_record(installed_path):
+            continue
+
+        skill_path = _resolve_record_path(
+            site_packages_dir,
+            installed_path,
+            file_system=file_system,
+        )
+        skill_dir = skill_path.parent
+        if skill_dir in seen_skill_dirs:
+            continue
+        seen_skill_dirs.add(skill_dir)
+
+        discovered_skill, warning = _load_discovered_skill(
+            skill_path=skill_path,
+            package_name=package_name,
+            package_version=package_version,
+            file_system=file_system,
+        )
+        if discovered_skill is not None:
+            skills.append(discovered_skill)
+        elif warning is not None:
+            warnings.append(warning)
+
+    return _ScanResult(skills=skills, warnings=warnings)
+
+
+def _is_skill_file_record(installed_path: str) -> bool:
+    parts = PurePosixPath(installed_path).parts
+    for index, part in enumerate(parts):
+        if part != ".agents":
+            continue
+        if (
+            len(parts) > index + 3
+            and parts[index + 1] == "skills"
+            and parts[-1] == "SKILL.md"
+        ):
+            return True
+    return False
+
+
+def _load_discovered_skill(
+    *,
+    skill_path: Path,
+    package_name: str,
+    package_version: str,
+    file_system: FileSystem,
+) -> tuple[DiscoveredSkill | None, str | None]:
+    try:
+        skill = Skill.from_file(skill_path, file_system=file_system)
+    except (OSError, UnicodeDecodeError) as exc:
+        return None, f"{skill_path}: could not read SKILL.md ({exc})"
+    except ValueError as exc:
+        return None, f"{skill_path}: {exc}"
+
+    return (
+        DiscoveredSkill(
+            package_name=package_name,
+            package_version=package_version,
+            skill=skill,
+        ),
+        None,
+    )
+
+
+def _split_frontmatter(text: str) -> tuple[list[str], str]:
+    lines = text.splitlines()
+    if not lines or lines[0].strip() != "---":
+        raise ValueError("missing YAML frontmatter")
+
+    for index, line in enumerate(lines[1:], start=1):
+        if line.strip() == "---":
+            return lines[1:index], "\n".join(lines[index + 1 :])
+
+    raise ValueError("unterminated YAML frontmatter")
+
+
+def _parse_frontmatter(lines: list[str]) -> dict[str, object]:
+    metadata: dict[str, object] = {}
+    line_index = 0
+    while line_index < len(lines):
+        line = lines[line_index]
+        stripped = line.strip()
+        if not stripped or stripped.startswith("#"):
+            line_index += 1
+            continue
+        if line[:1].isspace():
+            raise ValueError("top-level frontmatter fields must not be indented")
+
+        key, separator, raw_value = line.partition(":")
+        if not separator:
+            raise ValueError(f"invalid frontmatter line: {line}")
+
+        key = key.strip()
+        value = raw_value.lstrip()
+        if key == "metadata" and not value:
+            parsed_metadata, line_index = _parse_metadata_block(
+                lines,
+                start_index=line_index + 1,
+            )
+            metadata[key] = parsed_metadata
+            continue
+
+        parsed_value = _parse_scalar(value)
+        if not isinstance(parsed_value, str):
+            raise ValueError(f"{key} must be a string")
+        metadata[key] = parsed_value
+        line_index += 1
+
+    return metadata
+
+
+def _parse_metadata_block(
+    lines: list[str],
+    *,
+    start_index: int,
+) -> tuple[dict[str, str], int]:
+    metadata: dict[str, str] = {}
+    line_index = start_index
+
+    while line_index < len(lines):
+        line = lines[line_index]
+        stripped = line.strip()
+        if not stripped or stripped.startswith("#"):
+            line_index += 1
+            continue
+        if not line.startswith((" ", "\t")):
+            break
+        if line.startswith("\t"):
+            raise ValueError("metadata entries must be indented with spaces")
+
+        indentation = len(line) - len(line.lstrip(" "))
+        if indentation < 2:
+            raise ValueError("metadata entries must be indented by at least two spaces")
+
+        key, separator, raw_value = line[indentation:].partition(":")
+        if not separator:
+            raise ValueError(f"invalid metadata line: {line.strip()}")
+
+        parsed_value = _parse_scalar(raw_value.lstrip())
+        if not isinstance(parsed_value, str):
+            raise ValueError("metadata values must be strings")
+        metadata[key.strip()] = parsed_value
+        line_index += 1
+
+    return metadata, line_index
+
+
+def _parse_scalar(value: str) -> str | None:
+    value = value.strip()
+    if value == "null":
+        return None
+    if value.startswith("'") and value.endswith("'") and len(value) >= 2:
+        return value[1:-1].replace("''", "'")
+    if value.startswith('"') and value.endswith('"') and len(value) >= 2:
+        return bytes(value[1:-1], "utf-8").decode("unicode_escape")
+    return value
+
+
+def _find_dist_info_dirs(
+    site_packages_dir: Path,
+    *,
+    file_system: FileSystem,
+) -> list[Path]:
+    return [
+        child
+        for child in _child_paths(site_packages_dir, file_system=file_system)
+        if child.name.endswith(".dist-info") and file_system.is_dir(child)
+    ]
+
+
+def _child_paths(
+    path: Path,
+    *,
+    file_system: FileSystem,
+    reverse: bool = False,
+) -> list[Path]:
+    try:
+        names = sorted(file_system.list_files(path), reverse=reverse)
+    except OSError:
+        return []
+    return [path / name for name in names]
+
+
+def _resolve_record_path(
+    site_packages_dir: Path,
+    installed_path: str,
+    *,
+    file_system: FileSystem,
+) -> Path:
+    path = site_packages_dir
+    for part in PurePosixPath(installed_path).parts:
+        path /= part
+    return file_system.resolve(path)

skilly/util.py

@@ -0,0 +1,17 @@
+from pathlib import Path
+from typing import List
+
+from skilly.filesystem import FileSystem, DEFAULT_FILE_SYSTEM
+from skilly.parsers import parse_toml, PyProjectInfo
+from skilly.skills import Skill, VenvSkills
+
+
+def get_project_skills(
+    pyproject_toml_path: Path = Path("pyproject.toml"),
+    venv_path: Path = Path(".venv"),
+    file_system: FileSystem = DEFAULT_FILE_SYSTEM,
+) -> List[Skill]:
+    toml = parse_toml(pyproject_toml_path, file_system=file_system)
+    info = PyProjectInfo.from_pyproject_toml(toml)
+    venv_skills = VenvSkills.from_dir(venv_path, file_system=file_system)
+    return [s.skill for s in venv_skills.filter_skills(info.dependencies)]

skilly-0.0.2.dist-info/METADATA

@@ -0,0 +1,21 @@
+Metadata-Version: 2.4
+Name: skilly
+Version: 0.0.2
+Summary: Load skills from dependencies.
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: cyclopts>=4
+Requires-Dist: niquests>=3
+Description-Content-Type: text/markdown
+
+# skilly
+
+Read agent skills from dependencies.
+
+# Development Status
+
+Alpha
+
+# License
+
+[MIT](LICENSE)

skilly-0.0.2.dist-info/RECORD

@@ -0,0 +1,13 @@
+skilly/__init__.py,sha256=fiamy7aTVhTj3BE4S6wp7xZ-eQ-fGN8zvrytSBOHY2Q,129
+skilly/filesystem.py,sha256=yKlF26UFs_NzAhfghahvYGG5srTXO1D84IhXM36cp1U,986
+skilly/parsers.py,sha256=FbG47j96r6xEn4VVRnh4zwhGypL7lyB6pVdXVDvKHJA,1498
+skilly/skills.py,sha256=YMmMv7K_yQKsH_2XyDJ9S06sSFiRAmuGVvNFv-bAmtQ,12895
+skilly/util.py,sha256=XckNuSlbM2iFPn9gcLqQzG1BE_qMVtSlY71kcnszxD0,665
+skilly/cli/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+skilly/cli/root.py,sha256=3QEkcJr_pkTc_up50ymAnWukXxk0q0GQuIiU5K7JSqw,568
+skilly/cli/util.py,sha256=3J3Nxi_MnNSGM0c3GVsOOaxmvKN3RjUgCJNRVoVyTQ8,858
+skilly-0.0.2.dist-info/METADATA,sha256=0gBYX7dS2wFbeUnGav5VlMSln2h2kJ5mpU5L70aIn9w,334
+skilly-0.0.2.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+skilly-0.0.2.dist-info/entry_points.txt,sha256=u0AaCWJ7HB8ZtEP_1e6bXC-Yui210-eO4xxfeWgSbXE,47
+skilly-0.0.2.dist-info/licenses/LICENSE,sha256=nEknAHlknpylAXhQcGx8e20-VchzUfUNs0PJz4o5R6w,1061
+skilly-0.0.2.dist-info/RECORD,,

skilly-0.0.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

skilly-0.0.2.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+skilly = skilly.cli.root:cli

skilly-0.0.2.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alex
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.