code-puppy-core-plugins 0.0.2__py3-none-any.whl

code_puppy_core_plugins/agent_skills/metadata.py

@@ -0,0 +1,219 @@
+"""Skill metadata parsing - extracts info from SKILL.md frontmatter."""
+
+import logging
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import List, Optional
+
+logger = logging.getLogger(__name__)
+
+# Regex pattern to match YAML frontmatter between --- delimiters
+FRONTMATTER_PATTERN = re.compile(r"^---\s*\n(.*?)\n---\s*\n", re.DOTALL)
+
+# Regex patterns for parsing simple key-value pairs from YAML-like frontmatter
+KEY_VALUE_PATTERN = re.compile(r"^([a-zA-Z_][a-zA-Z0-9_]*):\s*(.*)$", re.MULTILINE)
+LIST_PATTERN = re.compile(r"^\s+-\s+(.+)$", re.MULTILINE)
+
+
+@dataclass
+class SkillMetadata:
+    """Parsed skill metadata from SKILL.md frontmatter."""
+
+    name: str
+    description: str
+    path: Path
+    version: Optional[str] = None
+    author: Optional[str] = None
+    tags: List[str] = field(default_factory=list)
+
+
+def _unquote(value: str) -> str:
+    """Remove quotes from a YAML string value if present."""
+    value = value.strip()
+    if (value.startswith('"') and value.endswith('"')) or (
+        value.startswith("'") and value.endswith("'")
+    ):
+        return value[1:-1]
+    return value
+
+
+def parse_yaml_frontmatter(content: str) -> dict:
+    """Extract YAML frontmatter from SKILL.md content.
+
+    Frontmatter is between --- delimiters at the start of file.
+    Uses simple regex parsing to avoid heavy yaml dependency.
+
+    Args:
+        content: The full content of the SKILL.md file.
+
+    Returns:
+        Dictionary containing parsed frontmatter key-value pairs.
+        Returns empty dict if no frontmatter found or parsing fails.
+    """
+    match = FRONTMATTER_PATTERN.match(content)
+    if not match:
+        logger.debug("No frontmatter found in content")
+        return {}
+
+    frontmatter = match.group(1)
+    result: dict = {}
+    current_key: Optional[str] = None
+    current_list: List[str] = []
+
+    for line in frontmatter.split("\n"):
+        stripped = line.strip()
+
+        # Skip empty lines and comments
+        if not stripped or stripped.startswith("#"):
+            continue
+
+        # Check if this is a list item
+        list_match = LIST_PATTERN.match(line)
+        if list_match and current_key:
+            current_list.append(_unquote(list_match.group(1)))
+            continue
+
+        # Check if this is a key-value pair
+        kv_match = KEY_VALUE_PATTERN.match(line)
+        if kv_match:
+            # Save any accumulated list items from previous key
+            if current_key and current_list:
+                result[current_key] = current_list
+                current_list = []
+
+            key, value = kv_match.groups()
+            key = key.strip()
+            value = value.strip()
+
+            # If value is empty, this might be a list start
+            if not value:
+                current_key = key
+                result[key] = []  # Initialize as empty list
+            else:
+                result[key] = _unquote(value)
+                current_key = None
+
+    # Handle case where list items were at the end
+    if current_key and current_list:
+        result[current_key] = current_list
+
+    return result
+
+
+def parse_skill_metadata(skill_path: Path) -> Optional[SkillMetadata]:
+    """Parse metadata from a skill's SKILL.md file.
+
+    Args:
+        skill_path: Path to the skill directory (not the SKILL.md file)
+
+    Returns:
+        SkillMetadata if successful, None if parsing fails.
+    """
+    if not skill_path.exists():
+        logger.debug(f"Skill path does not exist: {skill_path}")
+        return None
+
+    skill_md_path = skill_path / "SKILL.md"
+    if not skill_md_path.exists():
+        logger.debug(f"SKILL.md not found in skill directory: {skill_path}")
+        return None
+
+    try:
+        content = skill_md_path.read_text(encoding="utf-8")
+    except Exception as e:
+        logger.error(f"Failed to read SKILL.md at {skill_md_path}: {e}")
+        return None
+
+    frontmatter = parse_yaml_frontmatter(content)
+    if not frontmatter:
+        logger.debug(f"No valid frontmatter found in {skill_md_path}")
+        return None
+
+    # Required fields
+    name = frontmatter.get("name")
+    if not name:
+        logger.debug(
+            f"'name' is required in frontmatter but not found in {skill_md_path}"
+        )
+        return None
+
+    description = frontmatter.get("description")
+    if not description:
+        logger.debug(
+            f"'description' is required in frontmatter but not found in {skill_md_path}"
+        )
+        return None
+
+    # Handle tags - could be a list or a comma-separated string
+    tags: List[str] = []
+    raw_tags = frontmatter.get("tags", [])
+    if isinstance(raw_tags, list):
+        tags = raw_tags
+    elif isinstance(raw_tags, str):
+        tags = [tag.strip() for tag in raw_tags.split(",") if tag.strip()]
+
+    return SkillMetadata(
+        name=name,
+        description=description,
+        path=skill_path,
+        version=frontmatter.get("version"),
+        author=frontmatter.get("author"),
+        tags=tags,
+    )
+
+
+def load_full_skill_content(skill_path: Path) -> Optional[str]:
+    """Load the complete SKILL.md content for activation.
+
+    Args:
+        skill_path: Path to the skill directory
+
+    Returns:
+        Full file content as string, or None if not found.
+    """
+    if not skill_path.exists():
+        logger.debug(f"Skill path does not exist: {skill_path}")
+        return None
+
+    skill_md_path = skill_path / "SKILL.md"
+    if not skill_md_path.exists():
+        logger.debug(f"SKILL.md not found in skill directory: {skill_path}")
+        return None
+
+    try:
+        return skill_md_path.read_text(encoding="utf-8")
+    except Exception as e:
+        logger.error(f"Failed to read SKILL.md at {skill_md_path}: {e}")
+        return None
+
+
+def get_skill_resources(skill_path: Path) -> List[Path]:
+    """List all resource files bundled with a skill.
+
+    Returns paths to all non-SKILL.md files in the skill directory.
+
+    Args:
+        skill_path: Path to the skill directory
+
+    Returns:
+        List of paths to resource files (excluding SKILL.md).
+    """
+    if not skill_path.exists():
+        logger.debug(f"Skill path does not exist: {skill_path}")
+        return []
+
+    if not skill_path.is_dir():
+        logger.warning(f"Skill path is not a directory: {skill_path}")
+        return []
+
+    resources: List[Path] = []
+    try:
+        for item in skill_path.iterdir():
+            if item.is_file() and item.name != "SKILL.md":
+                resources.append(item)
+    except Exception as e:
+        logger.error(f"Failed to list resources in {skill_path}: {e}")
+        return []
+
+    return sorted(resources)  # Sort for consistent ordering

