"""Skill definitions for registering instructional content with Pillar.

Skills are structured markdown instructions that AI agents can load
and follow. They are exposed as MCP prompts and resources.
"""
from __future__ import annotations

from dataclasses import dataclass


@dataclass(frozen=True)
class SkillDefinition:
    """A registered skill."""

    name: str
    """Unique skill name (e.g. 'billing-setup')."""

    description: str
    """When/why to use this skill — used for semantic search matching."""

    content: str
    """Full skill content (markdown)."""


def define_skill(
    *,
    name: str,
    description: str,
    content: str,
) -> SkillDefinition:
    """Define a skill for registration with Pillar.

    Example::

        setup_skill = define_skill(
            name="setup-guide",
            description="How to set up billing in your app",
            content="# Setup Guide\\n\\n1. Install the SDK...",
        )
    """
    if not name:
        raise ValueError("Skill requires a `name`.")
    if not description:
        raise ValueError("Skill requires a `description`.")
    if not content:
        raise ValueError("Skill requires `content`.")
    return SkillDefinition(name=name, description=description, content=content)
