dais-skills 0.1.0__tar.gz

dais_skills-0.1.0/PKG-INFO

@@ -0,0 +1,12 @@
+Metadata-Version: 2.3
+Name: dais-skills
+Version: 0.1.0
+Summary: A Python package for scanning and downloading agent skills from specified GitHub repositories.
+Author: BHznJNs
+Author-email: BHznJNs <bhznjns@outlook.com>
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: python-frontmatter>=1.1.0
+Requires-Dist: binaryornot>=0.6.0
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+

dais_skills-0.1.0/pyproject.toml

@@ -0,0 +1,22 @@
+[project]
+name = "dais-skills"
+version = "0.1.0"
+description = "A Python package for scanning and downloading agent skills from specified GitHub repositories."
+readme = "README.md"
+authors = [{ name = "BHznJNs", email = "bhznjns@outlook.com" }]
+requires-python = ">=3.14"
+dependencies = [
+    "httpx>=0.28.1",
+    "python-frontmatter>=1.1.0",
+    "binaryornot>=0.6.0",
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.25.2",
+]
+
+[build-system]
+requires = ["uv_build>=0.9.28,<0.12.0"]
+build-backend = "uv_build"

dais_skills-0.1.0/src/dais_skills/__init__.py

@@ -0,0 +1,11 @@
+from .extractor import Skill, SkillResource
+from .downloader import download_skill_zip
+from .scanner import scan_repo, ScannedSkill
+
+__all__ = [
+    "Skill",
+    "SkillResource",
+    "download_skill_zip",
+    "scan_repo",
+    "ScannedSkill",
+]

dais_skills-0.1.0/src/dais_skills/downloader/__init__.py

@@ -0,0 +1,11 @@
+import httpx
+from .github import DownloaderError, GitHubDownloader
+
+
+async def download_skill_zip(repo_url: str, skill_path: str) -> bytes:
+    async with httpx.AsyncClient(timeout=10.0) as client:
+        downloader = GitHubDownloader(client)
+        return await downloader.download_skill_zip(repo_url, skill_path)
+
+
+__all__ = ["download_skill_zip", "DownloaderError"]

dais_skills-0.1.0/src/dais_skills/downloader/github.py

@@ -0,0 +1,82 @@
+import io
+import zipfile
+from pathlib import PurePosixPath
+
+import httpx
+
+from dais_skills.public.github import (
+    GitHubBlob,
+    GitHubClient,
+    GitHubError,
+    GitHubRepo,
+    parse_github_repo_url,
+)
+
+
+class DownloaderError(Exception):
+    pass
+
+
+def normalize_skill_path(skill_path: str) -> str:
+    normalized = skill_path.strip().strip("/")
+    if not normalized:
+        raise DownloaderError("Skill path must not be empty")
+    if PurePosixPath(normalized).name.lower() == "skill.md":
+        normalized = str(PurePosixPath(normalized).parent)
+    if normalized in {"", "."}:
+        raise DownloaderError("Skill path must point to a skill directory")
+    return normalized
+
+
+class GitHubDownloader:
+    def __init__(self, client: httpx.AsyncClient):
+        self._github = GitHubClient(client)
+
+    async def download_skill_zip(self, repo_url: str, skill_path: str) -> bytes:
+        repo = parse_github_repo_url(repo_url)
+        skill_dir = normalize_skill_path(skill_path)
+        try:
+            tree_ref, blobs = await self._github.fetch_tree(repo)
+        except GitHubError as exc:
+            raise DownloaderError(str(exc)) from exc
+
+        skill_blobs = filter_skill_blobs(blobs, skill_dir)
+        if not skill_blobs:
+            raise DownloaderError(f"Skill path not found: {skill_dir}")
+
+        archive_root = PurePosixPath(skill_dir).name or "skill"
+        zip_buffer = io.BytesIO()
+        with zipfile.ZipFile(zip_buffer, "w", compression=zipfile.ZIP_DEFLATED) as zf:
+            for blob in skill_blobs:
+                try:
+                    content = await self._github.fetch_blob(repo, tree_ref, blob.path)
+                except GitHubError as exc:
+                    raise DownloaderError(str(exc)) from exc
+                relative = PurePosixPath(blob.path).relative_to(PurePosixPath(skill_dir))
+                archive_path = str(PurePosixPath(archive_root) / relative)
+                zf.writestr(archive_path, content)
+
+        return zip_buffer.getvalue()
+
+
+def filter_skill_blobs(blobs: list[GitHubBlob], skill_dir: str) -> list[GitHubBlob]:
+    prefix = f"{skill_dir}/"
+    filtered = [
+        blob
+        for blob in blobs
+        if blob.path == f"{skill_dir}/SKILL.md"
+        or blob.path == f"{skill_dir}/skill.md"
+        or blob.path.startswith(prefix)
+    ]
+    return sorted(filtered, key=lambda blob: blob.path)
+
+
+__all__ = [
+    "DownloaderError",
+    "GitHubBlob",
+    "GitHubDownloader",
+    "GitHubRepo",
+    "filter_skill_blobs",
+    "normalize_skill_path",
+    "parse_github_repo_url",
+]

