Cómo se crea una Skill: De la idea al paquete

Una Skill no comienza con una carpeta o un archivo YAML.

Comienza con un momento de reconocimiento: notas que le has pedido a Claude que haga el mismo tipo de tarea, de la misma manera, más de una vez.

Esa tarea repetida es la materia prima. El empaquetado es solo el último paso, no el primero.

Esta página recorre el camino completo que viaja una Skill, desde notar la repetición hasta una carpeta SKILL.md funcional que Claude puede descubrir y cargar por sí misma.

Resumen

• Una Skill es la forma empaquetada de una tarea que ya realizas de forma repetida y consistente, no una nueva capacidad inventada desde cero.
• Por qué es importante: Comprender el camino de la idea al paquete evita que empieces por el extremo equivocado, escribiendo instrucciones elaboradas antes de saber si la tarea es realmente repetible.
• Conceptos Clave: tarea repetida, SKILL.md, frontmatter, descripción, cuerpo paso a paso, herramientas permitidas, recursos incluidos.
• Cuándo usar: Útil cuando decides si algo tiene "forma de Skill" en absoluto, y cuando quieres un mapa mental de las etapas antes de empezar a escribir.
• Limitaciones / Compensaciones: Una Skill solo ayuda si la tarea subyacente es genuinamente repetible y descriptible; forzar una tarea única en un paquete de Skill desperdicia esfuerzo sin beneficio futuro.
• Temas Relacionados: Descripciones de Skills y activación, estructura de instrucciones paso a paso, alcance de herramientas permitidas, archivos de referencia incluidos.

Fundamentos

Cada Skill comienza su vida como una tarea repetida: algo que le has pedido a Claude que haga más de una vez, de una forma más o menos igual, con pasos más o menos iguales.

Quizás sea redactar una actualización de estado semanal a partir de un conjunto de notas. Quizás sea revisar una solicitud de extracción (pull request) contra una lista de verificación fija. Quizás sea convertir una transcripción de cliente en un resumen estructurado.

El hilo común es la repetición con una forma consistente. Una tarea que hiciste una vez y nunca volverás a hacer no es un buen candidato. Una tarea que haces de manera diferente cada vez, sin un patrón estable, tampoco es un buen candidato.

Una vez que has identificado ese patrón, el destino es un paquete de Skill: una carpeta que contiene un archivo obligatorio, SKILL.md, y opcionalmente un puñado de archivos de soporte junto a él.

mi-skill/
  SKILL.md          # obligatorio: frontmatter + instrucciones
  referencia.md       # opcional: detalle adicional que Claude carga solo si es necesario
  script-ayuda.py    # opcional: un script al que las instrucciones pueden apuntar

El propio SKILL.md tiene dos partes: un pequeño bloque de frontmatter YAML en la parte superior y un cuerpo de instrucciones debajo.

---
name: weekly-status-update
description: >-
  Drafts a weekly status update from raw notes. Use when the user asks for a
  status update, weekly summary, or standup recap based on notes or bullet points.
---

El frontmatter son metadatos que Claude lee para decidir si esta Skill es relevante para la tarea que tiene delante. El cuerpo es lo que Claude realmente sigue una vez que ha decidido usar la Skill.

Esa separación es la idea central a tener en cuenta para todo lo que sigue: el frontmatter decide si la Skill se carga, y el cuerpo decide qué sucede una vez que lo hace.

Mecánicas e Interacciones

El camino de la idea al paquete pasa por un pequeño número de etapas, cada una construyendo sobre la anterior.

Etapa 1 - Notar el patrón. Antes de escribir nada, confirma que la tarea realmente se repite con una forma consistente. Si no puedes describir los pasos que sigues hoy en una o dos frases, es demasiado pronto para empaquetarla.

Etapa 2 - Escribe las instrucciones primero en lenguaje claro. Describe lo que realmente haces, en orden, de la manera que se lo explicarías a un nuevo compañero de equipo. No te preocupes por el frontmatter o la estructura del archivo todavía. Consigue los pasos correctos antes de conseguir el empaquetado correcto.

Etapa 3 - Redacta la descripción. Esta es la pieza más importante de todo el paquete. El campo description es lo que Claude compara con una nueva tarea para decidir si esta Skill se aplica. Debe indicar tanto lo que hace la Skill como cuándo debe activarse, en un lenguaje lo suficientemente concreto como para que una tarea cercana no coincida accidentalmente.

Etapa 4 - Convierte los pasos en lenguaje claro en instrucciones numeradas. La prosa vaga ("manejar el formato apropiadamente") se reescribe como un paso específico y ordenado ("aplicar la guía de estilo de la casa en el paso 3, luego volver a verificar los niveles de encabezado"). Los pasos numerados son lo que permite a Claude ejecutar de la misma manera cada vez.

