Creador de Habilidades: Construir Habilidades Efectivas de Claude

--- name: skill-creator description: Guía para crear habilidades efectivas. Esta habilidad debe usarse cuando los usuarios quieran crear una nueva habilidad (o actualizar una existente) que extienda las capacidades de Claude con conocimiento especializado, flujos de trabajo o integraciones de herramientas. license: Términos completos en LICENSE.txt --- # Creador de Habilidades Esta habilidad proporciona orientación para crear habilidades efectivas. ## Acerca de las Habilidades Las habilidades son paquetes modulares y autocontenidos que extienden las capacidades de Claude al proporcionar conocimiento especializado, flujos de trabajo y herramientas. Piense en ellas como "guías de incorporación" para dominios o tareas específicos - transforman a Claude de un agente de propósito general a un agente especializado equipado con conocimiento procedimental que ningún modelo puede poseer completamente. ### Qué Proporcionan las Habilidades 1. Flujos de trabajo especializados - Procedimientos de múltiples pasos para dominios específicos 2. Integraciones de herramientas - Instrucciones para trabajar con formatos de archivo o APIs específicos 3. Experiencia de dominio - Conocimiento específico de la empresa, esquemas, lógica de negocio 4. Recursos empaquetados - Scripts, referencias y activos para tareas complejas y repetitivas ## Principios Fundamentales ### La Concisión es Clave La ventana de contexto es un bien público. Las habilidades comparten la ventana de contexto con todo lo demás que Claude necesita: el prompt del sistema, el historial de conversación, los metadatos de otras habilidades y la solicitud real del usuario. **Suposición predeterminada: Claude ya es muy inteligente.** Solo agregue contexto que Claude no tenga ya. Cuestiona cada pieza de información: "¿Realmente necesita Claude esta explicación?" y "¿Este párrafo justifica su costo de tokens?" Prefiera ejemplos concisos sobre explicaciones verbosas. ### Establezca Grados Apropiados de Libertad Haga coincidir el nivel de especificidad con la fragilidad y variabilidad de la tarea: **Alta libertad (instrucciones basadas en texto)**: Úselo cuando múltiples enfoques sean válidos, las decisiones dependan del contexto o los heurísticos guíen el enfoque. **Libertad media (pseudocódigo o scripts con parámetros)**: Úselo cuando exista un patrón preferido, cierta variación sea aceptable o la configuración afecte el comportamiento. **Baja libertad (scripts específicos, pocos parámetros)**: Úselo cuando las operaciones sean frágiles y propensas a errores, la consistencia sea crítica o deba seguirse una secuencia específica. Piense en Claude explorando un camino: un puente estrecho con acantilados necesita barandillas específicas (baja libertad), mientras que un campo abierto permite muchas rutas (alta libertad). ### Anatomía de una Habilidad Cada habilidad consiste en un archivo SKILL.md requerido y recursos empaquetados opcionales: ``` skill-name/ ├── SKILL.md (requerido) │ ├── Metadatos frontmatter YAML (requerido) │ │ ├── name: (requerido) │ │ └── description: (requerido) │ └── Instrucciones Markdown (requerido) └── Recursos Empaquetados (opcional) ├── scripts/ - Código ejecutable (Python/Bash/etc.) ├── references/ - Documentación destinada a cargarse en el contexto según sea necesario └── assets/ - Archivos utilizados en la salida (plantillas, iconos, fuentes, etc.) ``` #### SKILL.md (requerido) Cada SKILL.md consiste en: - **Frontmatter** (YAML): Contiene los campos `name` y `description`. Estos son los únicos campos que Claude lee para determinar cuándo se usa la habilidad, por lo que es muy importante ser claro y completo al describir qué es la habilidad y cuándo debe usarse. - **Cuerpo** (Markdown): Instrucciones y orientación para usar la habilidad. Solo se carga DESPUÉS de que la habilidad se active (si es que se activa). #### Recursos Empaquetados (opcional) ##### Scripts (`scripts/`) Código ejecutable (Python/Bash/etc.) para tareas que requieren confiabilidad determinista o que se reescriben repetidamente. - **Cuándo incluirlos**: Cuando el mismo código se reescribe repetidamente o se necesita confiabilidad determinista - **Ejemplo**: `scripts/rotate_pdf.py` para tareas de rotación de PDF - **Beneficios**: Eficiente en tokens, determinista, puede ejecutarse sin cargarse en el contexto - **Nota**: Es posible que Claude aún necesite leer los scripts para parchearlos o realizar ajustes específicos del entorno ##### Referencias (`references/`) Documentación y material de referencia destinados a cargarse según sea necesario en el contexto para informar el proceso y pensamiento de Claude. - **Cuándo incluirlas**: Para documentación que Claude debe consultar mientras trabaja - **Ejemplos**: `references/finance.md` para esquemas financieros, `references/mnda.md` para plantilla de NDA de la empresa, `references/policies.md` para políticas de la empresa, `references/api_docs.md` para especificaciones de API - **Casos de uso**: Esquemas de bases de datos, documentación de API, conocimiento de dominio, políticas de la empresa, guías de flujo de trabajo detalladas - **Beneficios**: Mantiene SKILL.md ágil, se carga solo cuando Claude determina que es necesario - **Mejores prácticas**: Si los archivos son grandes (>10k palabras), incluya patrones de búsqueda grep en SKILL.md - **Evite la duplicación**: La información debe vivir en SKILL.md o en archivos de referencias, no en ambos. ##### Activos (`assets/`) Archivos que no están destinados a cargarse en el contexto, sino que se utilizan dentro de la salida que Claude produce. - **Cuándo incluirlos**: Cuando la habilidad necesita archivos que se usarán en la salida final - **Ejemplos**: `assets/logo.png` para activos de marca, `assets/slides.pptx` para plantillas de PowerPoint - **Casos de uso**: Plantillas, imágenes, iconos, código repetitivo, fuentes, documentos de muestra ### Principio de Diseño de Divulgación Progresiva Las habilidades utilizan un sistema de carga de tres niveles para gestionar el contexto de manera eficiente: 1. **Metadatos (name + description)** - Siempre en contexto (~100 palabras) 2. **Cuerpo de SKILL.md** - Cuando la habilidad se activa (<5k palabras) 3. **Recursos empaquetados** - Según lo necesite Claude Mantenga el cuerpo de SKILL.md en lo esencial y por debajo de 500 líneas para minimizar la inflación del contexto. ## Proceso de Creación de Habilidades La creación de habilidades implica estos pasos: 1. Comprender la habilidad con ejemplos concretos 2. Planificar contenidos de habilidad reutilizables (scripts, referencias, activos) 3. Inicializar la habilidad (ejecutar init_skill.py) 4. Editar la habilidad (implementar recursos y escribir SKILL.md) 5. Empaquetar la habilidad (ejecutar package_skill.py) 6. Iterar según el uso real ### Paso 3: Inicializar la Habilidad Al crear una nueva habilidad desde cero, siempre ejecute el script `init_skill.py`: ```bash scripts/init_skill.py <skill-name> --path <output-directory> ``` ### Paso 4: Editar la Habilidad Consulte estas guías útiles según las necesidades de su habilidad: - **Procesos de múltiples pasos**: Consulte references/workflows.md para flujos de trabajo secuenciales y lógica condicional - **Formatos de salida específicos o estándares de calidad**: Consulte references/output-patterns.md para plantillas y patrones de ejemplo ### Paso 5: Empaquetar una Habilidad ```bash scripts/package_skill.py <path/to/skill-folder> ``` El script de empaquetado valida y crea un archivo .skill para distribución. FILE:references/workflows.md # Patrones de Flujo de Trabajo ## Flujos de Trabajo Secuenciales Para tareas complejas, divida las operaciones en pasos secuenciales claros. A menudo es útil dar a Claude una visión general del proceso hacia el comienzo de SKILL.md: ```markdown Completar un formulario PDF implica estos pasos: 1. Analizar el formulario (ejecutar analyze_form.py) 2. Crear mapeo de campos (editar fields.json) 3. Validar mapeo (ejecutar validate_fields.py) 4. Completar el formulario (ejecutar fill_form.py) 5. Verificar la salida (ejecutar verify_output.py) ``` ## Flujos de Trabajo Condicionales Para tareas con lógica de ramificación, guíe a Claude a través de puntos de decisión: ```markdown 1. Determinar el tipo de modificación: **¿Crear contenido nuevo?** → Siga el "Flujo de creación" a continuación **¿Editar contenido existente?** → Siga el "Flujo de edición" a continuación 2. Flujo de creación: [pasos] 3. Flujo de edición: [pasos] ``` FILE:references/output-patterns.md # Patrones de Salida Use estos patrones cuando las habilidades necesiten producir una salida consistente y de alta calidad. ## Patrón de Plantilla Proporcione plantillas para el formato de salida. Haga coincidir el nivel de rigor con sus necesidades. **Para requisitos estrictos (como respuestas de API o formatos de datos):** ```markdown ## Estructura del informe USE SIEMPRE esta estructura de plantilla exacta: # [Título del Análisis] ## Resumen ejecutivo [Resumen de un párrafo de los hallazgos clave] ## Hallazgos clave - Hallazgo 1 con datos de respaldo - Hallazgo 2 con datos de respaldo - Hallazgo 3 con datos de respaldo ## Recomendaciones 1. Recomendación específica y accionable 2. Recomendación específica y accionable ``` **Para orientación flexible (cuando la adaptación es útil):** ```markdown ## Estructura del informe Aquí hay un formato predeterminado sensato, pero use su mejor criterio: # [Título del Análisis] ## Resumen ejecutivo [Resumen] ## Hallazgos clave [Adapte las secciones según lo que descubra] ## Recomendaciones [Adapte al contexto específico] Ajuste las secciones según sea necesario para el tipo de análisis específico. ``` ## Patrón de Ejemplos Para habilidades donde la calidad de la salida depende de ver ejemplos, proporcione pares de entrada/salida: ```markdown ## Formato de mensaje de commit Genere mensajes de commit siguiendo estos ejemplos: **Ejemplo 1:** Entrada: Se agregó autenticación de usuario con tokens JWT Salida: ``` feat(auth): implementar autenticación basada en JWT Agregar endpoint de inicio de sesión y middleware de validación de tokens ``` **Ejemplo 2:** Entrada: Se corrigió error donde las fechas se mostraban incorrectamente en informes Salida: ``` fix(reports): corregir formato de fecha en conversión de zona horaria Usar marcas de tiempo UTC de manera consistente en la generación de informes ``` Siga este estilo: tipo(alcance): descripción breve, luego explicación detallada. ``` Los ejemplos ayudan a Claude a comprender el estilo deseado y el nivel de detalle más claramente que las descripciones solas. FILE:scripts/quick_validate.py #!/usr/bin/env python3 """ Script de validación rápida para habilidades - versión mínima """ import sys import os import re import yaml from pathlib import Path def validate_skill(skill_path): """Validación básica de una habilidad""" skill_path = Path(skill_path) # Verificar que SKILL.md exista skill_md = skill_path / 'SKILL.md' if not skill_md.exists(): return False, "SKILL.md no encontrado" # Leer y validar frontmatter content = skill_md.read_text() if not content.startswith('---'): return False, "No se encontró frontmatter YAML" # Extraer frontmatter match = re.match(r'^---\n(.*?)\n---', content, re.DOTALL) if not match: return False, "Formato de frontmatter inválido" frontmatter_text = match.group(1) # Analizar frontmatter YAML try: frontmatter = yaml.safe_load(frontmatter_text) if not isinstance(frontmatter, dict): return False, "El frontmatter debe ser un diccionario YAML" except yaml.YAMLError as e: return False, f"YAML inválido en frontmatter: {e}" # Definir propiedades permitidas ALLOWED_PROPERTIES = {'name', 'description', 'license', 'allowed-tools', 'metadata'} # Verificar propiedades inesperadas (excluyendo claves anidadas bajo metadata) unexpected_keys = set(frontmatter.keys()) - ALLOWED_PROPERTIES if unexpected_keys: return False, ( f"Clave(s) inesperada(s) en frontmatter de SKILL.md: {', '.join(sorted(unexpected_keys))}. " f"Las propiedades permitidas son: {', '.join(sorted(ALLOWED_PROPERTIES))}" ) # Verificar campos requeridos if 'name' not in frontmatter: return False, "Falta 'name' en frontmatter" if 'description' not in frontmatter: return False, "Falta 'description' en frontmatter" # Extraer nombre para validación name = frontmatter.get('name', '') if not isinstance(name, str): return False, f"El nombre debe ser una cadena, se obtuvo {type(name).__name__}" name = name.strip() if name: # Verificar convención de nomenclatura (hyphen-case: minúsculas con guiones) if not re.match(r'^[a-z0-9-]+$', name): return False, f"El nombre '{name}' debe estar en hyphen-case (solo letras minúsculas, dígitos y guiones)" if name.startswith('-') or name.endswith('-') or '--' in name: return False, f"El nombre '{name}' no puede comenzar/terminar con guion ni contener guiones consecutivos" # Verificar longitud del nombre (máximo 64 caracteres según especificación) if len(name) > 64: return False, f"El nombre es demasiado largo ({len(name)} caracteres). El máximo es 64 caracteres." # Extraer y validar descripción description = frontmatter.get('description', '') if not isinstance(description, str): return False, f"La descripción debe ser una cadena, se obtuvo {type(description).__name__}" description = description.strip() if description: # Verificar corchetes angulares if '<' in description or '>' in description: return False, "La descripción no puede contener corchetes angulares (< o >)" # Verificar longitud de la descripción (máximo 1024 caracteres según especificación) if len(description) > 1024: return False, f"La descripción es demasiado larga ({len(description)} caracteres). El máximo es 1024 caracteres." return True, "¡La habilidad es válida!" if __name__ == "__main__": if len(sys.argv) != 2: print("Uso: python quick_validate.py <directorio_de_habilidad>") sys.exit(1) valid, message = validate_skill(sys.argv[1]) print(message) sys.exit(0 if valid else 1) FILE:scripts/init_skill.py #!/usr/bin/env python3 """ Inicializador de Habilidades - Crea una nueva habilidad a partir de plantilla Uso: init_skill.py <skill-name> --path <ruta> Ejemplos: init_skill.py my-new-skill --path skills/public init_skill.py my-api-helper --path skills/private init_skill.py custom-skill --path /custom/location """ import sys from pathlib import Path SKILL_TEMPLATE = """--- name: {skill_name} description: [TODO: Explicación completa e informativa de qué hace la habilidad y cuándo usarla. Incluya CUÁNDO usar esta habilidad - escenarios específicos, tipos de archivo o tareas que la activan.] --- # {skill_title} ## Resumen [TODO: 1-2 oraciones explicando qué permite esta habilidad] ## Recursos Esta habilidad incluye directorios de recursos de ejemplo que demuestran cómo organizar diferentes tipos de recursos empaquetados: ### scripts/ Código ejecutable (Python/Bash/etc.) que se puede ejecutar directamente para realizar operaciones específicas. ### references/ Documentación y material de referencia destinados a cargarse en el contexto para informar el proceso y pensamiento de Claude. ### assets/ Archivos que no están destinados a cargarse en el contexto, sino que se utilizan dentro de la salida que Claude produce. --- **Cualquier directorio innecesario puede eliminarse.** No todas las habilidades requieren los tres tipos de recursos. """ EXAMPLE_SCRIPT = '''#!/usr/bin/env python3 """ Script auxiliar de ejemplo para {skill_name} Este es un script de marcador de posición que se puede ejecutar directamente. Reemplácelo con la implementación real o elimínelo si no es necesario. """ def main(): print("Este es un script de ejemplo para {skill_name}") # TODO: Agregar lógica real del script aquí if __name__ == "__main__": main() ''' EXAMPLE_REFERENCE = """# Documentación de Referencia para {skill_title} Este es un marcador de posición para documentación de referencia detallada. Reemplácelo con contenido de referencia real o elimínelo si no es necesario. """ EXAMPLE_ASSET = """# Archivo de Activo de Ejemplo Este marcador de posición representa dónde se almacenarían los archivos de activos. Reemplácelo con archivos de activos reales (plantillas, imágenes, fuentes, etc.) o elimínelo si no es necesario. """ def title_case_skill_name(skill_name): """Convertir nombre de habilidad con guiones a Title Case para visualización.""" return ' '.join(word.capitalize() for word in skill_name.split('-')) def init_skill(skill_name, path): """Inicializar un nuevo directorio de habilidad con SKILL.md de plantilla.""" skill_dir = Path(path).resolve() / skill_name if skill_dir.exists(): print(f"❌ Error: El directorio de habilidad ya existe: {skill_dir}") return None try: skill_dir.mkdir(parents=True, exist_ok=False) print(f"✅ Directorio de habilidad creado: {skill_dir}") except Exception as e: print(f"❌ Error al crear directorio: {e}") return None skill_title = title_case_skill_name(skill_name) skill_content = SKILL_TEMPLATE.format(skill_name=skill_name, skill_title=skill_title) skill_md_path = skill_dir / 'SKILL.md' try: skill_md_path.write_text(skill_content) print("✅ SKILL.md creado") except Exception as e: print(f"❌ Error al crear SKILL.md: {e}") return None try: scripts_dir = skill_dir / 'scripts' scripts_dir.mkdir(exist_ok=True) example_script = scripts_dir / 'example.py' example_script.write_text(EXAMPLE_SCRIPT.format(skill_name=skill_name)) example_script.chmod(0o755) print("✅ scripts/example.py creado") references_dir = skill_dir / 'references' references_dir.mkdir(exist_ok=True) example_reference = references_dir / 'api_reference.md' example_reference.write_text(EXAMPLE_REFERENCE.format(skill_title=skill_title)) print("✅ references/api_reference.md creado") assets_dir = skill_dir / 'assets' assets_dir.mkdir(exist_ok=True) example_asset = assets_dir / 'example_asset.txt' example_asset.write_text(EXAMPLE_ASSET) print("✅ assets/example_asset.txt creado") except Exception as e: print(f"❌ Error al crear directorios de recursos: {e}") return None print(f"\n✅ Habilidad '{skill_name}' inicializada exitosamente en {skill_dir}") return skill_dir def main(): if len(sys.argv) < 4 or sys.argv[2] != '--path': print("Uso: init_skill.py <skill-name> --path <ruta>") sys.exit(1) skill_name = sys.argv[1] path = sys.argv[3] print(f"🚀 Inicializando habilidad: {skill_name}") print(f" Ubicación: {path}") print() result = init_skill(skill_name, path) sys.exit(0 if result else 1) if __name__ == "__main__": main() FILE:scripts/package_skill.py #!/usr/bin/env python3 """ Empaquetador de Habilidades - Crea un archivo .skill distribuible de una carpeta de habilidad Uso: python utils/package_skill.py <ruta/a/carpeta-de-habilidad> [directorio-de-salida] Ejemplo: python utils/package_skill.py skills/public/my-skill python utils/package_skill.py skills/public/my-skill ./dist """ import sys import zipfile from pathlib import Path from quick_validate import validate_skill def package_skill(skill_path, output_dir=None): """Empaquetar una carpeta de habilidad en un archivo .skill.""" skill_path = Path(skill_path).resolve() if not skill_path.exists(): print(f"❌ Error: Carpeta de habilidad no encontrada: {skill_path}") return None if not skill_path.is_dir(): print(f"❌ Error: La ruta no es un directorio: {skill_path}") return None skill_md = skill_path / "SKILL.md" if not skill_md.exists(): print(f"❌ Error: SKILL.md no encontrado en {skill_path}") return None print("🔍 Validando habilidad...") valid, message = validate_skill(skill_path) if not valid: print(f"❌ Validación fallida: {message}") print(" Corrija los errores de validación antes de empaquetar.") return None print(f"✅ {message}\n") skill_name = skill_path.name if output_dir: output_path = Path(output_dir).resolve() output_path.mkdir(parents=True, exist_ok=True) else: output_path = Path.cwd() skill_filename = output_path / f"{skill_name}.skill" try: with zipfile.ZipFile(skill_filename, 'w', zipfile.ZIP_DEFLATED) as zipf: for file_path in skill_path.rglob('*'): if file_path.is_file(): arcname = file_path.relative_to(skill_path.parent) zipf.write(file_path, arcname) print(f" Agregado: {arcname}") print(f"\n✅ Habilidad empaquetada exitosamente en: {skill_filename}") return skill_filename except Exception as e: print(f"❌ Error al crear archivo .skill: {e}") return None def main(): if len(sys.argv) < 2: print("Uso: python utils/package_skill.py <ruta/a/carpeta-de-habilidad> [directorio-de-salida]") sys.exit(1) skill_path = sys.argv[1] output_dir = sys.argv[2] if len(sys.argv) > 2 else None print(f"📦 Empaquetando habilidad: {skill_path}") if output_dir: print(f" Directorio de salida: {output_dir}") print() result = package_skill(skill_path, output_dir) sys.exit(0 if result else 1) if __name__ == "__main__": main()