Beyond Static Prompts: How to Build Self-Improving AI Agents with Closed-Loop Skill Playbooks

[ Trigger (Invocation Contract) ]
               │
               ▼
[ Execution Logic (Modular Workflow) ] ◄───┐ (Self-Correction / Updates)
               │                           │
               ▼                           │
[ Memory Integration (Feedback Loop) ] ────┘

   User Input: "/gif-search cute cats"
               │
               ▼
┌─────────────────────────────────────────────────────────┐
│ 1. TRIGGER                                              │
│ - scan_skill_commands() matches "/gif-search"           │
│ - Loads "SKILL.md" and packages payload                 │
└──────────────┬──────────────────────────────────────────┘
               │
               ▼
┌─────────────────────────────────────────────────────────┐
│ 2. EXECUTION                                            │
│ - Step A: Run web_search("cute cats gif")               │
│ - Step B: Extract direct image URLs                     │
│ - Step C: Return formatted markdown link to user        │
└──────────────┬──────────────────────────────────────────┘
               │
               ▼
┌─────────────────────────────────────────────────────────┐
│ 3. MEMORY INTEGRATION (Background Review)               │
│ - Critic detects Step B failed (regex extraction error)  │
│ - Generates a patch to fix the regex pattern            │
│ - Writes update back to "SKILL.md"                      │
└─────────────────────────────────────────────────────────┘

---
name: gif-search
description: Search the web for animated GIFs matching a query and return markdown image links.
version: 1.1.0
author: hermes-system
tags: media, search, web
category: utility
platforms: macos, linux, windows
---

# Playbook: GIF Search

## Trigger Contract
Activated explicitly via `/gif-search <query>` or contextually when the user requests an animated image or reaction GIF.

## Execution Steps
1. Call `web_search` tool with the query appended with "filetype:gif site:giphy.com OR site:tenor.com".
2. Parse the search results. Use the following regex pattern to extract raw media URLs: `https://media\.giphy\.com/media/[a-zA-Z0-9]+/giphy\.gif`.
3. If the primary regex fails, fall back to extracting any URL ending with `.gif` from the page source.
4. Format the output as a standard Markdown image link: `![Result](url)`.

"""
Basic Skill Library Implementation

This module provides a clean, standalone implementation for discovering,
indexing, and invoking skills from a local directory. It demonstrates the
core patterns used by Hermes Agent's skill management system.

Key Features:
- Scans a directory for SKILL.md files
- Parses YAML frontmatter for metadata (name, description, tags)
- Creates a mapping of skill names to their file paths and metadata
- Provides a simple invocation mechanism that returns the skill's content
- Includes a reload mechanism to pick up new or changed skills
"""

import json
import logging
import os
import re
import uuid
from datetime import datetime
from pathlib import Path
from typing import Any, Dict, List, Optional, Set, Tuple

# Configure logging for this module
logging.basicConfig(level=logging.INFO, format="%(asctime)s - %(levelname)s - %(message)s")
logger = logging.getLogger(__name__)

# ─── Constants ───────────────────────────────────────────────────────────
# The name of the skill definition file within each skill directory
SKILL_MD_FILENAME = "SKILL.md"

# Regular expression to match YAML frontmatter blocks
# Frontmatter is delimited by '---' at the start and end
FRONTMATTER_PATTERN = re.compile(r"^---\s*\n(.*?)\n---\s*\n", re.DOTALL)

# Patterns for sanitizing skill names into clean, hyphen-separated slugs
# This ensures compatibility with slash command naming conventions
SKILL_INVALID_CHARS = re.compile(r"[^a-z0-9-]")
SKILL_MULTI_HYPHEN = re.compile(r"-{2,}")

# ─── Data Structures ─────────────────────────────────────────────────────


