feat: support skills

agent/skills/__init__.py

@@ -0,0 +1,29 @@
+"""
+Skills module for agent system.
+
+This module provides the framework for loading, managing, and executing skills.
+Skills are markdown files with frontmatter that provide specialized instructions
+for specific tasks.
+"""
+
+from agent.skills.types import (
+    Skill,
+    SkillEntry,
+    SkillMetadata,
+    SkillInstallSpec,
+    LoadSkillsResult,
+)
+from agent.skills.loader import SkillLoader
+from agent.skills.manager import SkillManager
+from agent.skills.formatter import format_skills_for_prompt
+
+__all__ = [
+    "Skill",
+    "SkillEntry",
+    "SkillMetadata",
+    "SkillInstallSpec",
+    "LoadSkillsResult",
+    "SkillLoader",
+    "SkillManager",
+    "format_skills_for_prompt",
+]

agent/skills/config.py

@@ -0,0 +1,211 @@
+"""
+Configuration support for skills.
+"""
+
+import os
+import platform
+from typing import Dict, Optional, List
+from agent.skills.types import SkillEntry
+
+
+def resolve_runtime_platform() -> str:
+    """Get the current runtime platform."""
+    return platform.system().lower()
+
+
+def has_binary(bin_name: str) -> bool:
+    """
+    Check if a binary is available in PATH.
+    
+    :param bin_name: Binary name to check
+    :return: True if binary is available
+    """
+    import shutil
+    return shutil.which(bin_name) is not None
+
+
+def has_any_binary(bin_names: List[str]) -> bool:
+    """
+    Check if any of the given binaries is available.
+    
+    :param bin_names: List of binary names to check
+    :return: True if at least one binary is available
+    """
+    return any(has_binary(bin_name) for bin_name in bin_names)
+
+
+def has_env_var(env_name: str) -> bool:
+    """
+    Check if an environment variable is set.
+    
+    :param env_name: Environment variable name
+    :return: True if environment variable is set
+    """
+    return env_name in os.environ and bool(os.environ[env_name].strip())
+
+
+def get_skill_config(config: Optional[Dict], skill_name: str) -> Optional[Dict]:
+    """
+    Get skill-specific configuration.
+    
+    :param config: Global configuration dictionary
+    :param skill_name: Name of the skill
+    :return: Skill configuration or None
+    """
+    if not config:
+        return None
+    
+    skills_config = config.get('skills', {})
+    if not isinstance(skills_config, dict):
+        return None
+    
+    entries = skills_config.get('entries', {})
+    if not isinstance(entries, dict):
+        return None
+    
+    return entries.get(skill_name)
+
+
+def should_include_skill(
+    entry: SkillEntry,
+    config: Optional[Dict] = None,
+    current_platform: Optional[str] = None,
+    lenient: bool = True,
+) -> bool:
+    """
+    Determine if a skill should be included based on requirements.
+    
+    Similar to clawdbot's shouldIncludeSkill logic, but with lenient mode:
+    - In lenient mode (default): Only check explicit disable and platform, ignore missing requirements
+    - In strict mode: Check all requirements (binary, env vars, config)
+    
+    :param entry: SkillEntry to check
+    :param config: Configuration dictionary
+    :param current_platform: Current platform (default: auto-detect)
+    :param lenient: If True, ignore missing requirements and load all skills (default: True)
+    :return: True if skill should be included
+    """
+    metadata = entry.metadata
+    skill_name = entry.skill.name
+    skill_config = get_skill_config(config, skill_name)
+    
+    # Always check if skill is explicitly disabled in config
+    if skill_config and skill_config.get('enabled') is False:
+        return False
+    
+    if not metadata:
+        return True
+    
+    # Always check platform requirements (can't work on wrong platform)
+    if metadata.os:
+        platform_name = current_platform or resolve_runtime_platform()
+        # Map common platform names
+        platform_map = {
+            'darwin': 'darwin',
+            'linux': 'linux',
+            'windows': 'win32',
+        }
+        normalized_platform = platform_map.get(platform_name, platform_name)
+        
+        if normalized_platform not in metadata.os:
+            return False
+    
+    # If skill has 'always: true', include it regardless of other requirements
+    if metadata.always:
+        return True
+    
+    # In lenient mode, skip requirement checks and load all skills
+    # Skills will fail gracefully at runtime if requirements are missing
+    if lenient:
+        return True
+    
+    # Strict mode: Check all requirements
+    if metadata.requires:
+        # Check required binaries (all must be present)
+        required_bins = metadata.requires.get('bins', [])
+        if required_bins:
+            if not all(has_binary(bin_name) for bin_name in required_bins):
+                return False
+        
+        # Check anyBins (at least one must be present)
+        any_bins = metadata.requires.get('anyBins', [])
+        if any_bins:
+            if not has_any_binary(any_bins):
+                return False
+        
+        # Check environment variables (with config fallback)
+        required_env = metadata.requires.get('env', [])
+        if required_env:
+            for env_name in required_env:
+                # Check in order: 1) env var, 2) skill config env, 3) skill config apiKey (if primaryEnv)
+                if has_env_var(env_name):
+                    continue
+                if skill_config:
+                    # Check skill config env dict
+                    skill_env = skill_config.get('env', {})
+                    if isinstance(skill_env, dict) and env_name in skill_env:
+                        continue
+                    # Check skill config apiKey (if this is the primaryEnv)
+                    if metadata.primary_env == env_name and skill_config.get('apiKey'):
+                        continue
+                # Requirement not satisfied
+                return False
+        
+        # Check config paths
+        required_config = metadata.requires.get('config', [])
+        if required_config and config:
+            for config_path in required_config:
+                if not is_config_path_truthy(config, config_path):
+                    return False
+    
+    return True
+
+
+def is_config_path_truthy(config: Dict, path: str) -> bool:
+    """
+    Check if a config path resolves to a truthy value.
+    
+    :param config: Configuration dictionary
+    :param path: Dot-separated path (e.g., 'skills.enabled')
+    :return: True if path resolves to truthy value
+    """
+    parts = path.split('.')
+    current = config
+    
+    for part in parts:
+        if not isinstance(current, dict):
+            return False
+        current = current.get(part)
+        if current is None:
+            return False
+    
+    # Check if value is truthy
+    if isinstance(current, bool):
+        return current
+    if isinstance(current, (int, float)):
+        return current != 0
+    if isinstance(current, str):
+        return bool(current.strip())
+    
+    return bool(current)
+
+
+def resolve_config_path(config: Dict, path: str):
+    """
+    Resolve a dot-separated config path to its value.
+    
+    :param config: Configuration dictionary
+    :param path: Dot-separated path
+    :return: Value at path or None
+    """
+    parts = path.split('.')
+    current = config
+    
+    for part in parts:
+        if not isinstance(current, dict):
+            return None
+        current = current.get(part)
+        if current is None:
+            return None
+    
+    return current

