agno 2.2.13__py3-none-any.whl → 2.4.3__py3-none-any.whl

agno/skills/agent_skills.py

@@ -0,0 +1,377 @@
+import json
+import subprocess
+from pathlib import Path
+from typing import Dict, List, Optional
+
+from agno.skills.errors import SkillValidationError
+from agno.skills.loaders.base import SkillLoader
+from agno.skills.skill import Skill
+from agno.skills.utils import is_safe_path, read_file_safe, run_script
+from agno.tools.function import Function
+from agno.utils.log import log_debug, log_warning
+
+
+class Skills:
+    """Orchestrates skill loading and provides tools for agents to access skills.
+
+    The Skills class is responsible for:
+    1. Loading skills from various sources (loaders)
+    2. Providing methods to access loaded skills
+    3. Generating tools for agents to use skills
+    4. Creating system prompt snippets with available skills metadata
+
+    Args:
+        loaders: List of SkillLoader instances to load skills from.
+    """
+
+    def __init__(self, loaders: List[SkillLoader]):
+        self.loaders = loaders
+        self._skills: Dict[str, Skill] = {}
+        self._load_skills()
+
+    def _load_skills(self) -> None:
+        """Load skills from all loaders.
+
+        Raises:
+            SkillValidationError: If any skill fails validation.
+        """
+        for loader in self.loaders:
+            try:
+                skills = loader.load()
+                for skill in skills:
+                    if skill.name in self._skills:
+                        log_warning(f"Duplicate skill name '{skill.name}', overwriting with newer version")
+                    self._skills[skill.name] = skill
+            except SkillValidationError:
+                raise  # Re-raise validation errors as hard failures
+            except Exception as e:
+                log_warning(f"Error loading skills from {loader}: {e}")
+
+        log_debug(f"Loaded {len(self._skills)} total skills")
+
+    def reload(self) -> None:
+        """Reload skills from all loaders, clearing existing skills.
+
+        Raises:
+            SkillValidationError: If any skill fails validation.
+        """
+        self._skills.clear()
+        self._load_skills()
+
+    def get_skill(self, name: str) -> Optional[Skill]:
+        """Get a skill by name.
+
+        Args:
+            name: The name of the skill to retrieve.
+
+        Returns:
+            The Skill object if found, None otherwise.
+        """
+        return self._skills.get(name)
+
+    def get_all_skills(self) -> List[Skill]:
+        """Get all loaded skills.
+
+        Returns:
+            A list of all loaded Skill objects.
+        """
+        return list(self._skills.values())
+
+    def get_skill_names(self) -> List[str]:
+        """Get the names of all loaded skills.
+
+        Returns:
+            A list of skill names.
+        """
+        return list(self._skills.keys())
+
+    def get_system_prompt_snippet(self) -> str:
+        """Generate a system prompt snippet with available skills metadata.
+
+        This creates an XML-formatted snippet that provides the agent with
+        information about available skills without including the full instructions.
+
+        Returns:
+            An XML-formatted string with skills metadata.
+        """
+        if not self._skills:
+            return ""
+
+        lines = [
+            "<skills_system>",
+            "",
+            "## What are Skills?",
+            "Skills are packages of domain expertise that extend your capabilities. Each skill contains:",
+            "- **Instructions**: Detailed guidance on when and how to apply the skill",
+            "- **Scripts**: Executable code templates you can use or adapt",
+            "- **References**: Supporting documentation (guides, cheatsheets, examples)",
+            "",
+            "## IMPORTANT: How to Use Skills",
+            "**Skill names are NOT callable functions.** You cannot call a skill directly by its name.",
+            "Instead, you MUST use the provided skill access tools:",
+            "",
+            "1. `get_skill_instructions(skill_name)` - Load the full instructions for a skill",
+            "2. `get_skill_reference(skill_name, reference_path)` - Access specific documentation",
+            "3. `get_skill_script(skill_name, script_path, execute=False)` - Read or run scripts",
+            "",
+            "## Progressive Discovery Workflow",
+            "1. **Browse**: Review the skill summaries below to understand what's available",
+            "2. **Load**: When a task matches a skill, call `get_skill_instructions(skill_name)` first",
+            "3. **Reference**: Use `get_skill_reference` to access specific documentation as needed",
+            "4. **Scripts**: Use `get_skill_script` to read or execute scripts from a skill",
+            "",
+            "This approach ensures you only load detailed instructions when actually needed.",
+            "",
+            "## Available Skills",
+        ]
+        for skill in self._skills.values():
+            lines.append("<skill>")
+            lines.append(f"  <name>{skill.name}</name>")
+            lines.append(f"  <description>{skill.description}</description>")
+            if skill.scripts:
+                script_names = [s["name"] if isinstance(s, dict) else s for s in skill.scripts]
+                lines.append(f"  <scripts>{', '.join(script_names)}</scripts>")
+            if skill.references:
+                ref_names = [r["name"] if isinstance(r, dict) else r for r in skill.references]
+                lines.append(f"  <references>{', '.join(ref_names)}</references>")
+            lines.append("</skill>")
+        lines.append("")
+        lines.append("</skills_system>")
+
+        return "\n".join(lines)
+
+    def get_tools(self) -> List[Function]:
+        """Get the tools for accessing skills.
+
+        Returns:
+            A list of Function objects that agents can use to access skills.
+        """
+        tools: List[Function] = []
+
+        # Tool: get_skill_instructions
+        tools.append(
+            Function(
+                name="get_skill_instructions",
+                description="Load the full instructions for a skill. Use this when you need to follow a skill's guidance.",
+                entrypoint=self._get_skill_instructions,
+            )
+        )
+
+        # Tool: get_skill_reference
+        tools.append(
+            Function(
+                name="get_skill_reference",
+                description="Load a reference document from a skill's references. Use this to access detailed documentation.",
+                entrypoint=self._get_skill_reference,
+            )
+        )
+
+        # Tool: get_skill_script
+        tools.append(
+            Function(
+                name="get_skill_script",
+                description="Read or execute a script from a skill. Set execute=True to run the script and get output, or execute=False (default) to read the script content.",
+                entrypoint=self._get_skill_script,
+            )
+        )
+
+        return tools
+
+    def _get_skill_instructions(self, skill_name: str) -> str:
+        """Load the full instructions for a skill.
+
+        Args:
+            skill_name: The name of the skill to get instructions for.
+
+        Returns:
+            A JSON string with the skill's instructions and metadata.
+        """
+        skill = self.get_skill(skill_name)
+        if skill is None:
+            available = ", ".join(self.get_skill_names())
+            return json.dumps(
+                {
+                    "error": f"Skill '{skill_name}' not found",
+                    "available_skills": available,
+                }
+            )
+
+        return json.dumps(
+            {
+                "skill_name": skill.name,
+                "description": skill.description,
+                "instructions": skill.instructions,
+                "available_scripts": skill.scripts,
+                "available_references": skill.references,
+            }
+        )
+
+    def _get_skill_reference(self, skill_name: str, reference_path: str) -> str:
+        """Load a reference document from a skill.
+
+        Args:
+            skill_name: The name of the skill.
+            reference_path: The filename of the reference document.
+
+        Returns:
+            A JSON string with the reference content.
+        """
+        skill = self.get_skill(skill_name)
+        if skill is None:
+            available = ", ".join(self.get_skill_names())
+            return json.dumps(
+                {
+                    "error": f"Skill '{skill_name}' not found",
+                    "available_skills": available,
+                }
+            )
+
+        if reference_path not in skill.references:
+            return json.dumps(
+                {
+                    "error": f"Reference '{reference_path}' not found in skill '{skill_name}'",
+                    "available_references": skill.references,
+                }
+            )
+
+        # Validate path to prevent path traversal attacks
+        refs_dir = Path(skill.source_path) / "references"
+        if not is_safe_path(refs_dir, reference_path):
+            return json.dumps(
+                {
+                    "error": f"Invalid reference path: '{reference_path}'",
+                    "skill_name": skill_name,
+                }
+            )
+
+        # Load the reference file
+        ref_file = refs_dir / reference_path
+        try:
+            content = read_file_safe(ref_file)
+            return json.dumps(
+                {
+                    "skill_name": skill_name,
+                    "reference_path": reference_path,
+                    "content": content,
+                }
+            )
+        except Exception as e:
+            return json.dumps(
+                {
+                    "error": f"Error reading reference file: {e}",
+                    "skill_name": skill_name,
+                    "reference_path": reference_path,
+                }
+            )
+
+    def _get_skill_script(
+        self,
+        skill_name: str,
+        script_path: str,
+        execute: bool = False,
+        args: Optional[List[str]] = None,
+        timeout: int = 30,
+    ) -> str:
+        """Read or execute a script from a skill.
+
+        Args:
+            skill_name: The name of the skill.
+            script_path: The filename of the script.
+            execute: If True, execute the script. If False (default), return content.
+            args: Optional list of arguments to pass to the script (only used if execute=True).
+            timeout: Maximum execution time in seconds (default: 30, only used if execute=True).
+
+        Returns:
+            A JSON string with either the script content or execution results.
+        """
+        skill = self.get_skill(skill_name)
+        if skill is None:
+            available = ", ".join(self.get_skill_names())
+            return json.dumps(
+                {
+                    "error": f"Skill '{skill_name}' not found",
+                    "available_skills": available,
+                }
+            )
+
+        if script_path not in skill.scripts:
+            return json.dumps(
+                {
+                    "error": f"Script '{script_path}' not found in skill '{skill_name}'",
+                    "available_scripts": skill.scripts,
+                }
+            )
+
+        # Validate path to prevent path traversal attacks
+        scripts_dir = Path(skill.source_path) / "scripts"
+        if not is_safe_path(scripts_dir, script_path):
+            return json.dumps(
+                {
+                    "error": f"Invalid script path: '{script_path}'",
+                    "skill_name": skill_name,
+                }
+            )
+
+        script_file = scripts_dir / script_path
+
+        if not execute:
+            # Read mode: return script content
+            try:
+                content = read_file_safe(script_file)
+                return json.dumps(
+                    {
+                        "skill_name": skill_name,
+                        "script_path": script_path,
+                        "content": content,
+                    }
+                )
+            except Exception as e:
+                return json.dumps(
+                    {
+                        "error": f"Error reading script file: {e}",
+                        "skill_name": skill_name,
+                        "script_path": script_path,
+                    }
+                )
+
+        # Execute mode: run the script
+        try:
+            result = run_script(
+                script_path=script_file,
+                args=args,
+                timeout=timeout,
+                cwd=Path(skill.source_path),
+            )
+            return json.dumps(
+                {
+                    "skill_name": skill_name,
+                    "script_path": script_path,
+                    "stdout": result.stdout,
+                    "stderr": result.stderr,
+                    "returncode": result.returncode,
+                }
+            )
+        except subprocess.TimeoutExpired:
+            return json.dumps(
+                {
+                    "error": f"Script execution timed out after {timeout} seconds",
+                    "skill_name": skill_name,
+                    "script_path": script_path,
+                }
+            )
+        except FileNotFoundError as e:
+            return json.dumps(
+                {
+                    "error": f"Interpreter or script not found: {e}",
+                    "skill_name": skill_name,
+                    "script_path": script_path,
+                }
+            )
+        except Exception as e:
+            return json.dumps(
+                {
+                    "error": f"Error executing script: {e}",
+                    "skill_name": skill_name,
+                    "script_path": script_path,
+                }
+            )

