hanuscode 1.0.0__py3-none-any.whl

hanus/skill_manager.py

@@ -0,0 +1,702 @@
+# hanus/skill_manager.py — Sistema de Skills
+"""
+Gestión de skills: comandos reutilizables que pueden instalarse desde URLs.
+
+Soporta múltiples formatos para compatibilidad:
+1. Python (.py) - Skills ejecutables con función run()
+2. Markdown (.md) - Plantillas de instrucciones para el agente
+3. Claude Code (SKILL.md) - Formato de Claude Code con directorios
+4. Cursor (.mdc) - Formato de Cursor con scoping por globs
+
+Formatos de argumentos soportados:
+- HanusCode: {{args}}, {{arg1}}, {{arg2}}
+- Claude Code: $ARGUMENTS, $ARGUMENTS[0], $name (de frontmatter)
+- Genérico: $0, $1, $2
+
+Contexto dinámico:
+- Claude Code: !`command` ejecuta comando y reemplaza
+"""
+from __future__ import annotations
+import importlib.util
+import subprocess
+import urllib.request
+import urllib.error
+import json
+import re
+import yaml
+import shlex
+import traceback
+from pathlib import Path
+from typing import Dict, List, Optional, Any
+from dataclasses import dataclass, field
+from enum import Enum
+
+
+class SkillType(Enum):
+    PYTHON = "python"
+    MARKDOWN = "markdown"
+    CLAUDE_CODE = "claude_code"  # SKILL.md format
+    CURSOR = "cursor"  # .mdc format
+
+
+# Directorios de skills
+SKILLS_DIR_BUILTIN = Path(__file__).parent / "skills"
+SKILLS_DIR_USER = Path.home() / ".hanus" / "skills"
+
+
+@dataclass
+class Skill:
+    """Representa un skill cargado."""
+    name: str
+    description: str
+    usage: str
+    version: str
+    author: str
+    path: Path
+    skill_type: SkillType = SkillType.PYTHON
+    module: Any = None
+    content: str = ""  # Para skills markdown
+    is_builtin: bool = False
+    # Claude Code specific
+    arguments: List[str] = field(default_factory=list)  # Named arguments
+    allowed_tools: List[str] = field(default_factory=list)
+    disable_auto_invoke: bool = False
+    # Cursor specific
+    globs: List[str] = field(default_factory=list)
+    always_apply: bool = False
+
+    def run(self, args: str = "") -> str:
+        """Ejecuta el skill."""
+        if self.skill_type in (SkillType.MARKDOWN, SkillType.CLAUDE_CODE, SkillType.CURSOR):
+            return self._run_markdown(args)
+        else:
+            return self._run_python(args)
+
+    def _run_python(self, args: str = "") -> str:
+        """Ejecuta un skill Python."""
+        try:
+            if self.module is None:
+                return f"[Skill {self.name}] Módulo no cargado"
+            fn = getattr(self.module, "run", None)
+            if not callable(fn):
+                return f"[Skill {self.name}] No tiene función run()"
+            return str(fn(args))
+        except Exception as e:
+            return f"[Skill {self.name}] Error: {e}\n{traceback.format_exc()}"
+
+    def _run_markdown(self, args: str = "") -> str:
+        """Ejecuta un skill Markdown (inyecta instrucciones)."""
+        content = self.content
+
+        # Procesar contexto dinámico (!command)
+        content = self._process_dynamic_context(content)
+
+        # Reemplazar argumentos en múltiples formatos
+        content = self._replace_arguments(content, args)
+
+        # Formatear como instrucción para el agente
+        output = [
+            f"[SKILL: {self.name}]",
+            "",
+            content,
+        ]
+
+        if args:
+            output.insert(1, f"**Argumentos:** {args}")
+
+        return "\n".join(output)
+
+    def _process_dynamic_context(self, content: str) -> str:
+        """Procesa comandos dinámicos estilo Claude Code (!`command`)."""
+        # Buscar patrón !`command` o !`command args`
+        pattern = r'!`([^`]+)`'
+
+        def run_command(match):
+            cmd = match.group(1).strip()
+            try:
+                result = subprocess.run(
+                    cmd,
+                    shell=True,
+                    capture_output=True,
+                    text=True,
+                    timeout=30
+                )
+                output = result.stdout.strip()
+                if result.returncode != 0 and result.stderr:
+                    output += f"\n[stderr: {result.stderr.strip()}]"
+                return output
+            except subprocess.TimeoutExpired:
+                return "[timeout]"
+            except Exception as e:
+                return f"[error: {e}]"
+
+        return re.sub(pattern, run_command, content)
+
+    def _replace_arguments(self, content: str, args: str) -> str:
+        """Reemplaza argumentos en múltiples formatos."""
+        args_parts = args.split()
+
+        # IMPORTANTE: Reemplazar $ARGUMENTS[n] ANTES de $ARGUMENTS
+        # para evitar que el reemplazo de $ARGUMENTS afecte los índices
+
+        # $ARGUMENTS[0], $ARGUMENTS[1], etc.
+        for i in range(len(args_parts)):
+            content = content.replace(f"$ARGUMENTS[{i}]", args_parts[i])
+            content = content.replace(f"${i}", args_parts[i])
+
+        # Formato Claude Code: $ARGUMENTS (todo el string)
+        content = content.replace("$ARGUMENTS", args)
+
+        # Named arguments from frontmatter (Claude Code style)
+        for i, arg_name in enumerate(self.arguments):
+            if i < len(args_parts):
+                content = content.replace(f"${arg_name}", args_parts[i])
+
+        # Formato HanusCode: {{args}}, {{arg1}}, {{arg2}}
+        content = content.replace("{{args}}", args)
+        for i, arg in enumerate(args_parts, 1):
+            content = content.replace(f"{{{{arg{i}}}}}", arg)
+
+        return content
+
+    def get_doc(self) -> str:
+        """Retorna documentación del skill."""
+        type_icons = {
+            SkillType.PYTHON: "🐍",
+            SkillType.MARKDOWN: "📝",
+            SkillType.CLAUDE_CODE: "🤖",
+            SkillType.CURSOR: "⚡",
+        }
+        icon = type_icons.get(self.skill_type, "📄")
+
+        lines = [
+            f"### {icon} Skill: /{self.name}",
+            f"**Descripción:** {self.description}",
+            f"**Uso:** `/{self.name} {self.usage}`",
+            f"**Versión:** {self.version}",
+            f"**Autor:** {self.author}",
+            f"**Tipo:** {self.skill_type.value}",
+            f"**Origen:** {'Builtin' if self.is_builtin else 'Instalado'}",
+        ]
+
+        if self.arguments:
+            lines.append(f"**Argumentos:** {', '.join(self.arguments)}")
+
+        if self.globs:
+            lines.append(f"**Aplica a:** {', '.join(self.globs)}")
+
+        # Para skills Python, añadir docstrings
+        if self.skill_type == SkillType.PYTHON and self.module:
+            if self.module.__doc__:
+                lines.append(f"\n{self.module.__doc__}")
+            agent_doc = getattr(self.module, "AGENT_DOC", "")
+            if agent_doc:
+                lines.append(f"\n{agent_doc}")
+
+        # Para skills Markdown, mostrar preview
+        elif self.content:
+            preview = self.content[:300] + "..." if len(self.content) > 300 else self.content
+            lines.append(f"\n**Preview:**")
+            lines.append(f"```markdown")
+            lines.append(preview)
+            lines.append(f"```")
+
+        return "\n".join(lines)
+
+    def get_prompt(self, args: str = "") -> str:
+        """Obtiene el prompt/instrucción para el agente."""
+        if self.skill_type != SkillType.PYTHON:
+            return self._run_markdown(args)
+        else:
+            return self.run(args)
+
+
+class SkillManager:
+    """Gestiona el ciclo de vida de los skills."""
+
+    def __init__(self):
+        self.skills: Dict[str, Skill] = {}
+        self._load_all()
+
+    def _load_all(self):
+        """Carga todos los skills de todos los directorios."""
+        self.skills.clear()
+
+        # Cargar skills builtin
+        if SKILLS_DIR_BUILTIN.exists():
+            self._load_from_directory(SKILLS_DIR_BUILTIN, is_builtin=True)
+
+        # Cargar skills del usuario
+        if SKILLS_DIR_USER.exists():
+            self._load_from_directory(SKILLS_DIR_USER, is_builtin=False)
+
+    def _load_from_directory(self, directory: Path, is_builtin: bool = False):
+        """Carga skills de un directorio con múltiples formatos."""
+        # Python skills (.py)
+        for py in sorted(directory.glob("*.py")):
+            if not py.name.startswith("_"):
+                self._load_python(py, is_builtin=is_builtin)
+
+        # Markdown skills (.md)
+        for md in sorted(directory.glob("*.md")):
+            if not md.name.startswith("_"):
+                self._load_markdown(md, is_builtin=is_builtin)
+
+        # Cursor skills (.mdc)
+        for mdc in sorted(directory.glob("*.mdc")):
+            if not mdc.name.startswith("_"):
+                self._load_cursor(mdc, is_builtin=is_builtin)
+
+        # Claude Code skills (SKILL.md en subdirectorios)
+        for skill_dir in sorted(directory.iterdir()):
+            if skill_dir.is_dir() and not skill_dir.name.startswith("_"):
+                skill_md = skill_dir / "SKILL.md"
+                if skill_md.exists():
+                    self._load_claude_code(skill_md, is_builtin=is_builtin)
+
+    def _load_python(self, path: Path, is_builtin: bool = False) -> Optional[Skill]:
+        """Carga un skill Python desde archivo."""
+        try:
+            import sys
+            module_name = f"hanus_skill_{path.stem}"
+
+            spec = importlib.util.spec_from_file_location(module_name, path)
+            if not spec or not spec.loader:
+                return None
+
+            module = importlib.util.module_from_spec(spec)
+            sys.modules[module_name] = module
+            spec.loader.exec_module(module)
+
+            name = getattr(module, "NAME", path.stem).lower().replace("-", "_")
+            description = getattr(module, "DESCRIPTION", "Sin descripción")
+            usage = getattr(module, "USAGE", "")
+            version = getattr(module, "VERSION", "1.0")
+            author = getattr(module, "AUTHOR", "Desconocido")
+
+            skill = Skill(
+                name=name,
+                description=description,
+                usage=usage,
+                version=version,
+                author=author,
+                path=path,
+                skill_type=SkillType.PYTHON,
+                module=module,
+                is_builtin=is_builtin,
+            )
+
+            self.skills[name] = skill
+            return skill
+
+        except Exception as e:
+            print(f"  [SkillManager] Error cargando Python skill '{path.name}': {e}")
+            return None
+
+    def _load_markdown(self, path: Path, is_builtin: bool = False) -> Optional[Skill]:
+        """Carga un skill Markdown (formato HanusCode o Claude Code simple)."""
+        try:
+            content = path.read_text(encoding="utf-8")
+
+            metadata = self._parse_frontmatter(content, path)
+            body = content
+
+            # Separar frontmatter del body
+            if content.startswith("---"):
+                parts = content.split("---", 2)
+                if len(parts) >= 3:
+                    body = parts[2].strip()
+
+            # Determinar si es formato Claude Code
+            is_claude_format = "arguments" in metadata or "allowed-tools" in metadata
+
+            skill = Skill(
+                name=str(metadata.get("name", path.stem)).lower().replace("-", "_"),
+                description=str(metadata.get("description", "Sin descripción")),
+                usage=str(metadata.get("usage", "")),
+                version=str(metadata.get("version", "1.0")),
+                author=str(metadata.get("author", metadata.get("created-by", "Desconocido"))),
+                path=path,
+                skill_type=SkillType.CLAUDE_CODE if is_claude_format else SkillType.MARKDOWN,
+                content=body,
+                is_builtin=is_builtin,
+                arguments=metadata.get("arguments", []),
+                allowed_tools=metadata.get("allowed-tools", []),
+                disable_auto_invoke=metadata.get("disable-model-invocation", False),
+            )
+
+            self.skills[skill.name] = skill
+            return skill
+
+        except Exception as e:
+            print(f"  [SkillManager] Error cargando Markdown skill '{path.name}': {e}")
+            return None
+
+    def _load_claude_code(self, path: Path, is_builtin: bool = False) -> Optional[Skill]:
+        """Carga un skill en formato Claude Code (SKILL.md en directorio)."""
+        try:
+            content = path.read_text(encoding="utf-8")
+            metadata = self._parse_frontmatter(content, path)
+
+            # Separar body
+            body = content
+            if content.startswith("---"):
+                parts = content.split("---", 2)
+                if len(parts) >= 3:
+                    body = parts[2].strip()
+
+            # Nombre del directorio como fallback
+            dir_name = path.parent.name.lower().replace("-", "_")
+            name = str(metadata.get("name", dir_name)).lower().replace("-", "_")
+
+            skill = Skill(
+                name=name,
+                description=str(metadata.get("description", "Sin descripción")),
+                usage=str(metadata.get("usage", "")),
+                version=str(metadata.get("version", "1.0")),
+                author=str(metadata.get("created-by", metadata.get("author", "Desconocido"))),
+                path=path,
+                skill_type=SkillType.CLAUDE_CODE,
+                content=body,
+                is_builtin=is_builtin,
+                arguments=metadata.get("arguments", []),
+                allowed_tools=self._parse_allowed_tools(metadata.get("allowed-tools", [])),
+                disable_auto_invoke=metadata.get("disable-model-invocation", False),
+            )
+
+            self.skills[name] = skill
+            return skill
+
+        except Exception as e:
+            print(f"  [SkillManager] Error cargando Claude Code skill '{path}': {e}")
+            return None
+
+    def _load_cursor(self, path: Path, is_builtin: bool = False) -> Optional[Skill]:
+        """Carga un skill en formato Cursor (.mdc)."""
+        try:
+            content = path.read_text(encoding="utf-8")
+            metadata = self._parse_frontmatter(content, path)
+
+            # Separar body
+            body = content
+            if content.startswith("---"):
+                parts = content.split("---", 2)
+                if len(parts) >= 3:
+                    body = parts[2].strip()
+
+            name = path.stem.lower().replace("-", "_")
+
+            skill = Skill(
+                name=name,
+                description=str(metadata.get("description", "Sin descripción")),
+                usage="",
+                version="1.0",
+                author="Cursor",
+                path=path,
+                skill_type=SkillType.CURSOR,
+                content=body,
+                is_builtin=is_builtin,
+                globs=metadata.get("globs", []),
+                always_apply=metadata.get("alwaysApply", False),
+            )
+
+            self.skills[name] = skill
+            return skill
+
+        except Exception as e:
+            print(f"  [SkillManager] Error cargando Cursor skill '{path.name}': {e}")
+            return None
+
+    def _parse_frontmatter(self, content: str, path: Path) -> Dict:
+        """Parsea frontmatter YAML de un archivo."""
+        metadata = {"name": path.stem.lower().replace("-", "_")}
+
+        if content.startswith("---"):
+            parts = content.split("---", 2)
+            if len(parts) >= 2:
+                frontmatter = parts[1].strip()
+                try:
+                    fm_data = yaml.safe_load(frontmatter) or {}
+                    metadata.update(fm_data)
+                except yaml.YAMLError:
+                    pass
+
+        # Normalizar arguments (puede ser lista o string)
+        if "arguments" in metadata and isinstance(metadata["arguments"], str):
+            # Formato: "issue branch" -> ["issue", "branch"]
+            metadata["arguments"] = metadata["arguments"].split()
+
+        return metadata
+
+    def _parse_allowed_tools(self, tools) -> List[str]:
+        """Parsea allowed-tools que puede ser string, lista o None."""
+        if tools is None:
+            return []
+        if isinstance(tools, str):
+            return tools.split()
+        return list(tools)
+
+    def reload(self):
+        """Recarga todos los skills."""
+        self._load_all()
+
+    def get(self, name: str) -> Optional[Skill]:
+        """Obtiene un skill por nombre."""
+        return self.skills.get(name.lower())
+
+    def list_skills(self) -> List[Skill]:
+        """Lista todos los skills."""
+        return list(self.skills.values())
+
+    def run(self, name: str, args: str = "") -> str:
+        """Ejecuta un skill."""
+        skill = self.get(name)
+        if skill is None:
+            available = list(self.skills.keys())
+            return f"[Error] Skill '{name}' no encontrado. Disponibles: {available}"
+        return skill.run(args)
+
+    def install(self, url: str, name: Optional[str] = None) -> str:
+        """Instala un skill desde una URL (soporta múltiples formatos)."""
+        SKILLS_DIR_USER.mkdir(parents=True, exist_ok=True)
+
+        try:
+            req = urllib.request.Request(url, headers={
+                "User-Agent": "HanusCode/1.0"
+            })
+
+            with urllib.request.urlopen(req, timeout=30) as resp:
+                content = resp.read().decode("utf-8")
+
+            # Detectar tipo de skill
+            if url.endswith(".mdc"):
+                return self._install_cursor(content, url, name)
+            elif url.endswith("SKILL.md") or "SKILL.md" in url:
+                return self._install_claude_code(content, url, name)
+            elif url.endswith(".md") or content.strip().startswith("---"):
+                return self._install_markdown(content, url, name)
+            else:
+                return self._install_python(content, url, name)
+
+        except urllib.error.HTTPError as e:
+            return f"Error HTTP {e.code}: {e.reason}"
+        except urllib.error.URLError as e:
+            return f"Error de conexión: {e.reason}"
+        except Exception as e:
+            return f"Error instalando skill: {e}"
+
+    def _install_python(self, content: str, url: str, name: Optional[str] = None) -> str:
+        """Instala un skill Python."""
+        if "def run(" not in content:
+            return "Error: El archivo no es un skill Python válido (falta función run())"
+
+        if not name:
+            name_match = re.search(r'NAME\s*=\s*["\'](\w+)["\']', content)
+            name = name_match.group(1) if name_match else Path(url).stem
+
+        name = name.lower().replace("-", "_").replace(" ", "_")
+        dest_path = SKILLS_DIR_USER / f"{name}.py"
+        dest_path.write_text(content, encoding="utf-8")
+
+        skill = self._load_python(dest_path, is_builtin=False)
+        return f"✓ Skill Python '{skill.name}' instalado\n{skill.get_doc()}" if skill else f"✓ Guardado en {dest_path}"
+
+    def _install_markdown(self, content: str, url: str, name: Optional[str] = None) -> str:
+        """Instala un skill Markdown."""
+        metadata = self._parse_frontmatter(content, Path(url))
+        name = name or metadata.get("name", Path(url).stem)
+        name = name.lower().replace("-", "_").replace(" ", "_")
+
+        dest_path = SKILLS_DIR_USER / f"{name}.md"
+        dest_path.write_text(content, encoding="utf-8")
+
+        skill = self._load_markdown(dest_path, is_builtin=False)
+        return f"✓ Skill Markdown '{skill.name}' instalado\n{skill.get_doc()}" if skill else f"✓ Guardado en {dest_path}"
+
+    def _install_claude_code(self, content: str, url: str, name: Optional[str] = None) -> str:
+        """Instala un skill Claude Code (crea directorio con SKILL.md)."""
+        metadata = self._parse_frontmatter(content, Path(url))
+        skill_name = name or metadata.get("name", "imported")
+        skill_name = skill_name.lower().replace("-", "_").replace(" ", "_")
+
+        # Crear directorio para el skill
+        skill_dir = SKILLS_DIR_USER / skill_name
+        skill_dir.mkdir(parents=True, exist_ok=True)
+
+        dest_path = skill_dir / "SKILL.md"
+        dest_path.write_text(content, encoding="utf-8")
+
+        skill = self._load_claude_code(dest_path, is_builtin=False)
+        return f"✓ Skill Claude Code '{skill.name}' instalado\n{skill.get_doc()}" if skill else f"✓ Guardado en {dest_path}"
+
+    def _install_cursor(self, content: str, url: str, name: Optional[str] = None) -> str:
+        """Instala un skill Cursor (.mdc)."""
+        name = name or Path(url).stem
+        name = name.lower().replace("-", "_").replace(" ", "_")
+
+        dest_path = SKILLS_DIR_USER / f"{name}.mdc"
+        dest_path.write_text(content, encoding="utf-8")
+
+        skill = self._load_cursor(dest_path, is_builtin=False)
+        return f"✓ Skill Cursor '{skill.name}' instalado\n{skill.get_doc()}" if skill else f"✓ Guardado en {dest_path}"
+
+    def install_from_gist(self, gist_url: str) -> str:
+        """Instala un skill desde un GitHub Gist."""
+        gist_id = gist_url.split("/")[-1].split("?")[0]
+        api_url = f"https://api.github.com/gists/{gist_id}"
+
+        try:
+            req = urllib.request.Request(api_url, headers={
+                "User-Agent": "HanusCode/1.0",
+                "Accept": "application/vnd.github.v3+json"
+            })
+
+            with urllib.request.urlopen(req, timeout=30) as resp:
+                data = json.loads(resp.read().decode("utf-8"))
+
+            for filename, file_data in data.get("files", {}).items():
+                content = file_data.get("content", "")
+                if not content:
+                    continue
+
+                SKILLS_DIR_USER.mkdir(parents=True, exist_ok=True)
+
+                if filename.endswith(".mdc"):
+                    dest_path = SKILLS_DIR_USER / filename
+                    dest_path.write_text(content, encoding="utf-8")
+                    skill = self._load_cursor(dest_path, is_builtin=False)
+                elif filename == "SKILL.md":
+                    # Claude Code format - crear directorio
+                    skill_dir = SKILLS_DIR_USER / Path(filename).stem
+                    skill_dir.mkdir(parents=True, exist_ok=True)
+                    dest_path = skill_dir / "SKILL.md"
+                    dest_path.write_text(content, encoding="utf-8")
+                    skill = self._load_claude_code(dest_path, is_builtin=False)
+                elif filename.endswith(".md"):
+                    dest_path = SKILLS_DIR_USER / filename
+                    dest_path.write_text(content, encoding="utf-8")
+                    skill = self._load_markdown(dest_path, is_builtin=False)
+                elif filename.endswith(".py"):
+                    dest_path = SKILLS_DIR_USER / filename
+                    dest_path.write_text(content, encoding="utf-8")
+                    skill = self._load_python(dest_path, is_builtin=False)
+                else:
+                    continue
+
+                if skill:
+                    return f"✓ Skill '{skill.name}' instalado desde Gist\n{skill.get_doc()}"
+
+            return "Error: No se encontró ningún archivo de skill en el Gist"
+
+        except Exception as e:
+            return f"Error instalando desde Gist: {e}"
+
+    def create_markdown(self, name: str, description: str, content: str = "") -> str:
+        """Crea un nuevo skill Markdown."""
+        SKILLS_DIR_USER.mkdir(parents=True, exist_ok=True)
+
+        name = name.lower().replace("-", "_").replace(" ", "_")
+        dest_path = SKILLS_DIR_USER / f"{name}.md"
+
+        if dest_path.exists():
+            return f"Error: Ya existe un skill con nombre '{name}'"
+
+        template = f"""---
+name: {name}
+description: {description}
+version: "1.0"
+author: "User"
+---
+
+# {description.title()}
+
+{content or "Instrucciones para el agente..."}
+"""
+
+        dest_path.write_text(template, encoding="utf-8")
+        skill = self._load_markdown(dest_path, is_builtin=False)
+
+        return f"✓ Skill '{skill.name}' creado\nArchivo: {dest_path}" if skill else "Error creando skill"
+
+    def remove(self, name: str) -> str:
+        """Elimina un skill instalado."""
+        skill = self.get(name)
+
+        if skill is None:
+            return f"Error: Skill '{name}' no encontrado"
+
+        if skill.is_builtin:
+            return f"Error: No se pueden eliminar skills builtin"
+
+        try:
+            # Si es Claude Code format, eliminar directorio
+            if skill.skill_type == SkillType.CLAUDE_CODE and skill.path.name == "SKILL.md":
+                import shutil
+                shutil.rmtree(skill.path.parent)
+            else:
+                skill.path.unlink()
+
+            del self.skills[name.lower()]
+            return f"✓ Skill '{name}' eliminado"
+        except Exception as e:
+            return f"Error eliminando skill: {e}"
+
+    def get_skill_docs(self) -> str:
+        """Retorna documentación de todos los skills."""
+        if not self.skills:
+            return ""
+
+        docs = ["## Skills disponibles\n"]
+        docs.append("Los skills son comandos reutilizables. Invócalos con `/nombre_skill`")
+        docs.append("")
+
+        # Agrupar por tipo
+        by_type = {
+            SkillType.MARKDOWN: [],
+            SkillType.PYTHON: [],
+            SkillType.CLAUDE_CODE: [],
+            SkillType.CURSOR: [],
+        }
+
+        for skill in self.skills.values():
+            by_type[skill.skill_type].append(skill)
+
+        type_labels = {
+            SkillType.MARKDOWN: ("📝 Skills Markdown", "HanusCode format"),
+            SkillType.PYTHON: ("🐍 Skills Python", "Ejecutables"),
+            SkillType.CLAUDE_CODE: ("🤖 Skills Claude Code", "Compatible"),
+            SkillType.CURSOR: ("⚡ Skills Cursor", "Compatible"),
+        }
+
+        for skill_type, skills_list in by_type.items():
+            if skills_list:
+                label, hint = type_labels[skill_type]
+                docs.append(f"### {label} ({hint})")
+                for skill in sorted(skills_list, key=lambda s: s.name):
+                    docs.append(f"- `/{skill.name}` — {skill.description}")
+                docs.append("")
+
+        return "\n".join(docs)
+
+    def get_commands(self) -> Dict[str, str]:
+        """Retorna diccionario de comandos para UI."""
+        type_prefix = {
+            SkillType.MARKDOWN: "[MD]",
+            SkillType.PYTHON: "[PY]",
+            SkillType.CLAUDE_CODE: "[CC]",
+            SkillType.CURSOR: "[MC]",
+        }
+        return {name: f"{type_prefix.get(s.skill_type, '')} {s.description}"
+                for name, s in self.skills.items()}
+
+
+# Singleton global
+_skill_manager: Optional[SkillManager] = None
+
+
+def get_skill_manager() -> SkillManager:
+    """Obtiene el gestor de skills."""
+    global _skill_manager
+    if _skill_manager is None:
+        _skill_manager = SkillManager()
+    return _skill_manager