agent/skills/formatter.py

@@ -0,0 +1,62 @@
+"""
+Skill formatter for generating prompts from skills.
+"""
+
+from typing import List
+from agent.skills.types import Skill, SkillEntry
+
+
+def format_skills_for_prompt(skills: List[Skill]) -> str:
+    """
+    Format skills for inclusion in a system prompt.
+    
+    Uses XML format per Agent Skills standard.
+    Skills with disable_model_invocation=True are excluded.
+    
+    :param skills: List of skills to format
+    :return: Formatted prompt text
+    """
+    # Filter out skills that should not be invoked by the model
+    visible_skills = [s for s in skills if not s.disable_model_invocation]
+    
+    if not visible_skills:
+        return ""
+    
+    lines = [
+        "\n\nThe following skills provide specialized instructions for specific tasks.",
+        "Use the read tool to load a skill's file when the task matches its description.",
+        "",
+        "<available_skills>",
+    ]
+    
+    for skill in visible_skills:
+        lines.append("  <skill>")
+        lines.append(f"    <name>{_escape_xml(skill.name)}</name>")
+        lines.append(f"    <description>{_escape_xml(skill.description)}</description>")
+        lines.append(f"    <location>{_escape_xml(skill.file_path)}</location>")
+        lines.append("  </skill>")
+    
+    lines.append("</available_skills>")
+    
+    return "\n".join(lines)
+
+
+def format_skill_entries_for_prompt(entries: List[SkillEntry]) -> str:
+    """
+    Format skill entries for inclusion in a system prompt.
+    
+    :param entries: List of skill entries to format
+    :return: Formatted prompt text
+    """
+    skills = [entry.skill for entry in entries]
+    return format_skills_for_prompt(skills)
+
+
+def _escape_xml(text: str) -> str:
+    """Escape XML special characters."""
+    return (text
+            .replace('&', '&amp;')
+            .replace('<', '&lt;')
+            .replace('>', '&gt;')
+            .replace('"', '&quot;')
+            .replace("'", '&apos;'))

