"""
Skill manifest spec models.

Defines the core specification for skill packs.
"""

from pydantic import BaseModel, Field

from typing import Optional


class SkillEntry(BaseModel):
    """Individual skill definition within a skill pack."""

    name: str = Field(..., description="Skill identifier")
    description: str = Field(..., description="When to use this skill")


class CommandEntry(BaseModel):
    """Slash command mapping to a skill."""

    name: str = Field(..., description="Command name (used as /name)")
    description: Optional[str] = Field(None, description="Command description shown in help")
    argument_hint: Optional[str] = Field(
        None, description="Hint for command arguments (e.g., '[@doc.md | \"description\"]')"
    )
    skill: str = Field(..., description="Reference to skill name this command invokes")


class SkillSpec(BaseModel):
    """
    Skill pack specification block.

    Defines the skills, commands, and platform compatibility.
    """

    skills: list[SkillEntry] = Field(
        ..., description="Skills included in this pack"
    )
    commands: list[CommandEntry] = Field(
        default_factory=list, description="Slash command mappings"
    )
    platforms: list[str] = Field(
        default_factory=list,
        description="Compatible platforms (e.g., claude-code, opencode, openclaw)",
    )
