ahundt/ai-skill-builder

AI Skill Builder

Construye Skills de Agente utilizando el formato compartido SKILL.md y la metodología de Anthropic: el núcleo portátil más pequeño que funciona en cada destino nombrado, más adaptadores de runtime explícitos. La portabilidad es una afirmación de compatibilidad probada, no un estilo de formato. references/sources.md cita documentación del host para Claude Code, Codex y Qwen Code; cualquier otro host no ha sido probado aquí, así que verifica al que te diriges (Paso 1).

Esta metodología requiere deliberadamente regiones XML semánticas consistentes dentro del cuerpo de Markdown. Esa es una política de calidad para reducir la ambigüedad en instrucciones operacionales complejas, respaldada por la guía actual de prompting de Anthropic y verificada por las pruebas de avance en el Paso 4. No es un requisito del parser de la especificación portátil de Skills de Agente, un límite de autorización, ni una afirmación de que solo XML previene la inyección de prompts.

Fuente principal de la metodología: "The Complete Guide to Building Skills for Claude" (Anthropic, enero de 2026)

• PDF: https://resources.anthropic.com/hubfs/The-Complete-Guide-to-Building-Skill-for-Claude.pdf
• Texto extraído: references/ai-skill-builder-guide.md

Fuente del formato portátil: https://agentskills.io/specification

---

Inicio Rápido

Para crear un skill desde cero, sigue el proceso de 4 fases a continuación. Para mejorar un skill existente, lee references/refining-skills.md. Para validar la estructura, ejecuta scripts/audit-skill.sh.

Invoca con: pide ai-skill-builder; los hosts pueden exponerlo como /ai-skill-builder, $ai-skill-builder, o a través de su selector de skills.

Requisitos P0

Cada skill que produce esta metodología cumple con todos los trece. Cítalos por ID en auditorías y revisiones.