agent/skills/frontmatter.py

@@ -0,0 +1,159 @@
+"""
+Frontmatter parsing for skills.
+"""
+
+import re
+import json
+from typing import Dict, Any, Optional, List
+from agent.skills.types import SkillMetadata, SkillInstallSpec
+
+
+def parse_frontmatter(content: str) -> Dict[str, Any]:
+    """
+    Parse YAML-style frontmatter from markdown content.
+    
+    Returns a dictionary of frontmatter fields.
+    """
+    frontmatter = {}
+    
+    # Match frontmatter block between --- markers
+    match = re.match(r'^---\s*\n(.*?)\n---\s*\n', content, re.DOTALL)
+    if not match:
+        return frontmatter
+    
+    frontmatter_text = match.group(1)
+    
+    # Simple YAML-like parsing (supports key: value format)
+    for line in frontmatter_text.split('\n'):
+        line = line.strip()
+        if not line or line.startswith('#'):
+            continue
+        
+        if ':' in line:
+            key, value = line.split(':', 1)
+            key = key.strip()
+            value = value.strip()
+            
+            # Try to parse as JSON if it looks like JSON
+            if value.startswith('{') or value.startswith('['):
+                try:
+                    value = json.loads(value)
+                except json.JSONDecodeError:
+                    pass
+            # Parse boolean values
+            elif value.lower() in ('true', 'false'):
+                value = value.lower() == 'true'
+            # Parse numbers
+            elif value.isdigit():
+                value = int(value)
+            
+            frontmatter[key] = value
+    
+    return frontmatter
+
+
+def parse_metadata(frontmatter: Dict[str, Any]) -> Optional[SkillMetadata]:
+    """
+    Parse skill metadata from frontmatter.
+    
+    Looks for 'metadata' field containing JSON with skill configuration.
+    """
+    metadata_raw = frontmatter.get('metadata')
+    if not metadata_raw:
+        return None
+    
+    # If it's a string, try to parse as JSON
+    if isinstance(metadata_raw, str):
+        try:
+            metadata_raw = json.loads(metadata_raw)
+        except json.JSONDecodeError:
+            return None
+    
+    if not isinstance(metadata_raw, dict):
+        return None
+    
+    # Support both 'moltbot' and 'cow' keys for compatibility
+    meta_obj = metadata_raw.get('moltbot') or metadata_raw.get('cow')
+    if not meta_obj or not isinstance(meta_obj, dict):
+        return None
+    
+    # Parse install specs
+    install_specs = []
+    install_raw = meta_obj.get('install', [])
+    if isinstance(install_raw, list):
+        for spec_raw in install_raw:
+            if not isinstance(spec_raw, dict):
+                continue
+            
+            kind = spec_raw.get('kind', spec_raw.get('type', '')).lower()
+            if not kind:
+                continue
+            
+            spec = SkillInstallSpec(
+                kind=kind,
+                id=spec_raw.get('id'),
+                label=spec_raw.get('label'),
+                bins=_normalize_string_list(spec_raw.get('bins')),
+                os=_normalize_string_list(spec_raw.get('os')),
+                formula=spec_raw.get('formula'),
+                package=spec_raw.get('package'),
+                module=spec_raw.get('module'),
+                url=spec_raw.get('url'),
+                archive=spec_raw.get('archive'),
+                extract=spec_raw.get('extract', False),
+                strip_components=spec_raw.get('stripComponents'),
+                target_dir=spec_raw.get('targetDir'),
+            )
+            install_specs.append(spec)
+    
+    # Parse requires
+    requires = {}
+    requires_raw = meta_obj.get('requires', {})
+    if isinstance(requires_raw, dict):
+        for key, value in requires_raw.items():
+            requires[key] = _normalize_string_list(value)
+    
+    return SkillMetadata(
+        always=meta_obj.get('always', False),
+        skill_key=meta_obj.get('skillKey'),
+        primary_env=meta_obj.get('primaryEnv'),
+        emoji=meta_obj.get('emoji'),
+        homepage=meta_obj.get('homepage'),
+        os=_normalize_string_list(meta_obj.get('os')),
+        requires=requires,
+        install=install_specs,
+    )
+
+
+def _normalize_string_list(value: Any) -> List[str]:
+    """Normalize a value to a list of strings."""
+    if not value:
+        return []
+    
+    if isinstance(value, list):
+        return [str(v).strip() for v in value if v]
+    
+    if isinstance(value, str):
+        return [v.strip() for v in value.split(',') if v.strip()]
+    
+    return []
+
+
+def parse_boolean_value(value: Optional[str], default: bool = False) -> bool:
+    """Parse a boolean value from frontmatter."""
+    if value is None:
+        return default
+    
+    if isinstance(value, bool):
+        return value
+    
+    if isinstance(value, str):
+        return value.lower() in ('true', '1', 'yes', 'on')
+    
+    return default
+
+
+def get_frontmatter_value(frontmatter: Dict[str, Any], key: str) -> Optional[str]:
+    """Get a frontmatter value as a string."""
+    value = frontmatter.get(key)
+    return str(value) if value is not None else None

