skilllite 0.1.0__py3-none-any.whl

skilllite/core/registry.py

@@ -0,0 +1,185 @@
+"""
+Skill Registry - Skill registration and discovery.
+
+This module handles:
+- Scanning directories for skills
+- Registering individual skills
+- Skill lookup and listing
+- Multi-script tool detection
+"""
+
+from pathlib import Path
+from typing import Dict, List, Optional, Set
+
+from .metadata import SkillMetadata, parse_skill_metadata, detect_all_scripts
+from .skill_info import SkillInfo
+
+
+class SkillRegistry:
+    """
+    Registry for managing skill registration and discovery.
+    
+    Handles skill scanning, registration, and lookup operations.
+    Multi-script analysis is performed lazily when needed.
+    """
+    
+    def __init__(self):
+        self._skills: Dict[str, SkillInfo] = {}
+        # Maps tool_name -> tool info for multi-script skills
+        self._multi_script_tools: Dict[str, Dict[str, str]] = {}
+        # Track which skills have been analyzed for multi-script tools
+        self._analyzed_skills: Set[str] = set()
+    
+    def scan_directory(self, directory: Path) -> int:
+        """
+        Scan a directory for skills.
+        
+        Args:
+            directory: Directory to scan
+            
+        Returns:
+            Number of skills registered
+            
+        Raises:
+            FileNotFoundError: If directory does not exist
+        """
+        if not directory.exists():
+            raise FileNotFoundError(f"Skills directory does not exist: {directory}")
+        
+        # Check if directory itself is a skill
+        if (directory / "SKILL.md").exists():
+            self.register_skill(directory)
+            return 1
+        
+        # Scan subdirectories
+        count = 0
+        for path in directory.iterdir():
+            if path.is_dir() and (path / "SKILL.md").exists():
+                try:
+                    self.register_skill(path)
+                    count += 1
+                except Exception as e:
+                    print(f"Warning: Failed to register skill at {path}: {e}")
+        return count
+    
+    def register_skill(self, skill_dir: Path) -> SkillInfo:
+        """
+        Register a single skill from a directory.
+        
+        Multi-script analysis is deferred until needed (lazy loading).
+        
+        Args:
+            skill_dir: Path to skill directory
+            
+        Returns:
+            Registered SkillInfo
+        """
+        metadata = parse_skill_metadata(skill_dir)
+        info = SkillInfo(metadata, skill_dir)
+        self._skills[metadata.name] = info
+        return info
+    
+    def analyze_multi_script_skill(self, skill_name: str) -> None:
+        """
+        Analyze a skill for multiple scripts and register them as tools.
+        
+        Called lazily when tool definitions are requested.
+        
+        Args:
+            skill_name: Name of skill to analyze
+        """
+        if skill_name in self._analyzed_skills:
+            return
+        
+        info = self._skills.get(skill_name)
+        if not info:
+            return
+        
+        # Only analyze skills without a main entry point
+        if not info.metadata.entry_point:
+            scripts = detect_all_scripts(info.path)
+            if scripts:
+                for script in scripts:
+                    # Create unique tool name: skill-name__script-name
+                    # Use double underscore instead of colon for API compatibility
+                    tool_name = f"{skill_name}__{script['name']}"
+                    self._multi_script_tools[tool_name] = {
+                        "skill_name": skill_name,
+                        "script_path": script["path"],
+                        "script_name": script["name"],
+                        "language": script["language"],
+                        "filename": script["filename"],
+                    }
+        
+        self._analyzed_skills.add(skill_name)
+    
+    def analyze_all_multi_script_skills(self) -> None:
+        """Analyze all registered skills for multi-script tools."""
+        for skill_name in self._skills:
+            self.analyze_multi_script_skill(skill_name)
+    
+    def get_skill(self, name: str) -> Optional[SkillInfo]:
+        """Get a skill by name."""
+        return self._skills.get(name)
+    
+    def list_skills(self) -> List[SkillInfo]:
+        """Get all registered skills."""
+        return list(self._skills.values())
+    
+    def skill_names(self) -> List[str]:
+        """Get names of all registered skills."""
+        return list(self._skills.keys())
+    
+    def has_skill(self, name: str) -> bool:
+        """Check if a skill exists."""
+        return name in self._skills
+    
+    def is_executable(self, name: str) -> bool:
+        """
+        Check if a skill or tool is executable.
+        
+        Includes:
+        - Skills with a single entry_point
+        - Multi-script tools (skill-name:script-name format)
+        """
+        if name in self._multi_script_tools:
+            return True
+        info = self._skills.get(name)
+        return info is not None and bool(info.metadata.entry_point)
+    
+    def list_executable_skills(self) -> List[SkillInfo]:
+        """Get all executable skills (with entry_point or multi-script tools)."""
+        executable = []
+        for info in self._skills.values():
+            if info.metadata.entry_point:
+                executable.append(info)
+            elif info.name in [t["skill_name"] for t in self._multi_script_tools.values()]:
+                executable.append(info)
+        return executable
+    
+    def list_prompt_only_skills(self) -> List[SkillInfo]:
+        """Get all prompt-only skills (without entry_point and no multi-script tools)."""
+        prompt_only = []
+        multi_script_skill_names = set(t["skill_name"] for t in self._multi_script_tools.values())
+        for info in self._skills.values():
+            if not info.metadata.entry_point and info.name not in multi_script_skill_names:
+                prompt_only.append(info)
+        return prompt_only
+    
+    def list_multi_script_tools(self) -> List[str]:
+        """Get all multi-script tool names."""
+        return list(self._multi_script_tools.keys())
+    
+    def get_multi_script_tool_info(self, tool_name: str) -> Optional[Dict[str, str]]:
+        """Get info for a multi-script tool."""
+        return self._multi_script_tools.get(tool_name)
+    
+    @property
+    def skills(self) -> Dict[str, SkillInfo]:
+        """Direct access to skills dict (for compatibility)."""
+        return self._skills
+    
+    @property
+    def multi_script_tools(self) -> Dict[str, Dict[str, str]]:
+        """Direct access to multi-script tools dict (for compatibility)."""
+        return self._multi_script_tools