dais_skills-0.1.0/src/dais_skills/extractor/__init__.py

@@ -0,0 +1,108 @@
+import zipfile
+import frontmatter
+from dataclasses import dataclass, field
+from pathlib import PurePosixPath
+from typing import Any, cast
+from .resource import SkillResource, create_from_bytes as create_resource_from_bytes
+from .exceptions import InvalidSkillArchiveError
+
+
+ZipPath = PurePosixPath
+
+@dataclass
+class SkillMd:
+    name: str
+    description: str
+    content: str
+
+    license: str | None = None
+    compatibility: str | None = None
+    allowed_tools: str | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+class SkillParser:
+    SKILL_MD_NAME = "skill.md"
+
+    @staticmethod
+    def find_skill_root(paths: list[ZipPath]) -> ZipPath | None:
+        """
+        According to the [specification](https://agentskills.io/home), the skill root should be the first-level directory that contains the SKILL.md file.
+        If there is no such directory, the root is the archive root.
+        """
+        for path in paths:
+            parts = path.parts
+            if len(parts) == 2 and parts[1].lower() == SkillParser.SKILL_MD_NAME:
+                return path.parent
+            if len(parts) == 1 and path.name.lower() == SkillParser.SKILL_MD_NAME:
+                return path.parent
+        return None
+
+    @staticmethod
+    def find_skill_md(paths: list[ZipPath], root: ZipPath) -> ZipPath | None:
+        for path in paths:
+            if path.name.lower() == SkillParser.SKILL_MD_NAME and path.parent == root:
+                return path
+        return None
+
+    @staticmethod
+    def parse_skill_md(text: str) -> SkillMd:
+        def resolve_optional_str(value: Any) -> str | None:
+            if value is None:
+                return None
+            if isinstance(value, str):
+                return value
+            return str(value)
+
+        result = frontmatter.loads(text)
+        return SkillMd(
+            name=str(result["name"]),
+            description=str(result["description"]),
+            content=result.content,
+
+            license=resolve_optional_str(result.get("license")),
+            compatibility=resolve_optional_str(result.get("compatibility")),
+            allowed_tools=resolve_optional_str(result.get("allowed-tools")),
+            metadata=cast(dict[str, Any], result.get("metadata", {})),
+        )
+
+@dataclass
+class Skill(SkillMd):
+    resources: list[SkillResource] = field(default_factory=list)
+
+    @classmethod
+    def from_zip(cls, zip_file: zipfile.ZipFile) -> Skill:
+        names = zip_file.namelist()
+        paths = [ZipPath(name) for name in names]
+
+        skill_root = SkillParser.find_skill_root(paths)
+        if skill_root is None:
+            raise InvalidSkillArchiveError("Skill root not found")
+
+        skill_md = SkillParser.find_skill_md(paths, skill_root)
+        if skill_md is None:
+            raise InvalidSkillArchiveError("SKILL.md not found")
+
+        skill_md_text = zip_file.read(str(skill_md)).decode("utf-8-sig", errors="replace")
+        skill = SkillParser.parse_skill_md(skill_md_text)
+
+        resources: list[SkillResource] = []
+        for info in zip_file.infolist():
+            if info.is_dir(): continue
+            info_path = ZipPath(info.filename)
+            if info_path == skill_md: continue # skip SKILL.md
+            if skill_root != ZipPath(".") and skill_root not in {info_path, *info_path.parents}:
+                continue
+
+            relative = info_path.relative_to(skill_root)
+            content_bytes = zip_file.read(info.filename)
+            resources.append(create_resource_from_bytes(str(relative), content_bytes))
+
+        return cls(
+            **skill.__dict__,
+            resources=resources,
+        )
+
+__all__ = [
+    "SkillResource",
+    "Skill",
+]

