agno 2.3.20__py3-none-any.whl → 2.3.22__py3-none-any.whl

agno/skills/loaders/local.py

@@ -0,0 +1,216 @@
+import re
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple
+
+from agno.skills.errors import SkillValidationError
+from agno.skills.loaders.base import SkillLoader
+from agno.skills.skill import Skill
+from agno.skills.validator import validate_skill_directory
+from agno.utils.log import log_debug, log_warning
+
+
+class LocalSkills(SkillLoader):
+    """Loads skills from the local filesystem.
+
+    This loader can handle both:
+    1. A single skill folder (contains SKILL.md)
+    2. A directory containing multiple skill folders
+
+    Args:
+        path: Path to a skill folder or directory containing skill folders.
+        validate: Whether to validate skills against the Agent Skills spec.
+            If True (default), invalid skills will raise SkillValidationError.
+    """
+
+    def __init__(self, path: str, validate: bool = True):
+        self.path = Path(path).resolve()
+        self.validate = validate
+
+    def load(self) -> List[Skill]:
+        """Load skills from the local filesystem.
+
+        Returns:
+            A list of Skill objects loaded from the filesystem.
+
+        Raises:
+            FileNotFoundError: If the path doesn't exist.
+        """
+        if not self.path.exists():
+            raise FileNotFoundError(f"Skills path does not exist: {self.path}")
+
+        skills: List[Skill] = []
+
+        # Check if this is a single skill folder or a directory of skills
+        skill_md_path = self.path / "SKILL.md"
+        if skill_md_path.exists():
+            # Single skill folder
+            skill = self._load_skill_from_folder(self.path)
+            if skill:
+                skills.append(skill)
+        else:
+            # Directory of skill folders
+            for item in self.path.iterdir():
+                if item.is_dir() and not item.name.startswith("."):
+                    skill_md = item / "SKILL.md"
+                    if skill_md.exists():
+                        skill = self._load_skill_from_folder(item)
+                        if skill:
+                            skills.append(skill)
+                    else:
+                        log_debug(f"Skipping directory without SKILL.md: {item}")
+
+        log_debug(f"Loaded {len(skills)} skills from {self.path}")
+        return skills
+
+    def _load_skill_from_folder(self, folder: Path) -> Optional[Skill]:
+        """Load a single skill from a folder.
+
+        Args:
+            folder: Path to the skill folder.
+
+        Returns:
+            A Skill object if successful, None if there's an error.
+
+        Raises:
+            SkillValidationError: If validation is enabled and the skill is invalid.
+        """
+        # Validate skill directory structure and content if validation is enabled
+        if self.validate:
+            errors = validate_skill_directory(folder)
+            if errors:
+                raise SkillValidationError(
+                    f"Skill validation failed for '{folder.name}'",
+                    errors=errors,
+                )
+
+        skill_md_path = folder / "SKILL.md"
+
+        try:
+            content = skill_md_path.read_text(encoding="utf-8")
+            frontmatter, instructions = self._parse_skill_md(content)
+
+            # Get skill name from the frontmatter or folder name
+            name = frontmatter.get("name", folder.name)
+            description = frontmatter.get("description", "")
+
+            # Get optional fields
+            license_info = frontmatter.get("license")
+            metadata = frontmatter.get("metadata")
+            compatibility = frontmatter.get("compatibility")
+            allowed_tools = frontmatter.get("allowed-tools")
+
+            # Discover scripts
+            scripts = self._discover_scripts(folder)
+
+            # Discover references
+            references = self._discover_references(folder)
+
+            return Skill(
+                name=name,
+                description=description,
+                instructions=instructions,
+                source_path=str(folder),
+                scripts=scripts,
+                references=references,
+                metadata=metadata,
+                license=license_info,
+                compatibility=compatibility,
+                allowed_tools=allowed_tools,
+            )
+
+        except SkillValidationError:
+            raise  # Re-raise validation errors
+        except Exception as e:
+            log_warning(f"Error loading skill from {folder}: {e}")
+            return None
+
+    def _parse_skill_md(self, content: str) -> Tuple[Dict[str, Any], str]:
+        """Parse SKILL.md content into frontmatter and instructions.
+
+        Args:
+            content: The raw SKILL.md content.
+
+        Returns:
+            A tuple of (frontmatter_dict, instructions_body).
+        """
+        frontmatter: Dict[str, Any] = {}
+        instructions = content
+
+        # Check for YAML frontmatter (between --- delimiters)
+        frontmatter_match = re.match(r"^---\s*\n(.*?)\n---\s*\n?(.*)$", content, re.DOTALL)
+
+        if frontmatter_match:
+            frontmatter_text = frontmatter_match.group(1)
+            instructions = frontmatter_match.group(2).strip()
+
+            # Parse YAML frontmatter
+            try:
+                import yaml
+
+                frontmatter = yaml.safe_load(frontmatter_text) or {}
+            except ImportError:
+                # Fallback: simple key-value parsing if yaml not available
+                frontmatter = self._parse_simple_frontmatter(frontmatter_text)
+            except Exception as e:
+                log_warning(f"Error parsing YAML frontmatter: {e}")
+                frontmatter = self._parse_simple_frontmatter(frontmatter_text)
+
+        return frontmatter, instructions
+
+    def _parse_simple_frontmatter(self, text: str) -> Dict[str, Any]:
+        """Simple fallback frontmatter parser for basic key: value pairs.
+
+        Args:
+            text: The frontmatter text.
+
+        Returns:
+            A dictionary of parsed key-value pairs.
+        """
+        result: Dict[str, Any] = {}
+        for line in text.strip().split("\n"):
+            if ":" in line:
+                key, value = line.split(":", 1)
+                key = key.strip()
+                value = value.strip().strip('"').strip("'")
+                result[key] = value
+        return result
+
+    def _discover_scripts(self, folder: Path) -> List[str]:
+        """Discover script files in the scripts/ subdirectory.
+
+        Args:
+            folder: Path to the skill folder.
+
+        Returns:
+            A list of script filenames.
+        """
+        scripts_dir = folder / "scripts"
+        if not scripts_dir.exists() or not scripts_dir.is_dir():
+            return []
+
+        scripts: List[str] = []
+        for item in scripts_dir.iterdir():
+            if item.is_file() and not item.name.startswith("."):
+                scripts.append(item.name)
+
+        return sorted(scripts)
+
+    def _discover_references(self, folder: Path) -> List[str]:
+        """Discover reference files in the references/ subdirectory.
+
+        Args:
+            folder: Path to the skill folder.
+
+        Returns:
+            A list of reference filenames.
+        """
+        refs_dir = folder / "references"
+        if not refs_dir.exists() or not refs_dir.is_dir():
+            return []
+
+        references: List[str] = []
+        for item in refs_dir.iterdir():
+            if item.is_file() and not item.name.startswith("."):
+                references.append(item.name)
+
+        return sorted(references)