skilllite/core/skill_info.py

@@ -0,0 +1,181 @@
+"""
+SkillInfo - Information container for a registered skill.
+
+This is a CORE module - do not modify without explicit permission.
+
+This module provides the SkillInfo class which encapsulates all information
+about a skill including its metadata, content, references, and assets.
+"""
+
+import json
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from .metadata import SkillMetadata, detect_language, detect_all_scripts
+
+class SkillInfo:
+    """Information about a registered skill."""
+    
+    def __init__(self, metadata: SkillMetadata, path: Path):
+        self.metadata = metadata
+        self.path = path
+        self._full_content_cache: Optional[str] = None
+    
+    @property
+    def name(self) -> str:
+        return self.metadata.name
+    
+    @property
+    def description(self) -> Optional[str]:
+        return self.metadata.description
+    
+    @property
+    def language(self) -> str:
+        return detect_language(self.path, self.metadata)
+    
+    def get_full_content(self) -> str:
+        """
+        Get the full content of SKILL.md file.
+        
+        Returns:
+            Complete content of SKILL.md including instructions and examples
+        """
+        if self._full_content_cache is not None:
+            return self._full_content_cache
+        
+        skill_md_path = self.path / "SKILL.md"
+        if skill_md_path.exists():
+            self._full_content_cache = skill_md_path.read_text(encoding="utf-8")
+            return self._full_content_cache
+        return ""
+    
+    def get_references(self) -> Dict[str, str]:
+        """
+        Get all reference documents from references/ directory.
+        
+        Returns:
+            Dictionary mapping filename to file content
+        """
+        references = {}
+        references_dir = self.path / "references"
+        
+        if not references_dir.exists():
+            return references
+        
+        for file_path in references_dir.iterdir():
+            if file_path.is_file():
+                try:
+                    content = file_path.read_text(encoding="utf-8")
+                    references[file_path.name] = content
+                except Exception:
+                    references[file_path.name] = f"[Error reading file: {file_path.name}]"
+        
+        return references
+    
+    def get_assets(self) -> Dict[str, Any]:
+        """
+        Get all asset files from assets/ directory.
+        
+        For JSON files, returns parsed content.
+        For other files, returns file path for reference.
+        
+        Returns:
+            Dictionary mapping filename to content or path
+        """
+        assets = {}
+        assets_dir = self.path / "assets"
+        
+        if not assets_dir.exists():
+            return assets
+        
+        for file_path in assets_dir.iterdir():
+            if file_path.is_file():
+                try:
+                    if file_path.suffix.lower() == ".json":
+                        content = file_path.read_text(encoding="utf-8")
+                        assets[file_path.name] = json.loads(content)
+                    elif file_path.suffix.lower() in [".txt", ".md", ".yaml", ".yml", ".toml", ".ini", ".cfg"]:
+                        assets[file_path.name] = file_path.read_text(encoding="utf-8")
+                    else:
+                        assets[file_path.name] = {"_path": str(file_path), "_type": "binary"}
+                except Exception as e:
+                    assets[file_path.name] = {"_error": str(e)}
+        
+        return assets
+    
+    def get_assets_dir(self) -> Optional[Path]:
+        """
+        Get the path to assets/ directory if it exists.
+        
+        Returns:
+            Path to assets directory, or None if not exists
+        """
+        assets_dir = self.path / "assets"
+        return assets_dir if assets_dir.exists() else None
+    
+    def get_references_dir(self) -> Optional[Path]:
+        """
+        Get the path to references/ directory if it exists.
+        
+        Returns:
+            Path to references directory, or None if not exists
+        """
+        references_dir = self.path / "references"
+        return references_dir if references_dir.exists() else None
+    
+    def get_all_scripts(self) -> List[Dict[str, str]]:
+        """
+        Get all executable scripts in this skill.
+        
+        This is useful for skills with multiple entry points (like skill-creator
+        which has init_skill.py, package_skill.py, etc.)
+        
+        Returns:
+            List of dicts with 'name', 'path', 'language', and 'filename' for each script
+        """
+        return detect_all_scripts(self.path)
+    
+    def has_multiple_scripts(self) -> bool:
+        """
+        Check if this skill has multiple executable scripts.
+        
+        Returns:
+            True if there are multiple scripts that could be entry points
+        """
+        scripts = self.get_all_scripts()
+        return len(scripts) > 1
+    
+    def get_context(self, include_references: bool = True, include_assets: bool = True) -> Dict[str, Any]:
+        """
+        Get complete skill context for LLM consumption.
+        
+        Args:
+            include_references: Whether to include reference documents
+            include_assets: Whether to include asset files
+            
+        Returns:
+            Dictionary containing full skill context
+        """
+        context = {
+            "name": self.name,
+            "description": self.description,
+            "full_instructions": self.get_full_content(),
+            "skill_dir": str(self.path),
+        }
+        
+        if include_references:
+            refs = self.get_references()
+            if refs:
+                context["references"] = refs
+        
+        if include_assets:
+            assets = self.get_assets()
+            if assets:
+                context["assets"] = assets
+        
+        # Include available scripts info for multi-script skills
+        scripts = self.get_all_scripts()
+        if scripts:
+            context["available_scripts"] = scripts
+        
+        return context

