abstractskill 0.1.0__py3-none-any.whl

abstractskill/__init__.py

@@ -0,0 +1,33 @@
+"""AbstractSkill — Agent Skills parsing and discovery for AbstractFramework."""
+
+from abstractskill.errors import (
+    SkillError,
+    SkillNotFoundError,
+    SkillParseError,
+    SkillValidationError,
+)
+from abstractskill.hash import content_hash
+from abstractskill.loader import FilesystemSkillLoader
+from abstractskill.models import LoadedSkill, SkillDocument, SkillMetadata
+from abstractskill.parser import parse_skill_md
+from abstractskill.prompt import format_available_skills_xml
+from abstractskill.validation import SKILL_FILENAME, SKILL_NAME_RE, validate_skill_name
+
+__all__ = [
+    "FilesystemSkillLoader",
+    "LoadedSkill",
+    "SKILL_FILENAME",
+    "SKILL_NAME_RE",
+    "SkillDocument",
+    "SkillError",
+    "SkillMetadata",
+    "SkillNotFoundError",
+    "SkillParseError",
+    "SkillValidationError",
+    "content_hash",
+    "format_available_skills_xml",
+    "parse_skill_md",
+    "validate_skill_name",
+]
+
+__version__ = "0.1.0"

abstractskill/errors.py

@@ -0,0 +1,17 @@
+"""Skill-specific exceptions."""
+
+
+class SkillError(Exception):
+    """Base error for AbstractSkill operations."""
+
+
+class SkillParseError(SkillError):
+    """Raised when SKILL.md content cannot be parsed."""
+
+
+class SkillValidationError(SkillError):
+    """Raised when a skill document or directory layout is invalid."""
+
+
+class SkillNotFoundError(SkillError):
+    """Raised when a requested skill cannot be resolved."""

abstractskill/hash.py

@@ -0,0 +1,14 @@
+"""Content hashing for skill evolution tracking."""
+
+from __future__ import annotations
+
+import hashlib
+
+
+def content_hash(content: str | bytes) -> str:
+    """Return a stable SHA-256 hex digest for skill snapshotting."""
+    if isinstance(content, str):
+        payload = content.encode("utf-8")
+    else:
+        payload = content
+    return hashlib.sha256(payload).hexdigest()

abstractskill/loader.py

@@ -0,0 +1,75 @@
+"""Filesystem discovery and loading for Agent Skills."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from abstractskill.errors import SkillNotFoundError, SkillParseError, SkillValidationError
+from abstractskill.models import LoadedSkill, SkillMetadata
+from abstractskill.parser import parse_skill_md
+from abstractskill.validation import SKILL_FILENAME, validate_directory_name_match
+
+
+class FilesystemSkillLoader:
+    """Discover and load skills from one or more directory roots.
+
+    Later roots override earlier ones when skill names collide.
+    """
+
+    def __init__(self, roots: Path | str | list[Path | str]) -> None:
+        if isinstance(roots, (str, Path)):
+            root_list = [roots]
+        else:
+            root_list = list(roots)
+        self._roots = [Path(root).expanduser() for root in root_list]
+
+    @property
+    def roots(self) -> tuple[Path, ...]:
+        return tuple(self._roots)
+
+    def discover(self) -> list[SkillMetadata]:
+        """Return metadata for all valid skills, sorted by name."""
+        by_name: dict[str, SkillMetadata] = {}
+        for root in self._roots:
+            if not root.is_dir():
+                continue
+            for child in sorted(root.iterdir()):
+                if not child.is_dir():
+                    continue
+                skill_file = child / SKILL_FILENAME
+                if not skill_file.is_file():
+                    continue
+                try:
+                    document = parse_skill_md(
+                        skill_file.read_text(encoding="utf-8"),
+                        source_path=skill_file,
+                        directory_name=child.name,
+                    )
+                except (SkillParseError, SkillValidationError):
+                    continue
+                by_name[document.metadata.name] = document.metadata
+        return [by_name[name] for name in sorted(by_name)]
+
+    def load(self, name: str) -> LoadedSkill:
+        """Load the full SKILL.md document for a skill by name."""
+        for root in reversed(self._roots):
+            if not root.is_dir():
+                continue
+            candidate = root / name
+            skill_file = candidate / SKILL_FILENAME
+            if not skill_file.is_file():
+                continue
+            text = skill_file.read_text(encoding="utf-8")
+            document = parse_skill_md(
+                text,
+                source_path=skill_file,
+                directory_name=candidate.name,
+            )
+            if document.metadata.name != name:
+                raise SkillValidationError(
+                    f"skill at {skill_file} declares name {document.metadata.name!r}, "
+                    f"expected {name!r}"
+                )
+            validate_directory_name_match(document.metadata.name, candidate.name)
+            return LoadedSkill(document=document, root_dir=candidate)
+        raise SkillNotFoundError(f"skill not found: {name}")

abstractskill/models.py

@@ -0,0 +1,59 @@
+"""Data models for Agent Skills."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Mapping
+
+
+@dataclass(frozen=True, slots=True)
+class SkillMetadata:
+    """Metadata-only skill view used for discovery and progressive disclosure."""
+
+    name: str
+    description: str
+    license: str | None = None
+    compatibility: str | None = None
+    allowed_tools: tuple[str, ...] = ()
+    metadata: Mapping[str, Any] = field(default_factory=dict)
+    source_path: Path | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        payload: dict[str, Any] = {
+            "name": self.name,
+            "description": self.description,
+        }
+        if self.license is not None:
+            payload["license"] = self.license
+        if self.compatibility is not None:
+            payload["compatibility"] = self.compatibility
+        if self.allowed_tools:
+            payload["allowed_tools"] = list(self.allowed_tools)
+        if self.metadata:
+            payload["metadata"] = dict(self.metadata)
+        if self.source_path is not None:
+            payload["source_path"] = str(self.source_path)
+        return payload
+
+
+@dataclass(frozen=True, slots=True)
+class SkillDocument:
+    """Full SKILL.md content: frontmatter metadata plus markdown instructions."""
+
+    metadata: SkillMetadata
+    body: str
+    raw: str
+    content_hash: str
+
+    @property
+    def name(self) -> str:
+        return self.metadata.name
+
+
+@dataclass(frozen=True, slots=True)
+class LoadedSkill:
+    """A skill resolved from disk with its root directory."""
+
+    document: SkillDocument
+    root_dir: Path

