Has estado usando Claude durante una semana y sigues escribiendo lo mismo cada vez. Cada vez que confirmas código, pegas las mismas tres reglas sobre el formato de confirmación. Cada vez que escribes un documento, vuelves a explicar tu estilo. Claude lo hace bien, pero lo olvida en cuanto termina el chat, y al día siguiente vuelves a escribirlo todo.
Un skill soluciona eso. Es una pequeña carpeta que escribes una vez y que le enseña a Claude un flujo de trabajo de forma permanente, para que lo aplique en cada sesión sin que tengas que pedírselo.
Así funciona, de un vistazo: un skill es una carpeta con un archivo dentro. Claude mantiene visible en todo momento un resumen de una línea, y solo carga las instrucciones completas cuando tu solicitud coincide. Ese es todo el mecanismo.
En esta guía construiremos un skill real desde cero: commit-messages, que escribe confirmaciones de git en tu formato exacto. Si tienes Claude instalado y nada más, puedes seguir cada paso.
Lo que obtendrás al final
En esencia, un skill es una carpeta con un archivo obligatorio, SKILL.md. Tres carpetas opcionales aparecen más adelante a medida que el skill crece:
1tu-nombre-de-skill/2├── SKILL.md # Obligatorio - el archivo principal del skill3├── scripts/ # Opcional - código ejecutable4├── references/ # Opcional - documentación5└── assets/ # Opcional - plantillas, etc.
El propio SKILL.md tiene dos partes: un encabezado corto que le indica a Claude cuándo usar el skill, y las instrucciones debajo que le indican qué hacer. La razón de esta división es importante. Claude lee el encabezado constantemente, por lo que siempre sabe que el skill existe, pero solo carga las instrucciones cuando tu solicitud coincide. Ten presente esa distinción, porque casi todo lo demás en esta guía se deriva de ella.
Crearlo
Los skills viven en una carpeta llamada .claude/skills dentro de tu directorio de inicio, que tanto Claude Code como la aplicación de escritorio leen. Está oculta y probablemente aún no existe, así que la forma más rápida de crearla, junto con la carpeta de tu skill, es un solo comando.
En Mac, abre Terminal y ejecuta:
1mkdir -p ~/.claude/skills/tu-nombre-de-skill
En Windows, abre PowerShell y ejecuta:
1New-Item -ItemType Directory -Force -Path "$HOME\.claude\skills\tu-nombre-de-skill"
El nombre de la carpeta no es decorativo. Claude lo usa como identificador del skill, y hay una regla de formato que causa más problemas que cualquier otra:
- Usa kebab-case: notion-project-setup ✔
- Sin espacios: Notion Project Setup ✖
- Sin guiones bajos: notion_project_setup ✖
- Sin mayúsculas: NotionProjectSetup ✖
Dentro de esa carpeta, crea un archivo llamado exactamente SKILL.md y ábrelo en cualquier editor de texto. Todo lo que sigue va dentro de ese archivo.
Diseñarlo antes de escribirlo
Los skills que funcionan comienzan con dos decisiones, tomadas antes de escribir una sola línea del archivo. Ambas parecen saltables y ninguna lo es.
Primero, decide exactamente cuándo debería activarse el skill. Anota dos o tres situaciones reales en las palabras que un usuario escribiría realmente:
- "confirmar estos cambios"
- "escribe un mensaje de confirmación para este diff"
- "agregar y confirmar"
Esto no es trabajo perdido. Estas frases se convierten en la materia prima para tu descripción y tus pruebas posteriores, y un skill diseñado sin ellas tiende a ser vago justo en la forma que impide que se active.
Segundo, decide cómo sabrás que funciona. El criterio más importante por encima de todos los demás es si el skill se carga por sí solo, sin que lo nombres. Si tienes que invocarlo manualmente cada vez, el skill técnicamente se ejecuta pero ha fallado en su trabajo real. Vale la pena observar también si completa la tarea sin que tengas que corregirlo a mitad de camino, y si te da el mismo tipo de resultado en sesiones distintas.
La descripción es lo que lo hace o lo rompe
De todo lo que hay en el archivo, la descripción en el encabezado es lo que más trabajo hace, porque es la única parte que Claude lee al decidir si cargar el skill o no. Tus instrucciones podrían ser impecables y no importaría, ya que Claude nunca llega a ellas si la descripción no coincide. Aquí es donde fallan la mayoría de los skills que "no funcionan".
Una descripción sólida responde dos preguntas en una sola frase: qué hace el skill y cuándo debería Claude recurrir a él. Esa segunda mitad es la que la gente omite.
Aquí está la diferencia:
1# débil - dice qué es, no le da a Claude nada con lo que coincidir con una solicitud2description: Ayuda con confirmaciones de git.34# fuerte - nombra los momentos en los que debería activarse5description: Escribe mensajes de confirmación de git en formato Conventional Commits. Úsalo cuando el usuario pida confirmar cambios, escribir un mensaje de confirmación o agregar y confirmar archivos.
La versión débil le dice a Claude que el skill existe, pero nunca lo conecta con nada que puedas decir. La versión fuerte nombra las frases reales, así que cuando escribes "confirma estos cambios", Claude tiene algo con lo que coincidir. Nombra las palabras que un usuario usaría realmente, mantén todo por debajo de 1024 caracteres y no pongas < o > dentro.
Cuando un skill no se activa, la solución casi siempre está aquí. Añade las frases que realmente usas. Si dices "guarda mi trabajo" pero la descripción solo menciona "confirmar", Claude no tiene forma de vincular las dos. Y si ocurre lo contrario y el skill se activa cuando no debería, reduce la descripción o añade un desencadenante negativo:
1description: Escribe mensajes de confirmación de git en formato Conventional Commits. Úsalo al confirmar cambios. No usarlo para escribir comentarios de código o documentación.
Hay una forma rápida de comprobar tu trabajo antes de confiar en él. Pregúntale directamente a Claude:
"¿Cuándo usarías el skill commit-messages?"
Claude leerá tu descripción con sus propias palabras. Si eso no coincide con cuándo quieres que el skill se active, has encontrado tu problema, y está en la descripción, no en las instrucciones de abajo.
Escribe instrucciones que Claude realmente siga
Debajo del encabezado viene el cuerpo, en Markdown plano. Aquí es donde vive tu flujo de trabajo real, y dos hábitos separan las instrucciones que Claude sigue de las que ignora silenciosamente.
El primero es ser específico. Claude actúa sobre instrucciones concretas y pasa por alto las vagas, así que cuanto más exacto seas, más fiablemente se comportará:
1# Mal2Valida la confirmación antes de finalizar.34# Bien5Ejecuta `python scripts/validate.py "<mensaje>"`.6Si falla, corrige esto:7- Tipo no válido: usa feat, fix, docs, refactor, test, chore8- Resumen de más de 60 caracteres: acórtalo
El segundo es el orden. Claude pondera lo que lee primero, así que una regla enterrada al final de un archivo largo es una regla que se pasa por alto. Pon todo lo que no debe romperse al principio, bajo un encabezado que lo señale:
1## Importante2- Línea de resumen siempre por debajo de 60 caracteres3- Solo tiempo presente: "add", no "added"
También hay un límite en lo que el lenguaje puede garantizar. Las instrucciones se interpretan, lo que significa que Claude las sigue bien, pero no idénticamente cada vez. Cuando una verificación realmente tiene que pasar en cada ejecución, no la describas en prosa, pásala a un script y haz que las instrucciones lo ejecuten. El código hace lo mismo cada vez; una frase no. (Para eso está la carpeta scripts/, que se cubre a continuación.)
Una estructura que se sostiene en la mayoría de los skills se ve así:
1# Nombre del Skill23## Importante4Reglas críticas que no deben pasarse por alto.56## Instrucciones7Paso a paso, específicas y procesables.89## Ejemplos10Entrada y salida concretas. Claude copia los ejemplos de forma más fiable que sigue las reglas.
Mantén el archivo ligero. En el momento en que empiece a crecer más allá de sus instrucciones principales, es el momento de sacar el detalle extra, que es exactamente para lo que sirven las carpetas opcionales.
Scripts, referencias, assets
Todo lo anterior produce un skill que le da instrucciones a Claude. Las tres carpetas opcionales lo convierten en un skill que le da herramientas a Claude, y aquí es donde un skill hace cosas que un prompt simple no puede.
scripts/ contiene código que Claude ejecuta, para cualquier cosa que deba ser exacta. En lugar de confiar en que Claude evalúe visualmente si una confirmación tiene el formato correcto, le pasas un script que lo verifica:
1# scripts/validate.py2import sys3msg = sys.argv[1]4types = ("feat", "fix", "docs", "refactor", "test", "chore")56if msg.split(":")[0] not in types:7 print(f"Tipo no válido. Usa: {', '.join(types)}")8elif len(msg.split("\n")[0]) > 60:9 print("Resumen demasiado largo (más de 60 caracteres)")10else:11 print("OK")
Luego le dices a Claude que lo use en SKILL.md:
1Antes de finalizar, ejecuta `python scripts/validate.py "<mensaje>"`2y corrige cualquier cosa que marque.
Ahora la regla de formato se aplica mediante código que se ejecuta siempre de la misma manera, en lugar de depender de que Claude recuerde verificarlo.
references/ contiene documentación que se carga solo cuando es necesario. Supón que tus convenciones de confirmación ocupan dos páginas de ámbitos, pies de página y casos extremos. Pon todo eso en SKILL.md y se carga en cada confirmación, incluso en una de una línea. En su lugar, muévelo a un archivo de referencia:
1tu-nombre-de-skill/2├── SKILL.md3└── references/4 └── conventions.md
Y señálalo desde el archivo principal:
1Para la lista completa de convenciones, consulta references/conventions.md
Claude abre ese archivo solo cuando la tarea lo requiere. Esta es toda la razón por la que los skills son económicos de ejecutar: el detalle pesado reside en el disco hasta que realmente es relevante, en lugar de viajar en el contexto cada vez.
assets/ contiene archivos que el skill usa en su salida en lugar de leer para orientarse, como una plantilla, un archivo de configuración o un logotipo. Un skill de confirmaciones no necesita ninguno, pero un skill que genera informes podría mantener aquí un template.md y rellenarlo cada vez, para que cada informe tenga la misma estructura.
En conjunto, estas tres carpetas son la diferencia entre un skill que le dice a Claude cómo trabajas y uno que le da a Claude las herramientas exactas para hacer el trabajo a tu manera.
Lo único que hay que recordar
Un skill no le enseña a Claude una nueva habilidad. Ya sabe cómo escribir una confirmación. Lo que hace el skill es que realice el trabajo a tu manera, cada vez, sin que tengas que explicarlo de nuevo.
Y cuando un skill no funciona, la causa casi nunca son las instrucciones en las que trabajaste. Es la descripción. Claude decide si cargar el skill a partir de esa única línea, antes de leer el trabajo que hay debajo. Acierta con la descripción y todo lo que hay debajo finalmente se usará.
Si esto te fue útil, dirígete a mi perfil y sígueme. Escribo sobre tecnología, IA y sistemas que realmente funcionan.
