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
- Idea Central: 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 apuntarEl 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 empaquetadaObserva 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.
| Enfoque | Fortaleza | Debilidad | Mejor Ajuste |
|---|---|---|---|
| Una Skill por tarea estrecha | Las descripciones se mantienen precisas y fáciles de activar correctamente | Puede expandirse a muchas Skills pequeñas y superpuestas | Equipos pequeños, un puñado de tareas bien separadas |
| Una Skill con pasos ramificados para tareas relacionadas | Menos paquetes que mantener y descubrir | Las instrucciones se alargan y necesitan ramificación interna clara | Tareas relacionadas que comparten la mayoría de sus pasos |
| Archivos de referencia incluidos divididos desde el principio | Mantiene el cuerpo principal de SKILL.md corto y escaneable | Añade archivos para rastrear y mantener sincronizados | Tareas con material de referencia genuinamente grande (guías de estilo, esquemas, plantillas) |
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
descriptiontiene 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
¿Por dónde debo empezar realmente al construir una Skill?
- Empieza por confirmar que la tarea se repite con una forma consistente, luego escribe los pasos en lenguaje claro antes de tocar el frontmatter.
¿Qué es lo mínimo que necesita un paquete de Skill para existir?
- Un único archivo
SKILL.mdcon unnameydescriptionen su frontmatter, más un cuerpo de instrucciones. Los archivos incluidos yallowed-toolsson adiciones opcionales.
¿Por qué la descripción importa más que las instrucciones en sí?
Claude compara las nuevas tareas con la descripción de una Skill para decidir si la carga. Si la descripción no se activa, las instrucciones nunca se leen, sin importar lo buenas que sean.
¿Debo escribir la descripción antes o después de las instrucciones paso a paso?
- Cualquiera de los dos órdenes puede funcionar, pero muchos autores encuentran más fácil escribir primero los pasos en lenguaje claro, ya que una imagen clara de lo que realmente hace la Skill hace que la descripción sea más fácil de indicar con precisión.
¿Cómo sé si una tarea es lo suficientemente repetible como para empaquetarla?
- Si puedes describir los pasos que sigues hoy en una o dos frases, y esos pasos se mantienen en varias instancias pasadas de la tarea, es un buen candidato.
¿Qué sucede si salto directamente a escribir la estructura de carpetas de SKILL.md?
Corres el riesgo de producir un paquete técnicamente válido con instrucciones vagas o genéricas, ya que la carpeta y el frontmatter no te obligan a pensar en los pasos reales.
¿Necesito archivos de referencia o scripts incluidos para cada Skill?
No. Muchas Skills son un único archivo SKILL.md sin recursos incluidos en absoluto. Añade archivos adicionales solo cuando las instrucciones necesiten realmente apuntar a algo demasiado grande para incluir en línea.
¿Cuándo deberían dos tareas similares convertirse en una sola Skill en lugar de dos?
- Cuando sus descripciones serían casi indistinguibles, o cuando comparten la mayoría de sus pasos, agruparlas en una sola Skill con una ramificación en las instrucciones suele ser mejor que mantener dos paquetes superpuestos.
¿Qué significa "probar el disparador" y por qué es un paso separado de probar la salida?
Significa ejecutar una tarea que esperarías que activara la Skill y otra que no, y luego confirmar que Claude toma la decisión correcta en ambas direcciones; no solo comprobar que la Skill produce un buen resultado una vez que ya ha sido invocada.
¿Es `allowed-tools` obligatorio para cada Skill?
- No. Es opcional, y solo útil cuando quieres limitar explícitamente qué herramientas puede invocar una Skill, incluso si se activa en un contexto inesperado.
¿Cuál es la razón más común por la que una Skill empaquetada todavía no se utiliza?
La descripción es demasiado vaga o demasiado amplia, por lo que Claude o no reconoce la tarea coincidente o coincide con la incorrecta. Casi siempre es un problema de descripción, no un problema de instrucciones.
¿Puedo revisar una Skill después de que esté empaquetada, o necesito empezar de nuevo?
- Puedes revisarla libremente. Las etapas descritas aquí -aclarar pasos, ajustar la descripción, definir herramientas, añadir recursos- son cosas que puedes revisitar en cualquier momento, no una configuración única.
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.