agent/skills/loader.py

@@ -0,0 +1,242 @@
+"""
+Skill loader for discovering and loading skills from directories.
+"""
+
+import os
+from pathlib import Path
+from typing import List, Optional, Dict
+from common.log import logger
+from agent.skills.types import Skill, SkillEntry, LoadSkillsResult, SkillMetadata
+from agent.skills.frontmatter import parse_frontmatter, parse_metadata, parse_boolean_value, get_frontmatter_value
+
+
+class SkillLoader:
+    """Loads skills from various directories."""
+    
+    def __init__(self, workspace_dir: Optional[str] = None):
+        """
+        Initialize the skill loader.
+        
+        :param workspace_dir: Agent workspace directory (for workspace-specific skills)
+        """
+        self.workspace_dir = workspace_dir
+    
+    def load_skills_from_dir(self, dir_path: str, source: str) -> LoadSkillsResult:
+        """
+        Load skills from a directory.
+        
+        Discovery rules:
+        - Direct .md files in the root directory
+        - Recursive SKILL.md files under subdirectories
+        
+        :param dir_path: Directory path to scan
+        :param source: Source identifier (e.g., 'managed', 'workspace', 'bundled')
+        :return: LoadSkillsResult with skills and diagnostics
+        """
+        skills = []
+        diagnostics = []
+        
+        if not os.path.exists(dir_path):
+            diagnostics.append(f"Directory does not exist: {dir_path}")
+            return LoadSkillsResult(skills=skills, diagnostics=diagnostics)
+        
+        if not os.path.isdir(dir_path):
+            diagnostics.append(f"Path is not a directory: {dir_path}")
+            return LoadSkillsResult(skills=skills, diagnostics=diagnostics)
+        
+        # Load skills from root-level .md files and subdirectories
+        result = self._load_skills_recursive(dir_path, source, include_root_files=True)
+        
+        return result
+    
+    def _load_skills_recursive(
+        self, 
+        dir_path: str, 
+        source: str, 
+        include_root_files: bool = False
+    ) -> LoadSkillsResult:
+        """
+        Recursively load skills from a directory.
+        
+        :param dir_path: Directory to scan
+        :param source: Source identifier
+        :param include_root_files: Whether to include root-level .md files
+        :return: LoadSkillsResult
+        """
+        skills = []
+        diagnostics = []
+        
+        try:
+            entries = os.listdir(dir_path)
+        except Exception as e:
+            diagnostics.append(f"Failed to list directory {dir_path}: {e}")
+            return LoadSkillsResult(skills=skills, diagnostics=diagnostics)
+        
+        for entry in entries:
+            # Skip hidden files and directories
+            if entry.startswith('.'):
+                continue
+            
+            # Skip common non-skill directories
+            if entry in ('node_modules', '__pycache__', 'venv', '.git'):
+                continue
+            
+            full_path = os.path.join(dir_path, entry)
+            
+            # Handle directories
+            if os.path.isdir(full_path):
+                # Recursively scan subdirectories
+                sub_result = self._load_skills_recursive(full_path, source, include_root_files=False)
+                skills.extend(sub_result.skills)
+                diagnostics.extend(sub_result.diagnostics)
+                continue
+            
+            # Handle files
+            if not os.path.isfile(full_path):
+                continue
+            
+            # Check if this is a skill file
+            is_root_md = include_root_files and entry.endswith('.md')
+            is_skill_md = not include_root_files and entry == 'SKILL.md'
+            
+            if not (is_root_md or is_skill_md):
+                continue
+            
+            # Load the skill
+            skill_result = self._load_skill_from_file(full_path, source)
+            if skill_result.skills:
+                skills.extend(skill_result.skills)
+            diagnostics.extend(skill_result.diagnostics)
+        
+        return LoadSkillsResult(skills=skills, diagnostics=diagnostics)
+    
+    def _load_skill_from_file(self, file_path: str, source: str) -> LoadSkillsResult:
+        """
+        Load a single skill from a markdown file.
+        
+        :param file_path: Path to the skill markdown file
+        :param source: Source identifier
+        :return: LoadSkillsResult
+        """
+        diagnostics = []
+        
+        try:
+            with open(file_path, 'r', encoding='utf-8') as f:
+                content = f.read()
+        except Exception as e:
+            diagnostics.append(f"Failed to read skill file {file_path}: {e}")
+            return LoadSkillsResult(skills=[], diagnostics=diagnostics)
+        
+        # Parse frontmatter
+        frontmatter = parse_frontmatter(content)
+        
+        # Get skill name and description
+        skill_dir = os.path.dirname(file_path)
+        parent_dir_name = os.path.basename(skill_dir)
+        
+        name = frontmatter.get('name', parent_dir_name)
+        description = frontmatter.get('description', '')
+        
+        if not description or not description.strip():
+            diagnostics.append(f"Skill {name} has no description: {file_path}")
+            return LoadSkillsResult(skills=[], diagnostics=diagnostics)
+        
+        # Parse disable-model-invocation flag
+        disable_model_invocation = parse_boolean_value(
+            get_frontmatter_value(frontmatter, 'disable-model-invocation'),
+            default=False
+        )
+        
+        # Create skill object
+        skill = Skill(
+            name=name,
+            description=description,
+            file_path=file_path,
+            base_dir=skill_dir,
+            source=source,
+            content=content,
+            disable_model_invocation=disable_model_invocation,
+            frontmatter=frontmatter,
+        )
+        
+        return LoadSkillsResult(skills=[skill], diagnostics=diagnostics)
+    
+    def load_all_skills(
+        self,
+        managed_dir: Optional[str] = None,
+        workspace_skills_dir: Optional[str] = None,
+        extra_dirs: Optional[List[str]] = None,
+    ) -> Dict[str, SkillEntry]:
+        """
+        Load skills from all configured locations with precedence.
+        
+        Precedence (lowest to highest):
+        1. Extra directories
+        2. Managed skills directory
+        3. Workspace skills directory
+        
+        :param managed_dir: Managed skills directory (e.g., ~/.cow/skills)
+        :param workspace_skills_dir: Workspace skills directory (e.g., workspace/skills)
+        :param extra_dirs: Additional directories to load skills from
+        :return: Dictionary mapping skill name to SkillEntry
+        """
+        skill_map: Dict[str, SkillEntry] = {}
+        all_diagnostics = []
+        
+        # Load from extra directories (lowest precedence)
+        if extra_dirs:
+            for extra_dir in extra_dirs:
+                if not os.path.exists(extra_dir):
+                    continue
+                result = self.load_skills_from_dir(extra_dir, source='extra')
+                all_diagnostics.extend(result.diagnostics)
+                for skill in result.skills:
+                    entry = self._create_skill_entry(skill)
+                    skill_map[skill.name] = entry
+        
+        # Load from managed directory
+        if managed_dir and os.path.exists(managed_dir):
+            result = self.load_skills_from_dir(managed_dir, source='managed')
+            all_diagnostics.extend(result.diagnostics)
+            for skill in result.skills:
+                entry = self._create_skill_entry(skill)
+                skill_map[skill.name] = entry
+        
+        # Load from workspace directory (highest precedence)
+        if workspace_skills_dir and os.path.exists(workspace_skills_dir):
+            result = self.load_skills_from_dir(workspace_skills_dir, source='workspace')
+            all_diagnostics.extend(result.diagnostics)
+            for skill in result.skills:
+                entry = self._create_skill_entry(skill)
+                skill_map[skill.name] = entry
+        
+        # Log diagnostics
+        if all_diagnostics:
+            logger.debug(f"Skill loading diagnostics: {len(all_diagnostics)} issues")
+            for diag in all_diagnostics[:5]:  # Log first 5
+                logger.debug(f"  - {diag}")
+        
+        logger.info(f"Loaded {len(skill_map)} skills from all sources")
+        
+        return skill_map
+    
+    def _create_skill_entry(self, skill: Skill) -> SkillEntry:
+        """
+        Create a SkillEntry from a Skill with parsed metadata.
+        
+        :param skill: The skill to create an entry for
+        :return: SkillEntry with metadata
+        """
+        metadata = parse_metadata(skill.frontmatter)
+        
+        # Parse user-invocable flag
+        user_invocable = parse_boolean_value(
+            get_frontmatter_value(skill.frontmatter, 'user-invocable'),
+            default=True
+        )
+        
+        return SkillEntry(
+            skill=skill,
+            metadata=metadata,
+            user_invocable=user_invocable,
+        )