dais_skills-0.1.0/src/dais_skills/extractor/exceptions.py

@@ -0,0 +1,13 @@
+class ExtractorException(Exception): ...
+
+
+class InvalidSkillArchiveError(ExtractorException):
+    def __init__(self, message: str):
+        super().__init__(message)
+        self.message = message
+
+
+__all__ = [
+    "ExtractorException",
+    "InvalidSkillArchiveError",
+]

dais_skills-0.1.0/src/dais_skills/extractor/resource.py

@@ -0,0 +1,36 @@
+from dataclasses import dataclass
+from typing import Literal
+from binaryornot.helpers import is_binary_string
+
+
+@dataclass
+class BaseResource:
+    relative: str
+
+@dataclass
+class TextResource(BaseResource):
+    content: str
+    type: Literal["text"] = "text"
+
+@dataclass
+class BinaryResource(BaseResource):
+    content: bytes
+    type: Literal["binary"] = "binary"
+
+type SkillResource = TextResource | BinaryResource
+
+def create_from_bytes(relative: str, content: bytes) -> SkillResource:
+    is_binary = is_binary_string(content) or b"\x00" in content
+    if is_binary:
+        return BinaryResource(relative=relative, content=content)
+    else:
+        return TextResource(relative=relative, content=content.decode("utf-8-sig", errors="replace"))
+
+
+__all__ = [
+    "BaseResource",
+    "TextResource",
+    "BinaryResource",
+    "SkillResource",
+    "create_from_bytes",
+]

dais_skills-0.1.0/src/dais_skills/public/__init__.py

@@ -0,0 +1,15 @@
+from .github import (
+    GitHubBlob,
+    GitHubClient,
+    GitHubError,
+    GitHubRepo,
+    parse_github_repo_url,
+)
+
+__all__ = [
+    "GitHubBlob",
+    "GitHubClient",
+    "GitHubError",
+    "GitHubRepo",
+    "parse_github_repo_url",
+]

dais_skills-0.1.0/src/dais_skills/public/github.py