skilllite/core/tool_builder.py

@@ -0,0 +1,338 @@
+"""
+Tool Builder - Tool definition generation and schema inference.
+
+This module handles:
+- Creating tool definitions from skills
+- Schema inference from script content
+- Argparse parsing for Python scripts
+- Multi-script tool definition creation
+"""
+
+import ast
+import re
+from pathlib import Path
+from typing import Any, Dict, List, Optional, TYPE_CHECKING
+
+from .skill_info import SkillInfo
+from .tools import ToolDefinition
+
+if TYPE_CHECKING:
+    from .registry import SkillRegistry
+
+
+class ToolBuilder:
+    """
+    Builder for creating tool definitions from skills.
+    
+    Handles tool definition generation and argparse parsing for Python scripts.
+    Uses progressive disclosure - tool definitions only contain name and description,
+    full SKILL.md content is injected when the tool is actually called.
+    """
+    
+    def __init__(self, registry: "SkillRegistry"):
+        """
+        Initialize the tool builder.
+        
+        Args:
+            registry: Skill registry for accessing skill info
+        """
+        self._registry = registry
+        # Cache for multi-script tool schemas (argparse-based)
+        self._multi_script_schemas: Dict[str, Dict[str, Any]] = {}
+    
+    def get_tool_definitions(self, include_prompt_only: bool = False) -> List[ToolDefinition]:
+        """
+        Get tool definitions for registered skills.
+        
+        Includes:
+        - Regular skills with a single entry_point
+        - Multi-script tools (each script as a separate tool)
+        
+        Args:
+            include_prompt_only: Whether to include prompt-only skills
+            
+        Returns:
+            List of tool definitions
+        """
+        # Lazily analyze all skills for multi-script tools
+        self._registry.analyze_all_multi_script_skills()
+        
+        definitions = []
+        multi_script_skill_names = set(
+            t["skill_name"] for t in self._registry.multi_script_tools.values()
+        )
+        
+        # Add regular skills with single entry_point
+        for info in self._registry.list_skills():
+            if info.metadata.entry_point:
+                definition = self._create_tool_definition(info)
+                definitions.append(definition)
+            elif info.name in multi_script_skill_names:
+                # Skip - will be handled by multi-script tools below
+                pass
+            elif include_prompt_only:
+                definition = self._create_tool_definition(info)
+                definitions.append(definition)
+        
+        # Add multi-script tools
+        for tool_name, tool_info in self._registry.multi_script_tools.items():
+            skill_info = self._registry.get_skill(tool_info["skill_name"])
+            if skill_info:
+                definition = self._create_multi_script_tool_definition(
+                    tool_name, tool_info, skill_info
+                )
+                definitions.append(definition)
+        
+        return definitions
+    
+    def get_tools_openai(self) -> List[Dict[str, Any]]:
+        """Get tool definitions in OpenAI-compatible format."""
+        return [d.to_openai_format() for d in self.get_tool_definitions()]
+    
+    def get_tools_claude_native(self) -> List[Dict[str, Any]]:
+        """Get tool definitions in Claude's native API format."""
+        return [d.to_claude_format() for d in self.get_tool_definitions()]
+    
+    def _create_tool_definition(self, info: SkillInfo) -> ToolDefinition:
+        """Create a tool definition from skill info.
+        
+        Uses progressive disclosure:
+        1. Tool definition only contains name and description (from YAML front matter)
+        2. Uses a flexible schema that accepts any parameters
+        3. Full SKILL.md content is injected when the tool is actually called,
+           letting the LLM understand the expected parameters from the documentation
+        """
+        description = info.description or f"Execute the {info.name} skill"
+        
+        # Use a flexible schema that accepts any parameters
+        # The LLM will understand the expected format from the full SKILL.md
+        # content that is injected when the tool is called
+        input_schema = {
+            "type": "object",
+            "properties": {},
+            "additionalProperties": True
+        }
+        
+        return ToolDefinition(
+            name=info.name,
+            description=description,
+            input_schema=input_schema
+        )
+    
+    def _create_multi_script_tool_definition(
+        self,
+        tool_name: str,
+        tool_info: Dict[str, str],
+        skill_info: SkillInfo
+    ) -> ToolDefinition:
+        """Create a tool definition for a multi-script tool."""
+        script_name = tool_info["script_name"]
+        script_path = skill_info.path / tool_info["script_path"]
+        description = f"Execute {script_name} from {skill_info.name} skill"
+        
+        if script_path.exists():
+            try:
+                script_content = script_path.read_text(encoding="utf-8")
+                docstring = self._extract_script_docstring(script_content)
+                if docstring:
+                    first_line = docstring.strip().split('\n')[0].strip()
+                    if first_line:
+                        description = first_line
+                        # Add action hint for common operations
+                        if "init" in script_name.lower() or "create" in script_name.lower():
+                            description += ". Call this tool directly to create a new skill."
+                        elif "package" in script_name.lower():
+                            description += ". Call this tool directly to package a skill."
+                        elif "validate" in script_name.lower():
+                            description += ". Call this tool directly to validate a skill."
+            except Exception:
+                pass
+        
+        input_schema = self._infer_script_schema(tool_name, skill_info, tool_info)
+        
+        return ToolDefinition(
+            name=tool_name,
+            description=description,
+            input_schema=input_schema
+        )
+    
+    def _infer_script_schema(
+        self,
+        tool_name: str,
+        skill_info: SkillInfo,
+        tool_info: Dict[str, str]
+    ) -> Dict[str, Any]:
+        """Infer input schema for a multi-script tool using argparse parsing."""
+        if tool_name in self._multi_script_schemas:
+            return self._multi_script_schemas[tool_name]
+        
+        script_path = skill_info.path / tool_info["script_path"]
+        script_code = None
+        if script_path.exists():
+            try:
+                script_code = script_path.read_text(encoding="utf-8")
+            except Exception:
+                pass
+        
+        # Try argparse parsing for Python scripts
+        if script_code and tool_info.get("language") == "python":
+            schema = self._parse_argparse_schema(script_code)
+            if schema:
+                self._multi_script_schemas[tool_name] = schema
+                return schema
+        
+        # Default schema for scripts without argparse
+        return {
+            "type": "object",
+            "properties": {
+                "args": {
+                    "type": "array",
+                    "items": {"type": "string"},
+                    "description": "Command line arguments to pass to the script"
+                }
+            },
+            "required": []
+        }
+    
+    def _extract_script_docstring(self, script_content: str) -> Optional[str]:
+        """Extract the module-level docstring from a Python script."""
+        try:
+            tree = ast.parse(script_content)
+            return ast.get_docstring(tree)
+        except Exception:
+            return None
+    
+    def _parse_argparse_schema(self, script_code: str) -> Optional[Dict[str, Any]]:
+        """
+        Parse argparse argument definitions from Python script code.
+        
+        Extracts add_argument calls and converts them to JSON schema format.
+        """
+        properties = {}
+        required = []
+        
+        # Pattern to match add_argument calls
+        arg_pattern = re.compile(
+            r'\.add_argument\s*\(\s*["\']([^"\']+)["\']'
+            r'(?:\s*,\s*["\']([^"\']+)["\'])?'
+            r'([^)]*)\)',
+            re.MULTILINE | re.DOTALL
+        )
+        
+        for match in arg_pattern.finditer(script_code):
+            arg_name = match.group(1)
+            second_arg = match.group(2)
+            kwargs_str = match.group(3)
+            
+            # Determine parameter name
+            if arg_name.startswith('--'):
+                param_name = arg_name[2:].replace('-', '_')
+                is_positional = False
+            elif arg_name.startswith('-'):
+                if second_arg and second_arg.startswith('--'):
+                    param_name = second_arg[2:].replace('-', '_')
+                else:
+                    param_name = arg_name[1:]
+                is_positional = False
+            else:
+                param_name = arg_name.replace('-', '_')
+                is_positional = True
+            
+            prop = {"type": "string"}
+            
+            # Extract help text
+            help_match = re.search(r'help\s*=\s*["\']([^"\']+)["\']', kwargs_str)
+            if help_match:
+                prop["description"] = help_match.group(1)
+            
+            # Extract type
+            type_match = re.search(r'type\s*=\s*(\w+)', kwargs_str)
+            if type_match:
+                type_name = type_match.group(1)
+                if type_name == 'int':
+                    prop["type"] = "integer"
+                elif type_name == 'float':
+                    prop["type"] = "number"
+                elif type_name == 'bool':
+                    prop["type"] = "boolean"
+            
+            # Check for action="store_true" or action="store_false"
+            action_match = re.search(r'action\s*=\s*["\'](\w+)["\']', kwargs_str)
+            if action_match:
+                action = action_match.group(1)
+                if action in ('store_true', 'store_false'):
+                    prop["type"] = "boolean"
+            
+            # Check for nargs
+            nargs_match = re.search(r'nargs\s*=\s*["\']?([^,\s\)]+)["\']?', kwargs_str)
+            if nargs_match:
+                nargs = nargs_match.group(1)
+                if nargs in ('*', '+') or nargs.isdigit():
+                    prop["type"] = "array"
+                    prop["items"] = {"type": "string"}
+            
+            # Check for choices
+            choices_match = re.search(r'choices\s*=\s*\[([^\]]+)\]', kwargs_str)
+            if choices_match:
+                choices_str = choices_match.group(1)
+                choices = re.findall(r'["\']([^"\']+)["\']', choices_str)
+                if choices:
+                    prop["enum"] = choices
+            
+            # Check for default
+            default_match = re.search(r'default\s*=\s*([^,\)]+)', kwargs_str)
+            if default_match:
+                default_val = default_match.group(1).strip()
+                if default_val not in ('None', '""', "''"):
+                    prop["default"] = default_val.strip('"\'')
+            
+            # Check if required
+            required_match = re.search(r'required\s*=\s*True', kwargs_str)
+            if required_match or is_positional:
+                required.append(param_name)
+            
+            properties[param_name] = prop
+        
+        if not properties:
+            return None
+        
+        return {
+            "type": "object",
+            "properties": properties,
+            "required": required
+        }
+    
+    def infer_all_schemas(self, force: bool = False) -> Dict[str, Dict[str, Any]]:
+        """
+        Infer schemas for all skills that don't have one defined.
+        
+        Args:
+            force: Force re-inference even if cached
+            
+        Returns:
+            Dict mapping skill name to inferred schema
+        """
+        if not self._schema_inferrer:
+            raise RuntimeError("Schema inferrer not configured.")
+        
+        results = {}
+        for info in self._registry.list_skills():
+            name = info.name
+            if info.metadata.input_schema:
+                results[name] = info.metadata.input_schema
+                continue
+            if not force and name in self._inferred_schemas:
+                results[name] = self._inferred_schemas[name]
+                continue
+            
+            schema = self._infer_skill_schema(info)
+            if schema:
+                self._inferred_schemas[name] = schema
+                results[name] = schema
+        
+        return results
+    
+    @property
+    def inferred_schemas(self) -> Dict[str, Dict[str, Any]]:
+        """Access to inferred schemas cache."""
+        return self._inferred_schemas