skills.py

"""Skills discovery and loading system.

Scans a skills directory for SKILL.md manifest files and maintains a registry
of available skills that can be loaded by the agent at runtime.
"""

from pathlib import Path

from config import get_logger
from utils import parse_frontmatter
from wcode_errors import ToolError

logger = get_logger(__name__)


class SkillRegistry:
    """In-memory registry of available skills.

    Scans *skills_dir* for ``SKILL.md`` manifests at construction time.
    Skills are keyed by their ``name`` frontmatter field (falling back to
    the directory name).

    Usage::

        registry = SkillRegistry(Path("skills"))
        print(registry.list_skills())
        content = registry.load_skill("my-skill")
    """

    def __init__(self, skills_dir: Path) -> None:
        self._skills_dir = skills_dir
        self._registry: dict[str, dict] = {}
        self._scan()

    # ── Public API ──────────────────────────────────────────────────────

    def list_skills(self) -> str:
        """Return a formatted markdown string listing all registered skills."""
        if not self._registry:
            return ""
        lines = ["## Available Skills"]
        for skill in self._registry.values():
            lines.append(f"- **{skill['name']}**: {skill['description']}")
        return "\n".join(lines)

    def load_skill(self, name: str) -> str:
        """Load the full SKILL.md content for a registered skill.

        Parameters
        ----------
        name : str
            The name of the skill to load (as shown in ``list_skills``).

        Returns
        -------
        str
            The raw SKILL.md content.

        Raises
        ------
        ToolError
            If the skill name is not found in the registry.
        """
        skill = self._registry.get(name)
        if not skill:
            raise ToolError(f"Skill '{name}' not found")
        return skill["content"]

    # ── Internal ────────────────────────────────────────────────────────

    def _scan(self) -> None:
        """Scan *self._skills_dir* and populate the registry."""
        if not self._skills_dir.exists():
            logger.warning(f"Skills directory {self._skills_dir} does not exist.")
            return
        for d in sorted(self._skills_dir.iterdir()):
            if not d.is_dir():
                continue
            manifest = d / "SKILL.md"
            if manifest.exists():
                raw = manifest.read_text()
                meta, content = parse_frontmatter(raw)
                name = meta.get("name", d.name)
                desc = meta.get("description", raw.split("\n")[0].lstrip("#").strip())
                self._registry[name] = {
                    "name": name,
                    "description": desc,
                    "content": raw,
                }


# ── Module-level convenience (delegates to a default registry) ────────────

_default_registry: SkillRegistry | None = None


def _get_default_registry() -> SkillRegistry:
    """Lazily create and return a default SkillRegistry for the workspace."""
    global _default_registry
    if _default_registry is None:
        from config import SKILLS_DIR
        _default_registry = SkillRegistry(SKILLS_DIR)
    return _default_registry


def list_skills() -> str:
    """Module-level shim — delegates to the default registry."""
    return _get_default_registry().list_skills()


def run_load_skill(name: str) -> str:
    """Module-level shim for tool registration — delegates to the default registry."""
    return _get_default_registry().load_skill(name)