1. SKILL-REQ001-descubrir-runtimes-destino. Identifica productos exactos, versiones, modos de invocación, raíces de instalación, límites de confianza y semántica del sistema de archivos antes de escribir.
2. SKILL-REQ002-separar-estándar-de-extensiones. Mantén la especificación de Skills de Agente, las extensiones del runtime y las convenciones del proyecto en columnas separadas. Nunca presentes un campo específico de Claude, Codex, Copilot, Gemini o framework como universal.
3. SKILL-REQ003-usar-núcleo-portátil-válido. Coloca un SKILL.md requerido en un directorio cuyo nombre coincida con su name portátil; incluye una description específica que diga qué hace el skill y cuándo usarlo. Usa campos opcionales estándar solo cuando sea necesario.
4. SKILL-REQ004-usar-regiones-xml-semánticas. Envuelve cada región operacional importante en etiquetas XML consistentes y descriptivas dentro del cuerpo de Markdown, como <purpose>, <requirements>, <workflow>, <examples>, y <output_contract>. Mantén el Markdown dentro de esas regiones y el código fuente literal en bloques de código delimitados. Esta regla metodológica obligatoria apunta a la separación de instrucciones de mayor calidad; no es un requisito del parser de Skills de Agente ni un límite de seguridad. scripts/audit-skill.sh falla en un cuerpo sin región, con una etiqueta desbalanceada o mal anidada, o con un encabezado ## fuera de cada región.
5. SKILL-REQ005-diseñar-divulgación-progresiva. Mantén la descripción de activación precisa y el flujo de trabajo principal conciso. Mueve los detalles realmente condicionales a referencias enfocadas y directamente vinculadas; mantén la automatización reutilizable en scripts y los materiales de salida en assets.
6. SKILL-REQ006-preservar-contexto-operacional. Cada referencia o script debe decir cuándo usarlo, qué entradas acepta, qué devuelve o cambia, y cómo se reporta el fallo. Evita cadenas de referencia profundas.
7. SKILL-REQ007-hacer-invocación-correcta. Prueba la activación automática y la invocación explícita. Cuando un runtime soporta parámetros, prueba entradas vacías, posicionales, nombradas, con comillas, Unicode, inválidas y grandes. No asumas que otro runtime implementa la misma sintaxis de sustitución.
8. SKILL-REQ008-minimizar-autoridad-de-herramientas. Trata los skills y los scripts incluidos como dependencias ejecutables. Solicita la menor autoridad necesaria, valida entradas, conserva los avisos de aprobación cuando sea práctico y nunca describas delimitadores de prompts como prevención de inyección de prompts.
9. SKILL-REQ009-validar-cada-entorno. Valida el descubrimiento, la carga, las referencias, los scripts, los argumentos, los enlaces simbólicos, la resolución de duplicados, las actualizaciones y la eliminación en cada entorno compatible. Pasar un parser no demuestra compatibilidad entre runtimes.
10. SKILL-REQ010-preservar-estado-de-usuario. La instalación y desinstalación deben ser dueñas de rutas generadas exactas, preservar ediciones manuales, soportar múltiples raíces de skills configuradas y eliminar solo enlaces o archivos propiedad del instalador.
11. SKILL-REQ011-medir-costo-de-contexto-y-runtime. Registra el tamaño de metadatos de descubrimiento, el tamaño de instrucciones cargadas, el costo de referencias condicionales, el tiempo/memoria/E/S del script y la carga duplicada. Trata los objetivos de líneas y tokens como heurísticas a menos que un runtime objetivo los haga normativos.
12. SKILL-REQ012-probar-hacia-adelante-con-tareas-reales. Usa prompts realistas positivos, negativos, ambiguos y adversariales. Verifica el resultado de la tarea, no meramente si el skill apareció en una lista.
13. SKILL-REQ013-separar-autoría-de-ejecución. Clasifica si la tarea es cambiar el skill, usar el skill para producir un artefacto o resultado, o evaluar el skill a partir de evidencia. Las entradas del runtime, las salidas generadas, los ejemplos y las observaciones de dogfood no se convierten en instrucciones del skill a menos que una decisión de autoría explícita las acepte y generalice.

Los nombres de las regiones siguen la tarea en lugar de una taxonomía universal: los flujos de trabajo usan <workflow>, los skills de referencia pueden usar <decision_guide>, los skills multimodo <routing>, los contratos de resultados estrictos <output_contract>, el material de referencia en línea <reference>, y los punteros a archivos y fuentes incluidos <resources>. Las etiquetas deben ser consistentes, descriptivas, balanceadas y no estar anidadas más profundamente de lo que requiere la tarea. La matriz estándar-versus-extensión, la auditoría de reclamos y el recibo de validación por host viven en references/portability-and-claim-audit.md.

Cómo Funciona

Metodología de cuatro fases de la guía de Anthropic. Cada fase tiene una Definición de Hecho: la condición que debe cumplirse antes de que comience la siguiente fase.

Fase	Actividad	Definición de Hecho
1: Planificación y Diseño	Definir hosts objetivo, casos de uso, categoría, criterios de éxito	Los criterios son medibles y la categoría está elegida
2: Implementación	Crear carpeta, escribir SKILL.md, añadir recursos	audit-skill.sh reporta cero fallos
3: Pruebas	Pruebas de activación, funcionales, rendimiento, compatibilidad, avance	Cada host nombrado pasa con un recibo de validación; línea base registrada
4: Distribución	Empaquetar, documentar, publicar	Instalación verificada desde una raíz limpia

La Fase 1 cubre los Pasos 1–2 a continuación; las Fases 2–4 corresponden a los Pasos 3–5.

Cuánto tiempo toma una fase depende de quién o qué la ejecuta, así que este skill no proporciona estimaciones de tiempo real y los skills que construyas tampoco deberían hacerlo.

---

Flujo de Trabajo de Creación de Skills

Paso 1: Descubrir Requisitos