code_puppy_core_plugins/agent_skills/prompt_builder.py

@@ -0,0 +1,49 @@
+"""Build the `available skills` section for system-prompt injection.
+
+Keep the verbosity floor-low. Each skill becomes a single line of the form
+``- <name>: <description>``. That is essentially the frontmatter `name` and
+`description` fields, flattened. No XML, no ceremony, no escaping circus.
+"""
+
+from typing import TYPE_CHECKING, List
+
+if TYPE_CHECKING:
+    from .metadata import SkillMetadata
+
+
+def _one_line(text: str) -> str:
+    """Collapse whitespace so each skill stays on a single line."""
+    return " ".join(text.split())
+
+
+def build_available_skills_block(skills: List["SkillMetadata"]) -> str:
+    """Render a minimal markdown list of available skills.
+
+    Format::
+
+        ## Available Skills
+        - skill-one: short description
+        - skill-two: short description
+
+    Returns an empty string when there are no skills — callers can simply
+    concatenate without worrying about stray headings.
+    """
+    if not skills:
+        return ""
+
+    lines = ["## Available Skills"]
+    for skill in skills:
+        desc = _one_line(skill.description) if skill.description else ""
+        lines.append(f"- {skill.name}: {desc}" if desc else f"- {skill.name}")
+    return "\n".join(lines)
+
+
+def build_skills_guidance() -> str:
+    """Tell the model when and how to use a skill."""
+    return (
+        "When the user's question or task relates to a skill listed above, "
+        "activate it with `activate_skill(name)` **before** answering so its "
+        "full instructions are loaded into context. Use "
+        "`list_or_search_skills(query)` to discover skills by keyword — it "
+        "matches any individual word in the query."
+    )