agno/skills/skill.py

@@ -0,0 +1,65 @@
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+
+@dataclass
+class Skill:
+    """Represents a skill that an agent can use.
+
+    A skill provides structured instructions, reference documentation,
+    and optional scripts that an agent can access to perform specific tasks.
+
+    Attributes:
+        name: Unique skill name (from folder name or SKILL.md frontmatter)
+        description: Short description of what the skill does
+        instructions: Full SKILL.md body (the instructions/guidance for the agent)
+        scripts: List of script filenames in scripts/ subdirectory
+        references: List of reference filenames in references/ subdirectory
+        source_path: Filesystem path to the skill folder
+        metadata: Optional metadata from frontmatter (version, author, tags, etc.)
+        license: Optional license information
+        compatibility: Optional compatibility requirements
+        allowed_tools: Optional list of tools this skill is allowed to use
+    """
+
+    name: str
+    description: str
+    instructions: str
+    source_path: str
+    scripts: List[str] = field(default_factory=list)
+    references: List[str] = field(default_factory=list)
+    metadata: Optional[Dict[str, Any]] = None
+    license: Optional[str] = None
+    compatibility: Optional[str] = None
+    allowed_tools: Optional[List[str]] = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert the Skill to a dictionary representation."""
+        return {
+            "name": self.name,
+            "description": self.description,
+            "instructions": self.instructions,
+            "source_path": self.source_path,
+            "scripts": self.scripts,
+            "references": self.references,
+            "metadata": self.metadata,
+            "license": self.license,
+            "compatibility": self.compatibility,
+            "allowed_tools": self.allowed_tools,
+        }
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "Skill":
+        """Create a Skill from a dictionary."""
+        return cls(
+            name=data["name"],
+            description=data["description"],
+            instructions=data["instructions"],
+            source_path=data["source_path"],
+            scripts=data.get("scripts", []),
+            references=data.get("references", []),
+            metadata=data.get("metadata"),
+            license=data.get("license"),
+            compatibility=data.get("compatibility"),
+            allowed_tools=data.get("allowed_tools"),
+        )

agno/skills/utils.py

@@ -0,0 +1,107 @@
+"""Utility functions for the skills module."""
+
+import os
+import stat
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+from typing import List, Optional
+
+
+def is_safe_path(base_dir: Path, requested_path: str) -> bool:
+    """Check if the requested path stays within the base directory.
+
+    This prevents path traversal attacks where a malicious path like
+    '../../../etc/passwd' could be used to access files outside the
+    intended directory.
+
+    Args:
+        base_dir: The base directory that the path must stay within.
+        requested_path: The user-provided path to validate.
+
+    Returns:
+        True if the path is safe (stays within base_dir), False otherwise.
+    """
+    try:
+        full_path = (base_dir / requested_path).resolve()
+        base_resolved = base_dir.resolve()
+        return full_path.is_relative_to(base_resolved)
+    except (ValueError, OSError):
+        return False
+
+
+def ensure_executable(file_path: Path) -> None:
+    """Ensure a file has the executable bit set for the owner.
+
+    Args:
+        file_path: Path to the file to make executable.
+    """
+    current_mode = file_path.stat().st_mode
+    if not (current_mode & stat.S_IXUSR):
+        os.chmod(file_path, current_mode | stat.S_IXUSR)
+
+
+@dataclass
+class ScriptResult:
+    """Result of a script execution."""
+
+    stdout: str
+    stderr: str
+    returncode: int
+
+
+def run_script(
+    script_path: Path,
+    args: Optional[List[str]] = None,
+    timeout: int = 30,
+    cwd: Optional[Path] = None,
+) -> ScriptResult:
+    """Execute a script and return the result.
+
+    Args:
+        script_path: Path to the script to execute.
+        args: Optional list of arguments to pass to the script.
+        timeout: Maximum execution time in seconds.
+        cwd: Working directory for the script.
+
+    Returns:
+        ScriptResult with stdout, stderr, and returncode.
+
+    Raises:
+        subprocess.TimeoutExpired: If script exceeds timeout.
+        FileNotFoundError: If script or interpreter not found.
+    """
+    ensure_executable(script_path)
+    cmd = [str(script_path), *(args or [])]
+
+    result = subprocess.run(
+        cmd,
+        capture_output=True,
+        text=True,
+        timeout=timeout,
+        cwd=cwd,
+    )
+
+    return ScriptResult(
+        stdout=result.stdout,
+        stderr=result.stderr,
+        returncode=result.returncode,
+    )
+
+
+def read_file_safe(file_path: Path, encoding: str = "utf-8") -> str:
+    """Read a file's contents safely.
+
+    Args:
+        file_path: Path to the file to read.
+        encoding: File encoding (default: utf-8).
+
+    Returns:
+        The file contents as a string.
+
+    Raises:
+        FileNotFoundError: If file doesn't exist.
+        PermissionError: If file can't be read.
+        UnicodeDecodeError: If file can't be decoded.
+    """
+    return file_path.read_text(encoding=encoding)

agno/skills/validator.py

@@ -0,0 +1,277 @@
+"""Skill validation logic following the Agent Skills spec."""
+
+import unicodedata
+from pathlib import Path
+from typing import Dict, List, Optional
+
+# Constants per Agent Skills Spec
+MAX_SKILL_NAME_LENGTH = 64
+MAX_DESCRIPTION_LENGTH = 1024
+MAX_COMPATIBILITY_LENGTH = 500
+
+# Allowed frontmatter fields per Agent Skills Spec
+ALLOWED_FIELDS = {
+    "name",
+    "description",
+    "license",
+    "allowed-tools",
+    "metadata",
+    "compatibility",
+}
+
+
+def _validate_name(name: str, skill_dir: Optional[Path] = None) -> List[str]:
+    """Validate skill name format and directory match.
+
+    Skill names support alphanumeric characters plus hyphens.
+    Names must be lowercase and cannot start/end with hyphens.
+
+    Args:
+        name: The skill name to validate.
+        skill_dir: Optional path to skill directory (for name-directory match check).
+
+    Returns:
+        List of validation error messages. Empty list means valid.
+    """
+    errors = []
+
+    if not name or not isinstance(name, str) or not name.strip():
+        errors.append("Field 'name' must be a non-empty string")
+        return errors
+
+    name = unicodedata.normalize("NFKC", name.strip())
+
+    if len(name) > MAX_SKILL_NAME_LENGTH:
+        errors.append(f"Skill name '{name}' exceeds {MAX_SKILL_NAME_LENGTH} character limit ({len(name)} chars)")
+
+    if name != name.lower():
+        errors.append(f"Skill name '{name}' must be lowercase")
+
+    if name.startswith("-") or name.endswith("-"):
+        errors.append("Skill name cannot start or end with a hyphen")
+
+    if "--" in name:
+        errors.append("Skill name cannot contain consecutive hyphens")
+
+    if not all(c.isalnum() or c == "-" for c in name):
+        errors.append(
+            f"Skill name '{name}' contains invalid characters. Only letters, digits, and hyphens are allowed."
+        )
+
+    if skill_dir:
+        dir_name = unicodedata.normalize("NFKC", skill_dir.name)
+        if dir_name != name:
+            errors.append(f"Directory name '{dir_name}' must match skill name '{name}'")
+
+    return errors
+
+
+def _validate_description(description: str) -> List[str]:
+    """Validate description format.
+
+    Args:
+        description: The skill description to validate.
+
+    Returns:
+        List of validation error messages. Empty list means valid.
+    """
+    errors = []
+
+    if not description or not isinstance(description, str) or not description.strip():
+        errors.append("Field 'description' must be a non-empty string")
+        return errors
+
+    if len(description) > MAX_DESCRIPTION_LENGTH:
+        errors.append(f"Description exceeds {MAX_DESCRIPTION_LENGTH} character limit ({len(description)} chars)")
+
+    return errors
+
+
+def _validate_compatibility(compatibility: str) -> List[str]:
+    """Validate compatibility format.
+
+    Args:
+        compatibility: The compatibility string to validate.
+
+    Returns:
+        List of validation error messages. Empty list means valid.
+    """
+    errors = []
+
+    if not isinstance(compatibility, str):
+        errors.append("Field 'compatibility' must be a string")
+        return errors
+
+    if len(compatibility) > MAX_COMPATIBILITY_LENGTH:
+        errors.append(f"Compatibility exceeds {MAX_COMPATIBILITY_LENGTH} character limit ({len(compatibility)} chars)")
+
+    return errors
+
+
+def _validate_license(license_val: str) -> List[str]:
+    """Validate license field.
+
+    Args:
+        license_val: The license string to validate.
+
+    Returns:
+        List of validation error messages. Empty list means valid.
+    """
+    errors: List[str] = []
+
+    if not isinstance(license_val, str):
+        errors.append("Field 'license' must be a string")
+
+    return errors
+
+
+def _validate_allowed_tools(allowed_tools) -> List[str]:
+    """Validate allowed-tools field.
+
+    Args:
+        allowed_tools: The allowed-tools value to validate.
+
+    Returns:
+        List of validation error messages. Empty list means valid.
+    """
+    errors = []
+
+    if not isinstance(allowed_tools, list):
+        errors.append("Field 'allowed-tools' must be a list")
+        return errors
+
+    if not all(isinstance(tool, str) for tool in allowed_tools):
+        errors.append("Field 'allowed-tools' must be a list of strings")
+
+    return errors
+
+
+def _validate_metadata_value(metadata_val) -> List[str]:
+    """Validate metadata field value.
+
+    Args:
+        metadata_val: The metadata value to validate.
+
+    Returns:
+        List of validation error messages. Empty list means valid.
+    """
+    errors = []
+
+    if not isinstance(metadata_val, dict):
+        errors.append("Field 'metadata' must be a dictionary")
+
+    return errors
+
+
+def _validate_metadata_fields(metadata: Dict) -> List[str]:
+    """Validate that only allowed fields are present in frontmatter.
+
+    Args:
+        metadata: Parsed frontmatter dictionary.
+
+    Returns:
+        List of validation error messages. Empty list means valid.
+    """
+    errors = []
+
+    extra_fields = set(metadata.keys()) - ALLOWED_FIELDS
+    if extra_fields:
+        errors.append(
+            f"Unexpected fields in frontmatter: {', '.join(sorted(extra_fields))}. "
+            f"Only {sorted(ALLOWED_FIELDS)} are allowed."
+        )
+
+    return errors
+
+
+def validate_metadata(metadata: Dict, skill_dir: Optional[Path] = None) -> List[str]:
+    """Validate parsed skill metadata.
+
+    This is the core validation function that works on already-parsed metadata.
+
+    Args:
+        metadata: Parsed YAML frontmatter dictionary.
+        skill_dir: Optional path to skill directory (for name-directory match check).
+
+    Returns:
+        List of validation error messages. Empty list means valid.
+    """
+    errors = []
+    errors.extend(_validate_metadata_fields(metadata))
+
+    if "name" not in metadata:
+        errors.append("Missing required field in frontmatter: name")
+    else:
+        errors.extend(_validate_name(metadata["name"], skill_dir))
+
+    if "description" not in metadata:
+        errors.append("Missing required field in frontmatter: description")
+    else:
+        errors.extend(_validate_description(metadata["description"]))
+
+    if "compatibility" in metadata:
+        errors.extend(_validate_compatibility(metadata["compatibility"]))
+
+    if "license" in metadata:
+        errors.extend(_validate_license(metadata["license"]))
+
+    if "allowed-tools" in metadata:
+        errors.extend(_validate_allowed_tools(metadata["allowed-tools"]))
+
+    if "metadata" in metadata:
+        errors.extend(_validate_metadata_value(metadata["metadata"]))
+
+    return errors
+
+
+def validate_skill_directory(skill_dir: Path) -> List[str]:
+    """Validate a skill directory structure and contents.
+
+    Args:
+        skill_dir: Path to the skill directory.
+
+    Returns:
+        List of validation error messages. Empty list means valid.
+    """
+    import yaml
+
+    from agno.skills.errors import SkillParseError
+
+    skill_dir = Path(skill_dir)
+
+    if not skill_dir.exists():
+        return [f"Path does not exist: {skill_dir}"]
+
+    if not skill_dir.is_dir():
+        return [f"Not a directory: {skill_dir}"]
+
+    # Find SKILL.md file (only uppercase supported)
+    skill_md = skill_dir / "SKILL.md"
+    if not skill_md.exists():
+        return ["Missing required file: SKILL.md"]
+
+    # Parse frontmatter
+    try:
+        content = skill_md.read_text(encoding="utf-8")
+
+        if not content.startswith("---"):
+            raise SkillParseError("SKILL.md must start with YAML frontmatter (---)")
+
+        parts = content.split("---", 2)
+        if len(parts) < 3:
+            raise SkillParseError("SKILL.md frontmatter not properly closed with ---")
+
+        frontmatter_str = parts[1]
+        metadata = yaml.safe_load(frontmatter_str)
+
+        if not isinstance(metadata, dict):
+            raise SkillParseError("SKILL.md frontmatter must be a YAML mapping")
+
+    except SkillParseError as e:
+        return [str(e)]
+    except yaml.YAMLError as e:
+        return [f"Invalid YAML in frontmatter: {e}"]
+    except Exception as e:
+        return [f"Error reading SKILL.md: {e}"]
+
+    return validate_metadata(metadata, skill_dir)