class SkillMetadata:
    """
    Represents the parsed metadata from a skill's SKILL.md frontmatter.

    This class encapsulates all the information needed to identify, describe,
    and invoke a skill. It follows the Principle of Least Astonishment (POLA)
    by providing clear, predictable attribute names and behavior.
    """

    def __init__(
        self,
        name: str,
        description: str = "",
        version: str = "1.0.0",
        author: str = "",
        tags: Optional[List[str]] = None,
        category: str = "general",
        platforms: Optional[List[str]] = None,
    ):
        """
        Initialize a SkillMetadata instance.

        Args:
            name: The canonical name of the skill (e.g., "gif-search")
            description: A human-readable description of what the skill does
            version: Semantic version string (default: "1.0.0")
            author: The creator of the skill
            tags: A list of searchable tags for the skill
            category: The functional category of the skill (default: "general")
            platforms: A list of OS platforms this skill supports (e.g., ["macos", "linux"])
        """
        self.name = name
        self.description = description
        self.version = version
        self.author = author
        self.tags = tags or []
        self.category = category
        self.platforms = platforms or []

    def to_dict(self) -> Dict[str, Any]:
        """Convert the metadata to a dictionary for serialization or display."""
        return {
            "name": self.name,
            "description": self.description,
            "version": self.version,
            "author": self.author,
            "tags": self.tags,
            "category": self.category,
            "platforms": self.platforms,
        }

    @classmethod
    def from_frontmatter(cls, frontmatter: Dict[str, Any]) -> "SkillMetadata":
        """
        Create a SkillMetadata instance from a parsed YAML frontmatter dict.

        This class method handles the extraction of known fields and provides
        sensible defaults for any missing values.

        Args:
            frontmatter: A dictionary of key-value pairs from the SKILL.md frontmatter

        Returns:
            A new SkillMetadata instance populated with the frontmatter data
        """
        # Extract the name, falling back to a placeholder if missing
        name = frontmatter.get("name", "").strip()
        if not name:
            logger.warning("Skill frontmatter missing 'name' field; using placeholder.")
            name = "unnamed-skill"

        # Extract description, version, author, tags, category, and platforms
        description = frontmatter.get("description", "").strip()
        version = str(frontmatter.get("version", "1.0.0")).strip()
        author = frontmatter.get("author", "").strip()
        tags = frontmatter.get("tags", [])
        if isinstance(tags, str):
            tags = [tag.strip() for tag in tags.split(",")]
        category = frontmatter.get("category", "general").strip().lower()
        platforms = frontmatter.get("platforms", [])
        if isinstance(platforms, str):
            platforms = [p.strip() for p in platforms.split(",")]

        return cls(
            name=name,
            description=description,
            version=version,
            author=author,
            tags=tags,
            category=category,
            platforms=platforms,
        )


class SkillInfo:
    """
    Represents a discovered skill with its metadata, file path, and content.

    This is the primary data structure returned by the skill scanner. It
    bundles all the information needed to load and use a skill.
    """

    def __init__(
        self,
        metadata: SkillMetadata,
        skill_md_path: Path,
        skill_dir: Path,
        content: str = "",
    ):
        """
        Initialize a SkillInfo instance.

        Args:
            metadata: The parsed metadata from the SKILL.md frontmatter
            skill_md_path: The absolute path to the SKILL.md file
            skill_dir: The absolute path to the skill's directory
            content: The full text content of the SKILL.md file (optional)
        """
        self.metadata = metadata
        self.skill_md_path = skill_md_path
        self.skill_dir = skill_dir
        self.content = content

    def to_dict(self) -> Dict[str, Any]:
        """Convert the skill info to a dictionary for serialization."""
        return {
            "name": self.metadata.name,
            "description": self.metadata.description,
            "version": self.metadata.version,
            "author": self.metadata.author,
            "tags": self.metadata.tags,
            "category": self.metadata.category,
            "platforms": self.metadata.platforms,
            "skill_md_path": str(self.skill_md_path),
            "skill_dir": str(self.skill_dir),
            "content_length": len(self.content),
        }


# ─── Frontmatter Parser ─────────────────────────────────────────────────


def parse_frontmatter(content: str) -> Tuple[Dict[str, Any], str]:
    """
    Parse YAML frontmatter from a skill file's content.

    This function extracts the YAML frontmatter block (delimited by '---')
    and returns it as a dictionary, along with the remaining body content.
    It uses a simple regex-based approach for parsing, which is sufficient
    for the basic metadata fields used in SKILL.md files.

    Args:
        content: The full text content of a SKILL.md file

    Returns:
        A tuple of (frontmatter_dict, body_content_string)
    """
    # Attempt to match the frontmatter pattern at the start of the content
    match = FRONTMATTER_PATTERN.match(content)
    if not match:
        # No frontmatter found; return an empty dict and the full content as body
        return {}, content.strip()

    # Extract the raw YAML string and the body content
    raw_yaml = match.group(1)
    body = content[match.end():].strip()

    # Parse the raw YAML string into a dictionary
    # We use a simple key-value parser for this example
    frontmatter = {}
    for line in raw_yaml.split("\n"):
        line = line.strip()
        if not line or line.startswith("#"):
            continue
        if ":" in line:
            key, _, value = line.partition(":")
            key = key.strip()
            value = value.strip().strip('"').strip("'")
            frontmatter[key] = value

    return frontmatter, body


def sanitize_skill_name(name: str) -> str:
    """
    Sanitize a skill name into a clean, hyphen-separated slug.

    This ensures compatibility with slash command naming conventions
    (e.g., normalizing spaces and underscores to hyphens).

    Args:
        name: The raw skill name to sanitize

    Returns:
        A sanitized, hyphen-separated slug
    """
    # Convert to lowercase and replace spaces/underscores with hyphens
    slug = name.lower().replace(" ", "-").replace("_", "-")

    # Remove any characters that are not alphanumeric or hyphens
    slug = SKILL_INVALID_CHARS.sub("", slug)

    # Collapse multiple consecutive hyphens into a single hyphen
    slug = SKILL_MULTI_HYPHEN.sub("-", slug)

    # Strip leading and trailing hyphens
    slug = slug.strip("-")

    return slug