Investiga el dominio primero — usa las herramientas web del host para verificar las mejores prácticas actuales antes de escribir instrucciones. Una guía desactualizada es peor que ninguna: un agente la sigue con confianza.

Conserva todas las fuentes: registra cada URL consultada con una nota de lo que confirmó. La guía sin fuente no se puede verificar ni actualizar.

Para estrategias de investigación, estándares de calidad de fuentes y el formato requerido de la sección Fuentes: references/research.md

1. Clasifica la solicitud: autoría (cambiar el skill), ejecución (usar el skill para producir un resultado) o evaluación (juzgar el skill a partir de evidencia). Nombra el artefacto y el límite de mutación antes de usar el contenido de la tarea como entrada de diseño (SKILL-REQ013).
2. Identifica el problema y los usuarios objetivo
3. Identifica cada host y versión objetivo, su raíz de descubrimiento, forma de invocación y comportamiento de recarga. Marca lo desconocido como desconocido en lugar de adivinar. Inspecciona las raíces de skills existentes y la guía del proyecto antes de crear un paquete paralelo.
4. Define 2-3 casos de uso concretos
5. Establece criterios de éxito medibles (tiempo ahorrado, errores reducidos, calidad mejorada)
6. Elige una categoría de skill:

Categoría	ENTRADA → SALIDA	Ejemplos
1: Creación de Documentos y Activos	Datos/especificaciones → documento, código, informe	Generador de pruebas de API, resumidor de notas de reuniones
2: Automatización de Flujos de Trabajo	Parámetros de tarea → proceso de múltiples pasos completado	Pipeline de despliegue, flujo de trabajo de revisión de código
3: Mejora de MCP	Salidas de herramientas MCP → orquestación más inteligente	Búsqueda inteligente de archivos, asistente de BigQuery

Para guía detallada de categorías: references/categories.md Para preguntas interactivas de descubrimiento: references/discovery.md

Paso 2: Diseñar Estructura

Diseña usando divulgación progresiva — 3 niveles de carga:

Nivel	Cuándo se carga	Longitud objetivo	Contenido
1: Metadatos	Siempre (~100 palabras)	nombre + descripción	Condiciones de activación
2: Cuerpo de SKILL.md	Cuando se activa el skill	menos de 5,000 palabras (idealmente menos de 2,000)	Flujo de trabajo principal + punteros
3: Archivos de references/	Según sea necesario	Ilimitado	Detalles profundos, esquemas, ejemplos

Para consejos de escritura de divulgación progresiva y métricas de éxito: references/best-practices.md

Paso 3: Implementar

Reglas críticas:

• ✅ El archivo DEBE llamarse SKILL.md (no README.md)
• ✅ El nombre de la carpeta DEBE estar en kebab-case — sin espacios, sin mayúsculas (my-skill no My Skill)
• ✅ El frontmatter YAML DEBE incluir name y description; pon una versión bajo metadata
• ✅ La description DEBE incluir frases de activación específicas — lo que los usuarios DICEN para activar el skill
• ✅ La description debe tener menos de 1024 caracteres (límite estricto — las descripciones más largas se truncan)
• ✅ Sin corchetes angulares XML (< o >) en ningún campo del frontmatter — una restricción del host de la guía de skills de Anthropic, no una regla YAML; el cuerpo no se ve afectado
• ✅ Cuerpo: cada sección importante está dentro de una región XML equilibrada y descriptiva en su propia línea (<purpose>, <requirements>, <workflow>, <examples>, <output_contract>), Markdown dentro, código fuente literal en bloques de código delimitados (SKILL-REQ004). El título H1 puede permanecer fuera.
• ❌ NO hay README.md dentro de la carpeta del skill — toda la documentación va en SKILL.md o references/ (Excepción: un README.md en la RAÍZ del repositorio de GitHub, fuera de la carpeta del skill, está bien para GitHub).
• ❌ NO hay espacios ni guiones bajos en los nombres de carpeta (my_skill → my-skill)