agent/skills/manager.py

@@ -0,0 +1,214 @@
+"""
+Skill manager for managing skill lifecycle and operations.
+"""
+
+import os
+from typing import Dict, List, Optional
+from pathlib import Path
+from common.log import logger
+from agent.skills.types import Skill, SkillEntry, SkillSnapshot
+from agent.skills.loader import SkillLoader
+from agent.skills.formatter import format_skill_entries_for_prompt
+
+
+class SkillManager:
+    """Manages skills for an agent."""
+    
+    def __init__(
+        self,
+        workspace_dir: Optional[str] = None,
+        managed_skills_dir: Optional[str] = None,
+        extra_dirs: Optional[List[str]] = None,
+        config: Optional[Dict] = None,
+    ):
+        """
+        Initialize the skill manager.
+        
+        :param workspace_dir: Agent workspace directory
+        :param managed_skills_dir: Managed skills directory (e.g., ~/.cow/skills)
+        :param extra_dirs: Additional skill directories
+        :param config: Configuration dictionary
+        """
+        self.workspace_dir = workspace_dir
+        self.managed_skills_dir = managed_skills_dir or self._get_default_managed_dir()
+        self.extra_dirs = extra_dirs or []
+        self.config = config or {}
+        
+        self.loader = SkillLoader(workspace_dir=workspace_dir)
+        self.skills: Dict[str, SkillEntry] = {}
+        
+        # Load skills on initialization
+        self.refresh_skills()
+    
+    def _get_default_managed_dir(self) -> str:
+        """Get the default managed skills directory."""
+        # Use project root skills directory as default
+        import os
+        project_root = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+        return os.path.join(project_root, 'skills')
+    
+    def refresh_skills(self):
+        """Reload all skills from configured directories."""
+        workspace_skills_dir = None
+        if self.workspace_dir:
+            workspace_skills_dir = os.path.join(self.workspace_dir, 'skills')
+        
+        self.skills = self.loader.load_all_skills(
+            managed_dir=self.managed_skills_dir,
+            workspace_skills_dir=workspace_skills_dir,
+            extra_dirs=self.extra_dirs,
+        )
+        
+        logger.info(f"SkillManager: Loaded {len(self.skills)} skills")
+    
+    def get_skill(self, name: str) -> Optional[SkillEntry]:
+        """
+        Get a skill by name.
+        
+        :param name: Skill name
+        :return: SkillEntry or None if not found
+        """
+        return self.skills.get(name)
+    
+    def list_skills(self) -> List[SkillEntry]:
+        """
+        Get all loaded skills.
+        
+        :return: List of all skill entries
+        """
+        return list(self.skills.values())
+    
+    def filter_skills(
+        self,
+        skill_filter: Optional[List[str]] = None,
+        include_disabled: bool = False,
+        check_requirements: bool = False,  # Changed default to False for lenient loading
+        lenient: bool = True,  # New parameter for lenient mode
+    ) -> List[SkillEntry]:
+        """
+        Filter skills based on criteria.
+        
+        By default (lenient=True), all skills are loaded regardless of missing requirements.
+        Skills will fail gracefully at runtime if requirements are not met.
+        
+        :param skill_filter: List of skill names to include (None = all)
+        :param include_disabled: Whether to include skills with disable_model_invocation=True
+        :param check_requirements: Whether to check skill requirements (default: False)
+        :param lenient: If True, ignore missing requirements (default: True)
+        :return: Filtered list of skill entries
+        """
+        from agent.skills.config import should_include_skill
+        
+        entries = list(self.skills.values())
+        
+        # Check requirements (platform, explicit disable, etc.)
+        # In lenient mode, only checks platform and explicit disable
+        if check_requirements or not lenient:
+            entries = [e for e in entries if should_include_skill(e, self.config, lenient=lenient)]
+        else:
+            # Lenient mode: only check explicit disable and platform
+            entries = [e for e in entries if should_include_skill(e, self.config, lenient=True)]
+        
+        # Apply skill filter
+        if skill_filter is not None:
+            normalized = [name.strip() for name in skill_filter if name.strip()]
+            if normalized:
+                entries = [e for e in entries if e.skill.name in normalized]
+        
+        # Filter out disabled skills unless explicitly requested
+        if not include_disabled:
+            entries = [e for e in entries if not e.skill.disable_model_invocation]
+        
+        return entries
+    
+    def build_skills_prompt(
+        self,
+        skill_filter: Optional[List[str]] = None,
+    ) -> str:
+        """
+        Build a formatted prompt containing available skills.
+        
+        :param skill_filter: Optional list of skill names to include
+        :return: Formatted skills prompt
+        """
+        entries = self.filter_skills(skill_filter=skill_filter, include_disabled=False)
+        return format_skill_entries_for_prompt(entries)
+    
+    def build_skill_snapshot(
+        self,
+        skill_filter: Optional[List[str]] = None,
+        version: Optional[int] = None,
+    ) -> SkillSnapshot:
+        """
+        Build a snapshot of skills for a specific run.
+        
+        :param skill_filter: Optional list of skill names to include
+        :param version: Optional version number for the snapshot
+        :return: SkillSnapshot
+        """
+        entries = self.filter_skills(skill_filter=skill_filter, include_disabled=False)
+        prompt = format_skill_entries_for_prompt(entries)
+        
+        skills_info = []
+        resolved_skills = []
+        
+        for entry in entries:
+            skills_info.append({
+                'name': entry.skill.name,
+                'primary_env': entry.metadata.primary_env if entry.metadata else None,
+            })
+            resolved_skills.append(entry.skill)
+        
+        return SkillSnapshot(
+            prompt=prompt,
+            skills=skills_info,
+            resolved_skills=resolved_skills,
+            version=version,
+        )
+    
+    def sync_skills_to_workspace(self, target_workspace_dir: str):
+        """
+        Sync all loaded skills to a target workspace directory.
+        
+        This is useful for sandbox environments where skills need to be copied.
+        
+        :param target_workspace_dir: Target workspace directory
+        """
+        import shutil
+        
+        target_skills_dir = os.path.join(target_workspace_dir, 'skills')
+        
+        # Remove existing skills directory
+        if os.path.exists(target_skills_dir):
+            shutil.rmtree(target_skills_dir)
+        
+        # Create new skills directory
+        os.makedirs(target_skills_dir, exist_ok=True)
+        
+        # Copy each skill
+        for entry in self.skills.values():
+            skill_name = entry.skill.name
+            source_dir = entry.skill.base_dir
+            target_dir = os.path.join(target_skills_dir, skill_name)
+            
+            try:
+                shutil.copytree(source_dir, target_dir)
+                logger.debug(f"Synced skill '{skill_name}' to {target_dir}")
+            except Exception as e:
+                logger.warning(f"Failed to sync skill '{skill_name}': {e}")
+        
+        logger.info(f"Synced {len(self.skills)} skills to {target_skills_dir}")
+    
+    def get_skill_by_key(self, skill_key: str) -> Optional[SkillEntry]:
+        """
+        Get a skill by its skill key (which may differ from name).
+        
+        :param skill_key: Skill key to look up
+        :return: SkillEntry or None
+        """
+        for entry in self.skills.values():
+            if entry.metadata and entry.metadata.skill_key == skill_key:
+                return entry
+            if entry.skill.name == skill_key:
+                return entry
+        return None