@@ -0,0 +1,120 @@
+from dataclasses import dataclass
+from urllib.parse import urlparse
+
+import httpx
+
+
+API_BASE_URL = "https://api.github.com"
+RAW_BASE_URL = "https://raw.githubusercontent.com"
+USER_AGENT = "dais-skills"
+
+
+class GitHubError(Exception):
+    pass
+
+
+@dataclass(frozen=True)
+class GitHubRepo:
+    owner: str
+    repo: str
+    ref: str | None = None
+
+    @property
+    def owner_repo(self) -> str:
+        return f"{self.owner}/{self.repo}"
+
+
+@dataclass(frozen=True)
+class GitHubBlob:
+    path: str
+    size: int | None = None
+
+
+def parse_github_repo_url(repo_url: str) -> GitHubRepo:
+    parsed = urlparse(repo_url.strip())
+    if parsed.scheme not in {"http", "https"} or parsed.hostname != "github.com":
+        raise GitHubError(f"Unsupported GitHub repository URL: {repo_url}")
+
+    parts = [part for part in parsed.path.split("/") if part]
+    if len(parts) < 2:
+        raise GitHubError(f"Unsupported GitHub repository URL: {repo_url}")
+
+    owner = parts[0]
+    repo = parts[1].removesuffix(".git")
+
+    ref = None
+    if len(parts) >= 4 and parts[2] == "tree":
+        ref = "/".join(parts[3:])
+
+    return GitHubRepo(owner=owner, repo=repo, ref=ref)
+
+
+class GitHubClient:
+    """Thin async wrapper around GitHub's tree and raw endpoints."""
+
+    def __init__(self, client: httpx.AsyncClient):
+        self._client = client
+
+    async def fetch_tree(self, repo: GitHubRepo) -> tuple[str, list[GitHubBlob]]:
+        refs_to_try = [repo.ref] if repo.ref else ["main", "master"]
+        last_error: GitHubError | None = None
+
+        for tree_ref in refs_to_try:
+            try:
+                tree = await self._get_json(
+                    f"/repos/{repo.owner_repo}/git/trees/{tree_ref}?recursive=1"
+                )
+            except GitHubError as exc:
+                last_error = exc
+                continue
+
+            blobs = [
+                GitHubBlob(path=entry["path"], size=entry.get("size"))
+                for entry in tree.get("tree", [])
+                if entry.get("type") == "blob" and isinstance(entry.get("path"), str)
+            ]
+            return tree_ref, blobs
+
+        if last_error is not None:
+            raise last_error
+        raise GitHubError(f"Unable to fetch repository tree for {repo.owner_repo}")
+
+    async def fetch_blob(self, repo: GitHubRepo, ref: str, path: str) -> bytes:
+        url = f"{RAW_BASE_URL}/{repo.owner}/{repo.repo}/{ref}/{path}"
+        response = await self._client.get(url, headers={"User-Agent": USER_AGENT})
+        try:
+            response.raise_for_status()
+        except httpx.HTTPStatusError as exc:
+            raise GitHubError(
+                f"Failed to download file {path}: HTTP {exc.response.status_code}"
+            ) from exc
+        return response.content
+
+    async def fetch_text(self, repo: GitHubRepo, ref: str, path: str) -> str:
+        content = await self.fetch_blob(repo, ref, path)
+        return content.decode("utf-8", errors="replace")
+
+    async def _get_json(self, path: str) -> dict:
+        response = await self._client.get(
+            f"{API_BASE_URL}{path}",
+            headers={
+                "Accept": "application/vnd.github.v3+json",
+                "User-Agent": USER_AGENT,
+            },
+        )
+        try:
+            response.raise_for_status()
+        except httpx.HTTPStatusError as exc:
+            raise GitHubError(
+                f"GitHub API request failed: HTTP {exc.response.status_code}"
+            ) from exc
+        return response.json()
+
+
+__all__ = [
+    "GitHubError",
+    "GitHubRepo",
+    "GitHubBlob",
+    "GitHubClient",
+    "parse_github_repo_url",
+]

dais_skills-0.1.0/src/dais_skills/scanner/__init__.py

@@ -0,0 +1,12 @@
+import httpx
+
+from .github import GitHubScanner, ScannedSkill, ScannerError
+
+
+async def scan_repo(repo_url: str) -> list[ScannedSkill]:
+    async with httpx.AsyncClient(timeout=10.0) as client:
+        scanner = GitHubScanner(client)
+        return await scanner.scan_repo(repo_url)
+
+
+__all__ = ["scan_repo", "ScannedSkill", "ScannerError"]

dais_skills-0.1.0/src/dais_skills/scanner/github.py