Frontmatter: campos requeridos:

---
name: your-skill-name          # solo kebab-case; sin espacios, mayúsculas ni guiones bajos
description: Qué hace. Úsalo cuando el usuario pida "frase específica", "otra frase".
             # DEBE incluir: qué hace + cuándo usarlo (condiciones de activación)
             # Menos de 1024 caracteres. Sin corchetes angulares XML.
             # NO empezar con "claude" o "anthropic" (espacios de nombres reservados).
---

Para cada campo opcional (license, compatibility, allowed-tools, metadata) con notas de portabilidad entre hosts: references/best-practices.md

El lenguaje de posicionamiento ("genera pruebas un 87% más rápido") pertenece al README del repositorio, nunca a description. Consulta references/best-practices.md.

Estructura de carpetas (ejemplo anotado de Claude Code independiente: references/best-practices.md, sección "Folder Structure Patterns"):

Directorio	¿Cargar en contexto?	Uso
references/	Sí, según sea necesario	Esquemas, documentación de API, políticas, guías de flujo de trabajo
references/examples/	Según sea necesario	Código funcional que los usuarios copian y adaptan
scripts/	No (ejecutar directamente)	Validadores, andamiadores, utilidades
assets/	No (usado en la salida)	Imágenes, fuentes, plantillas HTML que el skill pega en la salida

Nota: Los skills de plugins (en plugin-name/skills/) pueden colocar examples/ en el nivel superior — eso es convención de desarrollo de plugins. Para skills independientes de ~/.claude/skills/, pon los ejemplos dentro de references/.

Para andamiar un nuevo skill: bash scripts/scaffold-skill.sh my-skill-name (establece SKILLS_DIR para apuntar a la raíz de otro host) Para empezar desde una plantilla: copia references/examples/SKILL-template.md

Paso 4: Probar

Cinco enfoques de prueba (ejecutar en orden):

1. Pruebas de activación — verifica que el agente se active con frases esperadas y no con solicitudes no relacionadas
2. Pruebas funcionales — valida que el flujo de trabajo principal del skill produzca la salida correcta para entradas conocidas
3. Pruebas de rendimiento — mide la mejora sobre la línea base (tiempo ahorrado, reducción de errores, consistencia)
4. Pruebas de compatibilidad — verifica el descubrimiento, la invocación explícita, la carga de referencias, la ejecución de scripts y la resolución de duplicados/nombres en cada host y versión nombrados. Inicia una sesión limpia para cada host, ejecuta el validador propio del host donde exista (Codex incluye skill-creator/scripts/quick_validate.py), prueba las re-ejecuciones del instalador, múltiples raíces, objetivos de enlaces simbólicos, archivos de usuario modificados y desinstalación, y registra un recibo de validación por host (references/portability-and-claim-audit.md).
5. Pruebas de avance — prompts realistas positivos, negativos, ambiguos y adversariales; juzga el resultado de la tarea, no si el skill apareció en una lista, y verifica que no active en exceso tareas cercanas (SKILL-REQ012)

Depuración de problemas de activación:

Pregunta al agente: "¿Cuándo usarías el skill [nombre del skill]?"

El agente debería citar su descripción. Ajusta según lo que falte o sea demasiado vago.

Corregir activación insuficiente: Añade más frases de activación específicas y términos técnicos relevantes.

Corregir activación excesiva: Añade activadores negativos a la descripción:

description: Procesa documentos legales PDF para revisión de contratos. Úsalo para "revisar este contrato",
  "analizar documento legal", "extraer cláusulas contractuales". NO lo uses para visualización general de PDF,
  extracción de imágenes o documentos no legales (usa el skill doc-converter en su lugar).

Para la guía completa de diagnóstico y corrección que cubre los cuatro modos de fallo: references/troubleshooting.md

Para validar la estructura:

bash scripts/audit-skill.sh /path/to/TU-SKILL

…

[truncado para traducción]