code_puppy_core_plugins/agent_skills/provider.py

@@ -0,0 +1,52 @@
+"""Core-facing provider backed by the agent_skills plugin's existing helpers."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, List, Optional, Set
+
+from .config import get_disabled_skills, get_skills_enabled
+from .enabled_skills import iter_enabled_skills, list_enabled_skill_metadata
+from .metadata import get_skill_resources, load_full_skill_content
+from .skill_catalog import catalog
+
+
+class AgentSkillsProvider:
+    """Adapt agent_skills internals to the neutral core provider contract."""
+
+    def is_enabled(self) -> bool:
+        return get_skills_enabled()
+
+    def get_disabled_skill_names(self) -> Set[str]:
+        return get_disabled_skills()
+
+    def list_enabled_skills(self) -> List[dict[str, Any]]:
+        return [
+            {
+                "name": metadata.name,
+                "description": metadata.description,
+                "path": str(metadata.path),
+                "tags": metadata.tags,
+                "version": metadata.version,
+                "author": metadata.author,
+            }
+            for metadata in list_enabled_skill_metadata()
+        ]
+
+    def find_enabled_skill_path(self, skill_name: str) -> Optional[Path]:
+        return next(
+            (info.path for info in iter_enabled_skills() if info.name == skill_name),
+            None,
+        )
+
+    def load_skill_content(self, skill_path: Path) -> Optional[str]:
+        return load_full_skill_content(skill_path)
+
+    def get_skill_resources(self, skill_path: Path) -> List[Path]:
+        return get_skill_resources(skill_path)
+
+    def get_catalog_skill_ids(self) -> List[str]:
+        return [entry.id for entry in catalog.get_all()]
+
+
+skill_provider = AgentSkillsProvider()

code_puppy_core_plugins/agent_skills/register_callbacks.py

@@ -0,0 +1,309 @@
+"""Agent Skills plugin - registers callbacks for skill integration.
+
+This plugin:
+1. Injects available skills into system prompts
+2. Registers skill-related tools
+3. Exposes a skills provider via the ``register_skills`` hook
+4. Provides /skills slash command (and alias /skill)
+"""
+
+import logging
+from typing import Any, Dict, List, Optional, Tuple
+
+from code_puppy.callbacks import register_callback
+
+logger = logging.getLogger(__name__)
+
+
+def _get_skills_prompt_section() -> Optional[str]:
+    """Build the skills section to inject into system prompts.
+
+    Returns None if skills are disabled or no enabled skills exist.
+    Disabled skills never have their frontmatter loaded — see
+    :mod:`code_puppy_core_plugins.agent_skills.enabled_skills`.
+
+    When ``frontmatter_in_system_prompt`` is ``False``, the per-skill list is
+    omitted but the short guidance line is still emitted so the model knows
+    the ``activate_skill`` / ``list_or_search_skills`` mechanism exists.
+    """
+    from .config import get_frontmatter_in_system_prompt
+    from .enabled_skills import list_enabled_skill_metadata
+    from .prompt_builder import build_available_skills_block, build_skills_guidance
+
+    skills_metadata = list_enabled_skill_metadata()
+    if not skills_metadata:
+        logger.debug("No enabled skills with metadata found, skipping prompt injection")
+        return None
+
+    guidance = build_skills_guidance()
+
+    if not get_frontmatter_in_system_prompt():
+        logger.debug(
+            "Frontmatter injection disabled; emitting guidance line only "
+            f"({len(skills_metadata)} skills hidden from system prompt)"
+        )
+        return guidance
+
+    skills_block = build_available_skills_block(skills_metadata)
+    logger.debug(f"Injecting skills section with {len(skills_metadata)} skills")
+    return f"{skills_block}\n\n{guidance}"
+
+
+def _inject_skills_into_prompt(
+    model_name: str, default_system_prompt: str, user_prompt: str
+) -> Optional[Dict[str, Any]]:
+    """Callback to inject skills into system prompt.
+
+    This is registered with the 'get_model_system_prompt' callback phase.
+    """
+    skills_section = _get_skills_prompt_section()
+
+    if not skills_section:
+        return None  # No skills, don't modify prompt
+
+    # Append skills section to system prompt
+    enhanced_prompt = f"{default_system_prompt}\n\n{skills_section}"
+
+    return {
+        "instructions": enhanced_prompt,
+        "user_prompt": user_prompt,
+        "handled": False,  # Let other handlers also process
+    }
+
+
+def _register_skills_tools() -> List[Dict[str, Any]]:
+    """Callback to register skills tools.
+
+    This is registered with the 'register_tools' callback phase.
+    Returns tool definitions for the tool registry.
+    """
+    from code_puppy.tools.skills_tools import (
+        register_activate_skill,
+        register_list_or_search_skills,
+    )
+
+    return [
+        {"name": "activate_skill", "register_func": register_activate_skill},
+        {
+            "name": "list_or_search_skills",
+            "register_func": register_list_or_search_skills,
+        },
+    ]
+
+
+def _register_skills() -> List[Dict[str, Any]]:
+    """Expose the plugin through the neutral ``register_skills`` provider seam."""
+    from .provider import skill_provider
+
+    return [{"provider": skill_provider}]
+
+
+# ---------------------------------------------------------------------------
+# Slash command: /skills (and alias /skill)
+# ---------------------------------------------------------------------------
+
+_COMMAND_NAME = "skills"
+_ALIASES = ("skill",)
+
+
+def _skills_command_help() -> List[Tuple[str, str]]:
+    """Advertise /skills (+ every individual skill) in the /help menu."""
+    from .skill_commands import skill_command_help
+
+    entries: List[Tuple[str, str]] = [
+        ("skills", "Manage agent skills – browse, enable, disable, install"),
+        ("skill", "Alias for /skills"),
+    ]
+    # Append per-skill commands so they show up in /help & tab-completion.
+    entries.extend(skill_command_help())
+    return entries
+
+
+def _handle_skills_command(command: str, name: str) -> Optional[Any]:
+    """Handle /skills and /skill slash commands.
+
+    Sub-commands:
+        /skills          – Launch interactive TUI menu
+        /skills list     – Quick text list of all skills
+        /skills install  – Browse & install from remote catalog
+        /skills enable   – Enable skills integration globally
+        /skills disable  – Disable skills integration globally
+        /skills toggle   – Toggle skills integration globally
+        /skills refresh  – Force skill re-discovery and refresh local cache
+        /skills help     – Show skills command help
+    """
+    if name not in (_COMMAND_NAME, *_ALIASES):
+        # Not the /skills meta-command — maybe it's an individual skill?
+        from .skill_commands import handle_skill_command
+
+        return handle_skill_command(command, name)
+
+    from code_puppy.messaging import emit_error, emit_info, emit_success, emit_warning
+    from code_puppy_core_plugins.agent_skills.config import (
+        get_disabled_skills,
+        get_frontmatter_in_system_prompt,
+        get_skills_enabled,
+        set_frontmatter_in_system_prompt,
+        set_skills_enabled,
+    )
+    from code_puppy_core_plugins.agent_skills.discovery import (
+        discover_skills,
+        refresh_skill_cache,
+    )
+    from code_puppy_core_plugins.agent_skills.metadata import parse_skill_metadata
+    from code_puppy_core_plugins.agent_skills.skills_menu import show_skills_menu
+
+    tokens = command.split()
+
+    if len(tokens) > 1:
+        subcommand = tokens[1].lower()
+
+        if subcommand == "list":
+            disabled_skills = get_disabled_skills()
+            skills = discover_skills()
+            enabled = get_skills_enabled()
+
+            if not skills:
+                emit_info("No skills found.")
+                emit_info("Create skills in:")
+                emit_info("  - ~/.code_puppy/skills/")
+                emit_info("  - ./skills/")
+                return True
+
+            emit_info(
+                f"\U0001f6e0\ufe0f Skills (integration: {'enabled' if enabled else 'disabled'})"
+            )
+            emit_info(f"Found {len(skills)} skill(s):\n")
+
+            for skill in skills:
+                metadata = parse_skill_metadata(skill.path)
+                if metadata:
+                    status = (
+                        "\U0001f534 disabled"
+                        if metadata.name in disabled_skills
+                        else "\U0001f7e2 enabled"
+                    )
+                    version_str = f" v{metadata.version}" if metadata.version else ""
+                    author_str = f" by {metadata.author}" if metadata.author else ""
+                    emit_info(f"  {status} {metadata.name}{version_str}{author_str}")
+                    emit_info(f"      {metadata.description}")
+                    if metadata.tags:
+                        emit_info(f"      tags: {', '.join(metadata.tags)}")
+                else:
+                    status = (
+                        "\U0001f534 disabled"
+                        if skill.name in disabled_skills
+                        else "\U0001f7e2 enabled"
+                    )
+                    emit_info(f"  {status} {skill.name}")
+                    emit_info("      (no SKILL.md metadata found)")
+                emit_info("")
+            return True
+
+        elif subcommand == "install":
+            from code_puppy_core_plugins.agent_skills.skills_install_menu import (
+                run_skills_install_menu,
+            )
+
+            run_skills_install_menu()
+            return True
+
+        elif subcommand == "enable":
+            set_skills_enabled(True)
+            emit_success("\u2705 Skills integration enabled globally")
+            return True
+
+        elif subcommand == "disable":
+            set_skills_enabled(False)
+            emit_warning("\U0001f534 Skills integration disabled globally")
+            return True
+
+        elif subcommand == "toggle":
+            new_state = not get_skills_enabled()
+            set_skills_enabled(new_state)
+            if new_state:
+                emit_success("✅ Skills integration enabled globally")
+            else:
+                emit_warning("🔴 Skills integration disabled globally")
+            return True
+
+        elif subcommand == "frontmatter":
+            # /skills frontmatter [on|off|toggle]   (no arg = show state)
+            arg = tokens[2].lower() if len(tokens) > 2 else None
+            current = get_frontmatter_in_system_prompt()
+
+            if arg in ("on", "enable", "true"):
+                new_state = True
+            elif arg in ("off", "disable", "false"):
+                new_state = False
+            elif arg == "toggle":
+                new_state = not current
+            elif arg is None:
+                emit_info(
+                    f"Skill frontmatter in system prompt: "
+                    f"{'🟢 on' if current else '🔴 off'}"
+                )
+                emit_info("Usage: /skills frontmatter [on|off|toggle]")
+                return True
+            else:
+                emit_error(f"Unknown frontmatter arg: {arg}")
+                emit_info("Usage: /skills frontmatter [on|off|toggle]")
+                return True
+
+            set_frontmatter_in_system_prompt(new_state)
+            if new_state:
+                emit_success(
+                    "✅ Skill frontmatter will be injected into system prompts"
+                )
+            else:
+                emit_warning(
+                    "🔴 Skill frontmatter hidden from system prompts "
+                    "(model can still call activate_skill / list_or_search_skills)"
+                )
+            return True
+
+        elif subcommand == "refresh":
+            refreshed = refresh_skill_cache()
+            valid_skills = [skill for skill in refreshed if skill.has_skill_md]
+            emit_success(
+                f"🔄 Refreshed skills cache: {len(refreshed)} discovered "
+                f"({len(valid_skills)} with SKILL.md)"
+            )
+            return True
+
+        elif subcommand == "help":
+            emit_info("Available /skills subcommands:")
+            emit_info("  /skills list     - List all installed skills")
+            emit_info("  /skills install  - Browse & install from catalog")
+            emit_info("  /skills enable   - Enable skills integration globally")
+            emit_info("  /skills disable  - Disable skills integration globally")
+            emit_info("  /skills toggle   - Toggle skills integration globally")
+            emit_info(
+                "  /skills frontmatter [on|off|toggle] - Toggle skill list injection into system prompt"
+            )
+            emit_info("  /skills refresh  - Refresh skill cache")
+            emit_info("  /skills          - Open interactive skills menu")
+            return True
+
+        else:
+            emit_error(f"Unknown subcommand: {subcommand}")
+            emit_info(
+                "Usage: /skills [list|install|enable|disable|toggle|frontmatter|refresh|help]"
+            )
+            return True
+
+    # No subcommand – launch TUI menu
+    show_skills_menu()
+    return True
+
+
+# ---------------------------------------------------------------------------
+# Register all callbacks
+# ---------------------------------------------------------------------------
+register_callback("get_model_system_prompt", _inject_skills_into_prompt)
+register_callback("register_tools", _register_skills_tools)
+register_callback("register_skills", _register_skills)
+register_callback("custom_command_help", _skills_command_help)
+register_callback("custom_command", _handle_skills_command)
+
+logger.info("Agent Skills plugin loaded")