abstractskill/parser.py

@@ -0,0 +1,117 @@
+"""SKILL.md parsing."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Mapping
+
+import yaml
+
+from abstractskill.errors import SkillParseError, SkillValidationError
+from abstractskill.hash import content_hash
+from abstractskill.models import SkillDocument, SkillMetadata
+from abstractskill.validation import validate_skill_name
+
+_FRONTMATTER_DELIM = "---"
+
+
+def _split_frontmatter(text: str) -> tuple[Mapping[str, Any], str]:
+    stripped = text.lstrip("\ufeff")
+    if not stripped.startswith(f"{_FRONTMATTER_DELIM}\n"):
+        raise SkillParseError("SKILL.md must start with YAML frontmatter")
+
+    lines = stripped.splitlines()
+    if not lines or lines[0].strip() != _FRONTMATTER_DELIM:
+        raise SkillParseError("SKILL.md frontmatter opening delimiter is missing")
+
+    closing_idx = None
+    for idx in range(1, len(lines)):
+        if lines[idx].strip() == _FRONTMATTER_DELIM:
+            closing_idx = idx
+            break
+    if closing_idx is None:
+        raise SkillParseError("SKILL.md frontmatter closing delimiter is missing")
+
+    frontmatter_text = "\n".join(lines[1:closing_idx])
+    body = "\n".join(lines[closing_idx + 1 :])
+    if body.startswith("\n"):
+        body = body[1:]
+
+    try:
+        loaded = yaml.safe_load(frontmatter_text) or {}
+    except yaml.YAMLError as exc:
+        raise SkillParseError(f"invalid YAML frontmatter: {exc}") from exc
+
+    if not isinstance(loaded, dict):
+        raise SkillParseError("SKILL.md frontmatter must be a mapping")
+    return loaded, body
+
+
+def _parse_allowed_tools(raw: Any) -> tuple[str, ...]:
+    if raw is None:
+        return ()
+    if isinstance(raw, str):
+        tokens = raw.split()
+    elif isinstance(raw, list):
+        tokens = [str(item).strip() for item in raw if str(item).strip()]
+    else:
+        raise SkillValidationError("allowed-tools must be a string or list of strings")
+    return tuple(tokens)
+
+
+def _metadata_from_frontmatter(
+    frontmatter: Mapping[str, Any],
+    *,
+    source_path: Path | None = None,
+) -> SkillMetadata:
+    if "name" not in frontmatter:
+        raise SkillValidationError("SKILL.md frontmatter requires 'name'")
+    if "description" not in frontmatter:
+        raise SkillValidationError("SKILL.md frontmatter requires 'description'")
+
+    name = validate_skill_name(str(frontmatter["name"]))
+    description = str(frontmatter["description"]).strip()
+    if not description:
+        raise SkillValidationError("SKILL.md frontmatter requires a non-empty description")
+
+    license_value = frontmatter.get("license")
+    compatibility = frontmatter.get("compatibility")
+    extra = frontmatter.get("metadata")
+    if extra is not None and not isinstance(extra, dict):
+        raise SkillValidationError("metadata frontmatter field must be a mapping")
+
+    allowed_raw = frontmatter.get("allowed-tools", frontmatter.get("allowed_tools"))
+    allowed_tools = _parse_allowed_tools(allowed_raw)
+
+    return SkillMetadata(
+        name=name,
+        description=description,
+        license=str(license_value).strip() if license_value is not None else None,
+        compatibility=str(compatibility).strip() if compatibility is not None else None,
+        allowed_tools=allowed_tools,
+        metadata=dict(extra or {}),
+        source_path=source_path,
+    )
+
+
+def parse_skill_md(
+    text: str,
+    *,
+    source_path: Path | None = None,
+    directory_name: str | None = None,
+) -> SkillDocument:
+    """Parse SKILL.md text into metadata and instructions."""
+    frontmatter, body = _split_frontmatter(text)
+    metadata = _metadata_from_frontmatter(frontmatter, source_path=source_path)
+
+    if directory_name is not None:
+        from abstractskill.validation import validate_directory_name_match
+
+        validate_directory_name_match(metadata.name, directory_name)
+
+    return SkillDocument(
+        metadata=metadata,
+        body=body,
+        raw=text,
+        content_hash=content_hash(text),
+    )

abstractskill/prompt.py

@@ -0,0 +1,22 @@
+"""Prompt helpers for progressive skill disclosure."""
+
+from __future__ import annotations
+
+import html
+
+from abstractskill.models import SkillMetadata
+
+
+def format_available_skills_xml(skills: list[SkillMetadata]) -> str:
+    """Render a deterministic `<available_skills>` block for host prompts."""
+    if not skills:
+        return "<available_skills></available_skills>"
+
+    lines = ["<available_skills>"]
+    for skill in sorted(skills, key=lambda item: item.name):
+        lines.append("  <skill>")
+        lines.append(f"    <name>{html.escape(skill.name)}</name>")
+        lines.append(f"    <description>{html.escape(skill.description)}</description>")
+        lines.append("  </skill>")
+    lines.append("</available_skills>")
+    return "\n".join(lines)

abstractskill/validation.py

@@ -0,0 +1,34 @@
+"""Validation helpers for Agent Skills."""
+
+from __future__ import annotations
+
+import re
+
+from abstractskill.errors import SkillValidationError
+
+SKILL_NAME_RE = re.compile(r"^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$")
+SKILL_FILENAME = "SKILL.md"
+
+
+def validate_skill_name(name: str) -> str:
+    """Validate an Agent Skills `name` field."""
+    if not isinstance(name, str):
+        raise SkillValidationError("skill name must be a string")
+    normalized = name.strip()
+    if not normalized:
+        raise SkillValidationError("skill name is required")
+    if len(normalized) > 64:
+        raise SkillValidationError("skill name must be at most 64 characters")
+    if not SKILL_NAME_RE.fullmatch(normalized):
+        raise SkillValidationError(
+            "skill name must use lowercase letters, digits, and hyphens only"
+        )
+    return normalized
+
+
+def validate_directory_name_match(name: str, directory_name: str) -> None:
+    """Ensure the skill name matches its leaf directory name."""
+    if name != directory_name:
+        raise SkillValidationError(
+            f"skill name {name!r} must match directory name {directory_name!r}"
+        )

abstractskill-0.1.0.dist-info/METADATA

@@ -0,0 +1,96 @@
+Metadata-Version: 2.4
+Name: abstractskill
+Version: 0.1.0
+Summary: Agent Skills (SKILL.md) parsing, discovery, and evolution tracking for AbstractFramework
+Author-email: Laurent-Philippe Albou <contact@abstractcore.ai>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/lpalbou/AbstractSkill
+Project-URL: Repository, https://github.com/lpalbou/AbstractSkill
+Project-URL: Documentation, https://github.com/lpalbou/AbstractSkill#readme
+Keywords: abstractframework,abstractcore,abstractgateway,agent-skills,skill-md,skills
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyYAML>=6.0
+Provides-Extra: apple
+Provides-Extra: all-apple
+Provides-Extra: gpu
+Provides-Extra: all-gpu
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Provides-Extra: test
+Requires-Dist: pytest>=7.0.0; extra == "test"
+Dynamic: license-file
+
+# AbstractSkill
+
+AbstractSkill is the shared Python library for [Agent Skills](https://agentskills.io/) (`SKILL.md`) in the
+[AbstractFramework](https://github.com/lpalbou/AbstractFramework) ecosystem.
+
+It provides a small, dependency-light foundation for:
+
+- parsing and validating `SKILL.md` frontmatter and instructions
+- discovering skills on disk (progressive disclosure: metadata first)
+- computing stable content hashes for skill evolution and replay safety
+- formatting compact `<available_skills>` prompt blocks for hosts and agents
+
+Flows run; skills are activated. AbstractSkill owns the portable skill contract so `abstractruntime`,
+`abstractgateway`, and thin clients can share identical semantics without duplicating parsers.
+
+## Install
+
+```bash
+pip install abstractskill
+```
+
+## Quick start
+
+```python
+from pathlib import Path
+
+from abstractskill import FilesystemSkillLoader, format_available_skills_xml, parse_skill_md
+
+# Parse a SKILL.md file
+doc = parse_skill_md(Path("my-skill/SKILL.md").read_text(encoding="utf-8"))
+print(doc.metadata.name, doc.metadata.description)
+
+# Discover skills under one or more roots (later roots override earlier ones)
+loader = FilesystemSkillLoader([Path.home() / ".abstract" / "skills", Path(".abstract/skills")])
+skills = loader.discover()
+print(format_available_skills_xml(skills))
+
+# Load full instructions when a skill is activated
+loaded = loader.load("my-skill")
+print(loaded.document.content_hash)
+```
+
+## Package scope (v0.1.0)
+
+- `parse_skill_md` — YAML frontmatter + markdown body
+- `FilesystemSkillLoader` — list metadata and load full documents
+- `content_hash` — SHA-256 digest for evolution tracking
+- `format_available_skills_xml` — deterministic discovery prompt block
+
+Out of scope for this release: gateway registry APIs, zip `.skill` packaging, and runtime activation handlers.
+Those layers live in `abstractgateway` and `abstractruntime` and consume this library.
+
+## Development
+
+```bash
+python -m pip install -e ".[test]"
+python -m pytest -q
+python -m build
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

abstractskill-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+abstractskill/__init__.py,sha256=Zs5siT-k1cqlcCpAnDwNCHo8xySrCYyD91G8Fkqww5g,948
+abstractskill/errors.py,sha256=I3e8uYZ8kOvczbFERNf6fz3vf0hTubLL85wti0JKktw,422
+abstractskill/hash.py,sha256=U2jfSgD1VxnP_wvNiiwhfRfrjf_rYGuSwik0JEXN7ZM,380
+abstractskill/loader.py,sha256=3bIWyhQ8KPsqb-BZBL5hPTgY7tBwIqx51E3hWzaFpiQ,2940
+abstractskill/models.py,sha256=0q87x3lkvfGawFKX0Bt0D9beyQnoRJkeGbv-BZkulB8,1662
+abstractskill/parser.py,sha256=ZhSnz6xnZBdbHq0tcNphNBz0XzLMhhh_O3tFkwAVqJ0,3967
+abstractskill/prompt.py,sha256=wqHvIczlh9xNlkyvjYReK5RRLDexIRSs5xuJY9Czq2E,766
+abstractskill/validation.py,sha256=2ZX-DlihZnKWMqjudemSB2CQlNAXp7vxdFqiyy1sTac,1153
+abstractskill-0.1.0.dist-info/licenses/LICENSE,sha256=z4XcvE7hBF5qzbKZSumgg2ha3EO1Fsd06a34e7wnmXM,1105
+abstractskill-0.1.0.dist-info/METADATA,sha256=AMzYrtIsuE0Ale9mijie37QysvetZ9tZdyYZ2IW3z-k,3420
+abstractskill-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+abstractskill-0.1.0.dist-info/top_level.txt,sha256=GR2MEbgAXsbQcdZusmHcaRv_JpWjyeYbLGzMTHfGQhY,14
+abstractskill-0.1.0.dist-info/RECORD,,

abstractskill-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

abstractskill-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Laurent-Philippe Albou <contact@abstractcore.ai>
+
+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.

abstractskill-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+abstractskill