agent/skills/types.py

@@ -0,0 +1,74 @@
+"""
+Type definitions for skills system.
+"""
+
+from typing import Dict, List, Optional, Any
+from dataclasses import dataclass, field
+
+
+@dataclass
+class SkillInstallSpec:
+    """Specification for installing skill dependencies."""
+    kind: str  # brew, pip, npm, download, etc.
+    id: Optional[str] = None
+    label: Optional[str] = None
+    bins: List[str] = field(default_factory=list)
+    os: List[str] = field(default_factory=list)
+    formula: Optional[str] = None  # for brew
+    package: Optional[str] = None  # for pip/npm
+    module: Optional[str] = None
+    url: Optional[str] = None  # for download
+    archive: Optional[str] = None
+    extract: bool = False
+    strip_components: Optional[int] = None
+    target_dir: Optional[str] = None
+
+
+@dataclass
+class SkillMetadata:
+    """Metadata for a skill from frontmatter."""
+    always: bool = False  # Always include this skill
+    skill_key: Optional[str] = None  # Override skill key
+    primary_env: Optional[str] = None  # Primary environment variable
+    emoji: Optional[str] = None
+    homepage: Optional[str] = None
+    os: List[str] = field(default_factory=list)  # Supported OS platforms
+    requires: Dict[str, List[str]] = field(default_factory=dict)  # Requirements
+    install: List[SkillInstallSpec] = field(default_factory=list)
+
+
+@dataclass
+class Skill:
+    """Represents a skill loaded from a markdown file."""
+    name: str
+    description: str
+    file_path: str
+    base_dir: str
+    source: str  # managed, workspace, bundled, etc.
+    content: str  # Full markdown content
+    disable_model_invocation: bool = False
+    frontmatter: Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class SkillEntry:
+    """A skill with parsed metadata."""
+    skill: Skill
+    metadata: Optional[SkillMetadata] = None
+    user_invocable: bool = True  # Can users invoke this skill directly
+
+
+@dataclass
+class LoadSkillsResult:
+    """Result of loading skills from a directory."""
+    skills: List[Skill]
+    diagnostics: List[str] = field(default_factory=list)
+
+
+@dataclass
+class SkillSnapshot:
+    """Snapshot of skills for a specific run."""
+    prompt: str  # Formatted prompt text
+    skills: List[Dict[str, str]]  # List of skill info (name, primary_env)
+    resolved_skills: List[Skill] = field(default_factory=list)
+    version: Optional[int] = None