Has usado 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 tus confirmaciones. Cada vez que escribes un documento, vuelves a explicar tu estilo. Claude lo hace bien, pero lo olvida en cuanto el chat termina, y mañana vuelves a escribirlo todo.
Una 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í es como funciona, de un vistazo: una skill es una carpeta con un archivo dentro. Claude mantiene visible un resumen de una línea en todo momento, y carga las instrucciones completas solo cuando tu solicitud coincide. Ese es todo el mecanismo.
En esta guía creamos una skill real desde cero: commit-messages, que escribe commits 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, una skill es una carpeta con un archivo obligatorio, SKILL.md. Tres carpetas opcionales vienen después a medida que la skill crece:
1tu-nombre-de-skill/2├── SKILL.md # Obligatorio - el archivo principal de la skill3├── scripts/ # Opcional - código ejecutable4├── references/ # Opcional - documentación5└── assets/ # Opcional - plantillas, etc.
SKILL.md tiene dos partes: un encabezado corto que le dice a Claude cuándo usar la skill, y las instrucciones debajo que le dicen a Claude qué hacer. La razón de esta división es importante. Claude lee el encabezado constantemente, por lo que siempre sabe que la 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.
Crearla
Las skills viven en una carpeta llamada .claude/skills dentro de tu directorio de usuario, 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/your-skill-name
En Windows, abre PowerShell y ejecuta:
1New-Item -ItemType Directory -Force -Path "$HOME\.claude\skills\your-skill-name"
El nombre de la carpeta no es solo estético. Claude lo usa como identificador de la 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 es lo que va en ese archivo.
Diseñala antes de escribirla
Las skills que funcionan comienzan con dos decisiones, tomadas antes de escribir una línea del archivo. Ambas parecen saltables y ninguna lo es.
Primero, decide exactamente cuándo debería activarse la skill. Anota dos o tres situaciones reales en las palabras que un usuario realmente escribiría:
- "confirmar estos cambios"
- "escribir un mensaje de commit para este diff"
- "hacer stage y confirmar"
Esto no es trabajo innecesario. Estas frases se convierten en el material base para tu descripción y tus pruebas más adelante, y una skill diseñada sin ellas tiende a ser vaga justo en la forma que impide que se active.
Segundo, decide cómo sabrás que funciona. El criterio que más importa por encima de todos es si la skill se carga por sí sola, sin que la nombres. Si tienes que invocarla manualmente cada vez, la skill técnicamente se ejecuta pero ha fallado en su trabajo real. Vale la pena observar también: si termina la tarea sin que la corrijas a mitad de camino, y si te da el mismo tipo de resultado en sesiones separadas.
La descripción es lo que la hace o la 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 la 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 las skills que "no funcionan".
Una buena descripción responde dos preguntas en una sola frase: qué hace la skill y cuándo debería Claude recurrir a ella. Esa segunda mitad es la que la gente omite.
Aquí está la diferencia:
1# débil - dice qué es, pero no le da a Claude nada con qué coincidir una solicitud2description: Ayuda con commits de git.34# fuerte - nombra los momentos en los que debería activarse5description: Escribe mensajes de commit de git en formato Conventional Commits. Úsala cuando el usuario pida confirmar cambios, escribir un mensaje de commit, o hacer stage y confirmar archivos.
La versión débil le dice a Claude que la skill existe, pero nunca la conecta con nada que puedas decir. La versión fuerte nombra las frases reales, así que cuando escribes "confirmar estos cambios", Claude tiene algo con qué coincidir. Nombra las palabras que un usuario realmente usaría, mantén todo por debajo de 1024 caracteres y no pongas < o > dentro.
Cuando una skill no se activa, la solución casi siempre está aquí. Añade las frases que realmente usas. Si dices "guardar mi trabajo" pero la descripción solo menciona "commit", Claude no tiene forma de vincularlos. Y si ocurre lo contrario y la skill se activa cuando no debería, reduce la descripción o añade un disparador negativo:
1description: Escribe mensajes de commit de git en formato Conventional Commits. Úsala al confirmar cambios. No la uses para escribir comentarios de código o documentación.
Hay una forma rápida de verificar tu trabajo antes de confiar en él. Pregúntale directamente a Claude:
"¿Cuándo usarías la skill commit-messages?"
Claude te leerá tu descripción en sus propias palabras. Si eso no coincide con cuándo realmente quieres que la 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 aquellas que pasa por alto 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 confiablemente se comportará:
1# Mal2Valida el commit antes de finalizar.34# Bien5Ejecuta `python scripts/validate.py "<mensaje>"`.6Si falla, corrige esto:7- Tipo invá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 omite. Pon cualquier cosa que no deba romperse al principio, bajo un encabezado que lo señale:
1## Importante2- Línea de resumen de menos de 60 caracteres, siempre3- 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 de manera idéntica cada vez. Cuando una verificación realmente tiene que pasar en cada ejecución, no la describas en prosa, muévela 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 las skills se ve así:
1# Nombre de la Skill23## Importante4Reglas críticas que no deben pasarse por alto.56## Instrucciones7Paso a paso, específicas y accionables.89## Ejemplos10Entrada y salida concretas. Claude copia los ejemplos de manera más confiable 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 hasta ahora produce una skill que le da instrucciones a Claude. Las tres carpetas opcionales la convierten en una skill que le da herramientas a Claude, y aquí es donde una 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 un commit 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 invá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 igual cada vez, en lugar de depender de que Claude recuerde verificarlo.
references/ contiene documentación que se carga solo cuando es necesario. Digamos que tus convenciones de commit ocupan dos páginas de ámbitos, pies de página y casos extremos. Pon todo eso en SKILL.md y se cargará en cada commit, incluso en uno 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 la razón principal por la que las skills siguen siendo económicas de ejecutar: el detalle pesado permanece en el disco hasta que realmente es relevante, en lugar de viajar en el contexto cada vez.
assets/ contiene archivos que la skill usa en su salida en lugar de leer para obtener orientación, como una plantilla, un archivo de configuración o un logotipo. Una skill de commits no necesita ninguno, pero una skill que genera informes podría mantener un template.md aquí y completarlo cada vez, para que cada informe tenga la misma estructura.
En conjunto, estas tres carpetas son la diferencia entre una skill que le dice a Claude cómo trabajas y una que le entrega a Claude las herramientas exactas para hacer el trabajo a tu manera.
Lo único que debes recordar
Una skill no le enseña a Claude una nueva capacidad. Ya sabe cómo escribir un commit. Lo que hace la skill es que haga el trabajo a tu manera, cada vez, sin que tengas que repetirlo.
Y cuando una skill no funciona, la causa casi nunca son las instrucciones en las que trabajaste. Es la descripción. Claude decide si cargar la 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 está debajo finalmente se usará.
Si te fue útil, dirígete a mi perfil y sígueme. Escribo sobre tecnología, IA y sistemas que realmente funcionan.