@@ -0,0 +1,161 @@
+from dataclasses import dataclass
+from pathlib import PurePosixPath
+
+import frontmatter
+import httpx
+
+from dais_skills.public.github import (
+    GitHubBlob,
+    GitHubClient,
+    GitHubError,
+    parse_github_repo_url,
+)
+
+
+class ScannerError(Exception):
+    pass
+
+
+PRIORITY_PREFIXES = [
+    "",
+    "skills/",
+    "skills/.curated/",
+    "skills/.experimental/",
+    "skills/.system/",
+    ".agents/skills/",
+    ".claude/skills/",
+    ".cline/skills/",
+    ".codebuddy/skills/",
+    ".codex/skills/",
+    ".commandcode/skills/",
+    ".continue/skills/",
+    ".github/skills/",
+    ".goose/skills/",
+    ".iflow/skills/",
+    ".junie/skills/",
+    ".kilocode/skills/",
+    ".kiro/skills/",
+    ".mux/skills/",
+    ".neovate/skills/",
+    ".opencode/skills/",
+    ".openhands/skills/",
+    ".pi/skills/",
+    ".qoder/skills/",
+    ".roo/skills/",
+    ".trae/skills/",
+    ".windsurf/skills/",
+    ".zencoder/skills/",
+]
+
+SKIP_DIRS = {"node_modules", ".git", "dist", "build", "__pycache__"}
+
+
+@dataclass(frozen=True)
+class ScannedSkill:
+    path: str
+    name: str
+    description: str
+
+
+class GitHubScanner:
+    def __init__(self, client: httpx.AsyncClient):
+        self._github = GitHubClient(client)
+
+    async def scan_repo(self, repo_url: str) -> list[ScannedSkill]:
+        repo = parse_github_repo_url(repo_url)
+        try:
+            tree_ref, blobs = await self._github.fetch_tree(repo)
+        except GitHubError as exc:
+            raise ScannerError(str(exc)) from exc
+
+        skill_md_paths = find_skill_md_paths(blobs)
+
+        skills: list[ScannedSkill] = []
+        for skill_md_path in skill_md_paths:
+            try:
+                content = await self._github.fetch_text(repo, tree_ref, skill_md_path)
+            except GitHubError:
+                continue
+            skill = parse_skill_from_content(content, skill_md_path)
+            if skill is not None:
+                skills.append(skill)
+
+        return skills
+
+
+def _is_skill_md(path: str) -> bool:
+    return "/" in path and path.rsplit("/", 1)[-1].lower() == "skill.md"
+
+
+def find_skill_md_paths(blobs: list[GitHubBlob]) -> list[str]:
+    filtered = [blob.path for blob in blobs if _is_skill_md(blob.path)]
+    if not filtered:
+        return []
+
+    priority_results: list[str] = []
+    seen: set[str] = set()
+    lower_skill_md_set = {path.lower() for path in filtered}
+
+    for priority_prefix in PRIORITY_PREFIXES:
+        is_container = priority_prefix != ""
+
+        for skill_md in filtered:
+            if not skill_md.startswith(priority_prefix):
+                continue
+
+            rest = skill_md[len(priority_prefix):]
+            parts = rest.split("/")
+
+            if len(parts) == 2:
+                if skill_md not in seen:
+                    priority_results.append(skill_md)
+                    seen.add(skill_md)
+                continue
+
+            if (
+                is_container
+                and len(parts) == 3
+                and parts[0] not in SKIP_DIRS
+                and parts[1] not in SKIP_DIRS
+            ):
+                parent_skill_md = f"{priority_prefix}{parts[0]}/SKILL.md".lower()
+                if parent_skill_md not in lower_skill_md_set and skill_md not in seen:
+                    priority_results.append(skill_md)
+                    seen.add(skill_md)
+
+    if priority_results:
+        return priority_results
+
+    return [
+        path
+        for path in filtered
+        if path.count("/") <= 5
+        and not any(part in SKIP_DIRS for part in path.split("/"))
+    ]
+
+
+def parse_skill_from_content(content: str, repo_path: str) -> ScannedSkill | None:
+    try:
+        post = frontmatter.loads(content)
+    except Exception:
+        return None
+
+    name = post.metadata.get("name")
+    description = post.metadata.get("description")
+    if not isinstance(name, str) or not isinstance(description, str):
+        return None
+
+    return ScannedSkill(
+        path=str(PurePosixPath(repo_path).parent),
+        name=name.strip(),
+        description=description.strip(),
+    )
+
+
+__all__ = [
+    "ScannerError",
+    "ScannedSkill",
+    "GitHubScanner",
+    "find_skill_md_paths",
+    "parse_skill_from_content",
+]