Etapa 5 - Decide qué herramientas necesita realmente la Skill. Algunas Skills solo necesitan leer y razonar. Otras necesitan escribir archivos, ejecutar comandos o llamar a herramientas específicas. Aquí es donde entra allowed-tools, definiendo exactamente qué puede invocar la Skill, incluso si se activa en un contexto que no anticipaste.

Etapa 6 - Añade recursos incluidos, solo si se ganan su lugar. Si las instrucciones se refieren constantemente a una tabla de referencia, una plantilla o un script de ayuda, ese contenido se traslada a su propio archivo dentro de la carpeta de la Skill, y el cuerpo lo señala por nombre en lugar de incluir todo en línea.

Etapa 7 - Prueba el disparador (trigger), no solo la salida. Ejecuta una tarea que esperarías que activara la Skill y una que esperarías que no, y confirma que Claude elige la correcta. Una Skill que produce un buen resultado es solo la mitad del trabajo si nunca se descubre en primer lugar.

Idea (tarea repetida)
  -> pasos en lenguaje claro
  -> descripción redactada (qué + cuándo)
  -> los pasos se convierten en instrucciones numeradas
  -> herramientas permitidas definidas (si es necesario)
  -> archivos de referencia / scripts incluidos (si es necesario)
  -> probado para precisión del disparador
  -> carpeta SKILL.md empaquetada

Observa que el empaquetado - el frontmatter, la carpeta, la disposición de los archivos - aparece tarde en esta secuencia, no primero. Las Skills que salen mal a menudo salen mal porque alguien escribió el bloque YAML antes de haber definido realmente los pasos.

Consideraciones Avanzadas y Aplicaciones

No todas las tareas repetidas deben convertirse en su propia Skill. Algunas pertenecen a una sección dentro de una Skill relacionada más amplia en lugar de un nuevo paquete propio, especialmente si comparten la mayoría de sus pasos con algo que ya existe.

Una prueba útil: si dos tareas se activaran con descripciones casi idénticas, probablemente pertenezcan a una sola Skill con una ramificación en las instrucciones, no a dos Skills compitiendo por el mismo disparador.

A medida que la biblioteca de Skills de un equipo crece, el camino de la idea al paquete también debe tener en cuenta la descubribilidad entre muchas Skills, no solo la corrección de una. Una descripción que habría estado bien de forma aislada puede volverse ambigua una vez que cinco Skills más se sientan a su lado con una redacción similar.

La etapa de empaquetado también tiene un momento natural para la revisión: una vez que tienes un SKILL.md completo, lee la descripción y los tres primeros pasos como si fueras Claude viéndolos por primera vez, sin recordar haberlos escrito. Si el "cuándo usarlo" no es obvio solo por la descripción, esa es la etapa a revisar, no la última para arreglar.

Conceptos Erróneos Comunes

• "Debería escribir primero el archivo SKILL.md y luego averiguar los pasos." - Hacer esto al revés tiende a producir instrucciones vagas y genéricas. Domina los pasos en lenguaje claro antes de redactar el frontmatter.
• "Cualquier tarea que hago más de una vez vale la pena empaquetarla." - Una tarea necesita una forma consistente y descriptible, no solo repetición. Dos tareas que se repiten pero varían enormemente cada vez no se comprimen bien en pasos fijos.
• "El nombre de la Skill es lo que la hace descubrible." - El campo description tiene casi todo el peso de la descubribilidad, no el nombre. Un nombre preciso con una descripción vaga todavía no se activará de manera fiable.
• "Los archivos incluidos hacen que una Skill sea más completa, así que cuanto más, mejor." - Los archivos de referencia y scripts adicionales solo deben existir porque las instrucciones realmente los necesitan. El contenido incluido no utilizado solo añade peso de mantenimiento.
• "Empaquetar es la parte difícil." - Escribir el frontmatter y la estructura de la carpeta es mecánico. Conseguir la descripción y el orden de los pasos correctos es donde pertenece la mayor parte del esfuerzo real.

Preguntas Frecuentes

Relacionados

• Fundamentos de Diseño y Empaquetado de Skills - escribe tu primer SKILL.md de principio a fin.
• Escribir una Descripción de Skill Efectiva Que Claude Disparará - una mirada más profunda a la Etapa 3.
• Estructurar Instrucciones Paso a Paso Que Claude Puede Seguir Fiablemente - una mirada más profunda a la Etapa 4.
• ¿Qué Son las Skills de Agente? - el concepto más amplio hacia el que se dirige esta página.
• Anatomía de un Archivo SKILL.md - una mirada campo por campo al archivo hacia el que esta página se dirige.

Versiones de Stack: Escrito contra la línea de modelos de Claude actual a partir de ~junio de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (el predeterminado) y Claude Haiku 4.5. Los nombres de los modelos, los precios y las características del producto cambian rápidamente; verifica los detalles actuales en platform.claude.com/docs antes de confiar en ellos.