agno/skills/errors.py

@@ -0,0 +1,32 @@
+"""Skill-related exceptions."""
+
+from typing import List, Optional
+
+
+class SkillError(Exception):
+    """Base exception for all skill-related errors."""
+
+    pass
+
+
+class SkillParseError(SkillError):
+    """Raised when SKILL.md parsing fails."""
+
+    pass
+
+
+class SkillValidationError(SkillError):
+    """Raised when skill validation fails.
+
+    Attributes:
+        errors: List of validation error messages.
+    """
+
+    def __init__(self, message: str, errors: Optional[List[str]] = None):
+        super().__init__(message)
+        self.errors = errors if errors is not None else [message]
+
+    def __str__(self) -> str:
+        if len(self.errors) == 1:
+            return self.errors[0]
+        return f"{len(self.errors)} validation errors: {'; '.join(self.errors)}"

agno/skills/loaders/__init__.py

@@ -0,0 +1,4 @@
+from agno.skills.loaders.base import SkillLoader
+from agno.skills.loaders.local import LocalSkills
+
+__all__ = ["SkillLoader", "LocalSkills"]

agno/skills/loaders/base.py

@@ -0,0 +1,27 @@
+from abc import ABC, abstractmethod
+from typing import List
+
+from agno.skills.skill import Skill
+
+
+class SkillLoader(ABC):
+    """Abstract base class for skill loaders.
+
+    Skill loaders are responsible for loading skills from various sources
+    (local filesystem, GitHub, URLs, etc.) and returning them as Skill objects.
+
+    Subclasses must implement the `load()` method to define how skills
+    are loaded from their specific source.
+    """
+
+    @abstractmethod
+    def load(self) -> List[Skill]:
+        """Load skills from the source.
+
+        Returns:
+            A list of Skill objects loaded from the source.
+
+        Raises:
+            SkillLoadError: If there's an error loading skills from the source.
+        """
+        pass

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)