# ─── Skill Scanner ──────────────────────────────────────────────────────


class SkillScanner:
    """
    Scans a directory for SKILL.md files and indexes them as skills.

    This class is the core of the skill discovery system. It walks a given
    directory tree, finds all SKILL.md files, parses their frontmatter, and
    creates a mapping of skill names to their metadata and file paths.

    The scanner is designed to be efficient and robust, handling missing
    files, malformed frontmatter, and duplicate skill names gracefully.
    """

    def __init__(self, skills_dir: Path):
        """
        Initialize the SkillScanner with a root directory to scan.

        Args:
            skills_dir: The root directory to scan for skill files
        """
        self.skills_dir = skills_dir
        self._skills: Dict[str, SkillInfo] = {}
        self._last_scan_time: Optional[datetime] = None

    def scan(self) -> Dict[str, SkillInfo]:
        """
        Perform a full scan of the skills directory.

        This method walks the directory tree, finds all SKILL.md files,
        parses their frontmatter, and builds an in-memory index of skills.
        It returns a dictionary mapping sanitized skill names to SkillInfo objects.

        Returns:
            A dictionary of {sanitized_skill_name: SkillInfo}
        """
        # Reset the skills index before scanning
        self._skills = {}
        seen_names: Set[str] = set()

        # Ensure the skills directory exists before scanning
        if not self.skills_dir.exists():
            logger.warning(f"Skills directory does not exist: {self.skills_dir}")
            return self._skills

        # Walk the directory tree, looking for SKILL.md files
        for skill_md_path in self.skills_dir.rglob(SKILL_MD_FILENAME):
            # Skip hidden directories (e.g., .git, .github)
            if any(part.startswith(".") for part in skill_md_path.parts):
                continue

            try:
                # Read the SKILL.md file content
                content = skill_md_path.read_text(encoding="utf-8")

                # Parse the frontmatter and body
                frontmatter, body = parse_frontmatter(content)

                # Create a SkillMetadata object from the frontmatter
                metadata = SkillMetadata.from_frontmatter(frontmatter)

                # Sanitize the skill name for use as a slash command
                sanitized_name = sanitize_skill_name(metadata.name)

                # Skip duplicate skill names (first one wins)
                if sanitized_name in seen_names:
                    logger.warning(
                        f"Duplicate skill name '{sanitized_name}' found at "
                        f"{skill_md_path}; skipping."
                    )
                    continue

                # Mark this name as seen
                seen_names.add(sanitized_name)

                # Create a SkillInfo object and add it to the index
                skill_info = SkillInfo(
                    metadata=metadata,
                    skill_md_path=skill_md_path,
                    skill_dir=skill_md_path.parent,
                    content=content,
                )
                self._skills[sanitized_name] = skill_info

                logger.info(
                    f"Discovered skill: {sanitized_name} "
                    f"({metadata.description})"
                )

            except Exception as e:
                # Log the error but continue scanning other skills
                logger.error(
                    f"Failed to parse skill at {skill_md_path}: {e}"
                )

        # Record the scan time
        self._last_scan_time = datetime.now()

        logger.info(
            f"Scan complete. Found {len(self._skills)} skill(s) "
            f"in {self.skills_dir}."
        )
        return self._skills

    def get_skill(self, name: str) -> Optional[SkillInfo]:
        """Retrieve a skill by its sanitized name."""
        return self._skills.get(sanitize_skill_name(name))


# ─── Demonstration ───────────────────────────────────────────────────────

if __name__ == "__main__":
    import tempfile

    # Create a temporary directory structure to simulate a skill library
    with tempfile.TemporaryDirectory() as temp_dir:
        temp_path = Path(temp_dir)

        # Define a mock skill directory and SKILL.md file
        search_skill_dir = temp_path / "gif-search"
        search_skill_dir.mkdir(parents=True, exist_ok=True)

        mock_skill_content = """---
name: Gif Search
description: Search and retrieve animated GIFs
version: 1.0.2
author: Developer-Alpha
tags: media, search
category: utility
platforms: macos, linux
---
# Playbook: Gif Search
This playbook defines how to search and retrieve animated GIFs...
"""

        skill_file = search_skill_dir / SKILL_MD_FILENAME
        skill_file.write_text(mock_skill_content, encoding="utf-8")

        # Initialize and run the scanner
        scanner = SkillScanner(temp_path)
        discovered_skills = scanner.scan()

        # Retrieve and inspect our parsed skill
        gif_skill = scanner.get_skill("gif-search")
        if gif_skill:
            print("\n--- Parsed Skill Metadata ---")
            print(json.dumps(gif_skill.to_dict(), indent=2))