Claude Skills es un sistema que consiste en escribir en un solo archivo SKILL.md los pasos que quieres que la IA recuerde. AInformation ejecuta todos los días con Claude Code 48 sistemas programados y tiene 295 skills. En esta ocasión, creamos un skill de prueba y probamos tanto su lectura como su forma de distribuirlo en Claude Code 2.1.316 y en Antigravity.
Para crear un skill de Claude Skills solo hay que colocar un archivo SKILL.md dentro de una carpeta con el nombre del skill. El 31 de octubre de 2026, AInformation escribió en 19 líneas un skill de prueba que genera un informe semanal a partir de los informes diarios. En Claude Code 2.1.316, el skill se invocó automáticamente las tres veces, justo después de colocarlo. Una solicitud que sin el skill tardaba de 34.7 a 39.3 segundos pasó a generar el mismo tipo de informe semanal en un tiempo de 13.7 a 16.4 segundos.
AInformation ejecuta normalmente 48 sistemas programados creados con Claude Code, todos los días. Las tareas con pasos definidos se convierten en skills, y al 31 de octubre de 2026 había 295. En este artículo mostramos, con el skill de prueba real y capturas de pantalla, cómo escribir un SKILL.md, dónde colocarlo y cómo distribuirlo, basándonos en lo que aprendimos usándolos. La instalación de Claude Code en sí está explicada en nuestro artículo sobre cómo usar Claude Code.
- La forma mínima de un SKILL.md (19 líneas) y los pasos desde que se coloca hasta que se invoca
- Al colocar el skill, la respuesta a la misma solicitud pasó de 34.7–39.3 segundos a 13.7–16.4 segundos, y las tres veces tuvo el mismo formato
- El mismo SKILL.md también se leyó las tres veces en .agents/skills de Antigravity
- Se probaron 8 formas de escritura que no cumplen con la especificación oficial. Claude Code las invocó todas, mientras que Antigravity no leyó una de ellas
- De los 295 skills de AInformation, solo 18 tenían su descripción incluida en el listado
- Se pudo distribuir desde un solo repositorio tanto a Claude Code como a Antigravity mediante un plugin
¿Qué es Claude Skills? Un manual de instrucciones que solo se lee cuando se necesita
Claude Skills (Agent Skills) reúne en una sola carpeta los pasos y reglas que quieres que la IA recuerde. El elemento central es un archivo llamado SKILL.md. En la parte superior se escribe el nombre y la descripción, y debajo, los pasos a seguir. Los programas o ejemplos que se usan dentro de esos pasos también se pueden guardar en la misma carpeta.
Lo importante es el orden de lectura. Normalmente, la IA solo tiene en un listado el nombre y la descripción de todos los skills. Solo cuando la solicitud coincide con la descripción se abre el contenido del SKILL.md, y si es necesario, se ejecutan los programas de scripts. El contenido no se lee de forma habitual, así que aunque escribas pasos largos, no representa una carga en cada uso.
Aquí está la diferencia con CLAUDE.md. CLAUDE.md se lee por completo cada vez, así que es el lugar donde escribir las reglas que siempre quieres que se respeten. Los pasos de una tarea definida, en cambio, se convierten en skill y solo se leen cuando corresponde a esa tarea. Las herramientas que conectan con servicios externos o bases de datos se agregan mediante otro sistema llamado MCP, así que consulta nuestro artículo sobre cómo usar MCP.
Esta estructura no es exclusiva de Claude Code. Existe una especificación pública llamada Agent Skills, y Antigravity de Google también lee el mismo SKILL.md. En esta ocasión también comprobamos si “el mismo archivo funciona en otra aplicación”.
La forma mínima de un SKILL.md (el skill de prueba escrito por AInformation)
A continuación está el texto completo del SKILL.md que escribimos esta vez. Tiene 19 líneas, y en la parte superior solo incluimos name y description, que la especificación exige como obligatorios. La parte delimitada por — es la configuración inicial (frontmatter), y debajo hay pasos escritos en Markdown normal.
---
name: shuho-matome
description: Crea un informe semanal a partir de las notas de los informes diarios (archivos md en la carpeta memo). Se usa cuando se solicita un 'informe semanal', un 'resumen de esta semana' o una 'revisión de la semana'.
---
# Cómo crear el informe semanal
1. Ejecutar scripts/jikan.py (en la misma carpeta que este SKILL.md) pasándole la carpeta de notas. Usar la tabla que genera para los tiempos por categoría, sin sumar manualmente.
2. Escribir con el siguiente formato.
## Informe semanal (período)
### Lo hecho esta semana
- Hasta 3 elementos destacados de las notas
### Desglose de tiempo
(Pegar directamente la tabla de jikan.py)
### Lo que se hará la próxima semana
- Recopilar de las líneas 'Nota:' de las notas
En la última línea escribir '(Creado con el formato de informe semanal v1)'.En description se debe escribir tanto qué hace el skill como con qué palabras se espera que se solicite su uso. La IA decide si invocarlo o no basándose en esta sola línea, así que el truco está en incluir las palabras que realmente usaría la persona que lo lee. En este caso incluimos tres: “informe semanal”, “resumen de esta semana” y “revisión de la semana”.
En los pasos no se le pide a la IA que haga las sumas, sino que se las delega a scripts/jikan.py. Esto es porque contar el tiempo por categoría con un programa da siempre el mismo resultado. La estructura de la carpeta es la siguiente.
shuho-matome/
├── SKILL.md (19 líneas: descripción y pasos)
└── scripts/
└── jikan.py (20 líneas: suma el tiempo por categoría)jikan.py lee las líneas del informe diario con el formato “- 09:00-10:30 contenido (categoría)” y en solo 20 líneas genera una tabla con el tiempo por categoría. Con los 5 días del informe diario de prueba, el total es de 40 horas 00 minutos.
#!/usr/bin/env python3
"""Lee las notas de los informes diarios (- HH:MM-HH:MM contenido (categoría)) y genera una tabla con el tiempo por categoría.
Uso: python3 jikan.py <carpeta de notas>"""
import re, sys, pathlib
d = pathlib.Path(sys.argv[1] if len(sys.argv) > 1 else "memo")
tot, days = {}, []
for f in sorted(d.glob("*.md")):
days.append(f.stem)
for m in re.finditer(r"- (\d\d):(\d\d)-(\d\d):(\d\d) .*\((.+?)\)", f.read_text(encoding="utf-8")):
h1, m1, h2, m2, k = m.groups()
tot[k] = tot.get(k, 0) + (int(h2) * 60 + int(m2)) - (int(h1) * 60 + int(m1))
if not days:
sys.exit(f"No se encontraron notas: {d}")
print(f"Período: {days[0]}-{days[-1]} ({len(days)} días)")
print("| Categoría | Tiempo |")
print("|---|---|")
for k, v in sorted(tot.items(), key=lambda x: -x[1]):
print(f"| {k} | {v // 60} horas {v % 60:02d} minutos |")
s = sum(tot.values())
print(f"| Total | {s // 60} horas {s % 60:02d} minutos |")Pasos para crear y ejecutar un skill en Claude Code
Son 4 pasos. AInformation usó Claude Code 2.1.316 (Opus 5.5) con una carpeta de prueba (que solo contenía 5 días de informes diarios). La versión 2.1.316 se publicó el 31 de octubre de 2026, y la probamos ese mismo día.
mkdir -p .claude/skills/shuho-matome/scripts
El nombre de la carpeta se convierte directamente en el nombre del comando /shuho-matome.
En segundo lugar, se guardan el SKILL.md y el jikan.py anteriores en esta carpeta. En tercer lugar, se inicia claude en esa carpeta. Al ser la primera vez que se usa esa carpeta, aparece una confirmación de confianza, y se selecciona “Yes”.
Crea el informe semanal de esta semana a partir de los informes diarios de la carpeta memo.
No se menciona el nombre del skill. La IA decide si coincide con la descripción.
Al hacer la solicitud, apareció de inmediato “Skill(shuho-matome)” y “Successfully loaded skill”. Después se pregunta si se permite ejecutar jikan.py. Como se inició con –permission-mode default, se pregunta cada vez antes de ejecutar un programa.
Al dar el permiso, apareció el informe semanal siguiendo el orden de los tres títulos escritos en SKILL.md. El desglose de tiempo es la misma tabla de jikan.py, y al final aparece la línea “(creado con el formato de informe semanal v1)”. Esa línea se incluyó a propósito en el procedimiento como marca para distinguir si el skill se había leído o no.
También se probó llamarlo directamente escribiendo /shuho-matome. Con -p tardó 15.3 segundos y produjo un informe semanal con el mismo formato que cuando se invocó automáticamente.
Se ejecutó la misma solicitud 3 veces con skill y 3 veces sin skill
Para ver qué cambia con el skill, se ejecutó la misma solicitud 3 veces también sin skill. Aquí se produjo un fallo: al ejecutarlo en la carpeta donde se había borrado el skill, Claude Code leyó y usó el SKILL.md borrado a partir del historial de git. Ocurrió igual en las dos ocasiones. Para la comparación, se repitió la prueba en otra carpeta donde el skill tampoco estaba en el historial.
Resultado de ejecutar la misma solicitud 3 veces (sin skill, con skill, con plugin)
| Forma de ejecución | Segundos hasta la respuesta | Tokens de salida | Siguió el formato del informe semanal |
|---|---|---|---|
| Claude Code, sin skill | 34.7–39.3 segundos | 3,615–4,385 | 0 de 3 |
| Claude Code, con skill | 13.7–16.4 segundos | 1,116–1,470 | 3 de 3 |
| Claude Code, con plugin | 19.8–26.7 segundos | 1,303–1,650 | 3 de 3 |
| Antigravity, sin skill | 82–134 segundos | 4,636–6,547 | 0 de 3 |
| Antigravity, con skill | 39–52 segundos | 1,886–2,017 | 3 de 3 |
| Antigravity, con plugin | 27–40 segundos | 1,583–2,113 | 3 de 3 |
Incluso sin skill, el total de 40 horas coincidió en las 3 ocasiones. Lo que cambió fue el formato y la velocidad. La estructura de los títulos era distinta cada vez, y la forma de escribir el tiempo también variaba entre “40.0 horas” y “40 horas”. En las 3 ocasiones intentó guardar un archivo, pero se le denegó por no tener permiso de escritura. En las ejecuciones con skill no intentó guardar nada que no se le había pedido, y la respuesta llegó en 13.7–16.4 segundos. Los tokens de salida también bajaron de 3,615–4,385 a 1,116–1,470.
Cuanto más fijo es el formato de una tarea, mayor es el efecto de convertirla en skill. Por otro lado, en las tareas donde se quiere que la IA piense el contenido por sí misma, limitarla con un procedimiento estrecha las respuestas. AInformation solo convierte en skill lo que quiere recibir siempre con el mismo formato y lo que siempre usa la misma herramienta.
El mismo SKILL.md también funcionó en Antigravity
Se colocó la misma carpeta, tal cual, en Antigravity (2.28.2, Gemini 3.8 Flash), presentado en el artículo sobre cómo usar Antigravity. En Antigravity, la ubicación es .agents/skills. La documentación oficial indica: “Antigravity defaults to .agents/skills, but still maintains backward compatibility for .agent/skills.”
Dónde colocar los skills (documentación oficial y medición de esta prueba)
| Alcance de uso | Claude Code | Antigravity |
|---|---|---|
| Solo esta carpeta | .claude/skills/nombre/ | .agents/skills/nombre/ |
| Todas mis carpetas | ~/.claude/skills/nombre/ | ~/.gemini/config/skills/nombre/ |
| Distribuido mediante plugin | skills/ del plugin | skills/ del plugin |
| ¿Lee la ubicación del otro? | No la leyó | No la leyó |
Se ejecutó la misma solicitud 3 veces. En las 3 ocasiones primero abrió SKILL.md, ejecutó jikan.py y después escribió el informe semanal. La línea final “(creado con el formato de informe semanal v1)” también apareció en las 3 ocasiones. En SKILL.md, la ruta de jikan.py seguía escrita de forma relativa a SKILL.md, pero Antigravity la convirtió en la ruta absoluta de la carpeta antes de ejecutarlo.
También se midió cuánto aumenta solo por tener el skill colocado. La cantidad que Antigravity envió inicialmente a la IA fue apenas unos 78 tokens más que en la ejecución sin skill. Como en la lista solo entran el nombre y la descripción, la carga por cada skill es de este orden.
Antigravity sin skill escribió el archivo del informe semanal en la carpeta memo sin preguntar en las 3 ocasiones. Esto se debe a que, en el nivel de permiso predeterminado (Default), no se pregunta por la escritura dentro de la carpeta. En las ejecuciones con skill, como SKILL.md no incluye un procedimiento de guardado, solo lo mostró en pantalla.
La ubicación varía según la aplicación, y cada una no lee la ubicación de la otra. Un skill colocado únicamente en .claude/skills no apareció en la lista de / de Antigravity. Para usarlo en ambas, hay que colocar la misma carpeta en dos ubicaciones, o distribuirla mediante un plugin, como se explica más adelante.
Diferencias con las especificaciones oficiales (probado con 9 versiones de SKILL.md)
Las reglas de SKILL.md varían ligeramente entre los tres documentos oficiales. La especificación de Agent Skills exige name y description, y sobre name dice “Must match the parent directory name” (debe coincidir con el nombre de la carpeta superior). El documento de Claude Code dice “All fields are optional. Only description is recommended” (todos los campos son opcionales, solo se recomienda description), mientras que el documento de Antigravity exige únicamente description.
Por eso se crearon 8 versiones que no cumplen con la especificación, y junto con la versión original se probaron 9 formas en ambas aplicaciones. En Claude Code se colocó cada una en una carpeta distinta y se hizo la misma solicitud sin mencionar el nombre. La columna de especificación muestra el conteo que hizo AInformation según las reglas escritas en la página de la especificación.
Cómo se trata un SKILL.md que no cumple con la especificación (9 versiones)
| Forma de escritura | Regla de la especificación | Claude Code | Antigravity |
|---|---|---|---|
| Solo name y description | Cumple | ◎ Se llamó automáticamente | ◎ Se leyó automáticamente |
| Sin configuración inicial (—) | × Obligatorio | ◎ Usó la primera línea como descripción y lo llamó | × Error de carga |
| Sin name | × Obligatorio | ◎ Lo llamó por el nombre de la carpeta | △ Se lee automáticamente, pero no aparece en la lista de / |
| Sin description | × Obligatorio | ◎ Usó el encabezado como descripción y lo llamó | △ Lo buscó y luego lo leyó |
| name con mayúsculas y _ | × Solo minúsculas | ◎ Apareció como /V5_Oomoji | ○ Apareció en la lista |
| name distinto al nombre de la carpeta | × Deben coincidir | ◎ Apareció con ambos nombres | ○ Apareció solo con el name |
| Descripción de 1,100 caracteres | × Hasta 1,024 caracteres | ◎ Se llamó automáticamente | ○ El texto completo apareció en la lista |
| La descripción incluye “: ” y rompe el YAML | × No se puede leer | ◎ Se pudo leer incluso la descripción | ○ Apareció con descripción |
| Configuración para no llamarlo automáticamente | (Campo exclusivo de Claude Code) | × No se llamó; la IA abrió el contenido por su cuenta | × Quedó fuera de la lista; lo buscó y lo leyó |
Claude Code llamó a las 8 variantes restantes, es decir, a todas excepto la que tenía la configuración para no llamarse automáticamente. Es más flexible que la especificación: aunque falte la configuración inicial, usa la primera línea como descripción. Cuando el name difiere del nombre de la carpeta, en la lista de /skills apareció con el nombre de la carpeta. En el menú de / apareció con el name. El documento oficial indica que también se puede llamar por el nombre de la carpeta.
La forma en que se trató el YAML roto fue distinta de lo que indica el documento oficial. El documento dice “If the frontmatter YAML is malformed, Claude Code loads the skill body with empty metadata” (si el frontmatter YAML está mal formado, Claude Code carga el cuerpo del skill con metadatos vacíos). Un SKILL.md con “: ” (dos puntos y un espacio normales, no de ancho completo) en el texto de la descripción no se puede leer con el cargador de Python (PyYAML). Aun así, Claude Code leyó incluso la descripción y la mostró en el menú de /. Tampoco claude plugin validate emitió ninguna advertencia para este formato.
Antigravity es un poco más estricto. Con un SKILL.md sin configuración inicial, mostró los mensajes “A customization failed to load” y “invalid frontmatter format”, y no lo leyó. El formato sin name no aparece en la lista de /, a pesar de que su propio documento dice “Defaults to the folder name if not provided” (si no se proporciona, usa el nombre de la carpeta por defecto). Sin embargo, al hacer una solicitud sin mencionar el nombre, sí lo leyó automáticamente.
También hubo diferencias en la configuración exclusiva de Claude Code (disable-model-invocation). Antigravity también tomó en cuenta esta configuración y excluyó el skill de la lista automática. Ambas aplicaciones, aunque el skill no aparecía en la lista, buscaron entre las carpetas, encontraron el SKILL.md, leyeron su contenido y lo usaron. “No llamar automáticamente” no significa que la IA no vaya a leer ese archivo.
La conclusión es sencilla. Si el name se escribe en minúsculas e igual al nombre de la carpeta, y se incluye description, funciona en ambas aplicaciones. Aunque funcione en Claude Code, una forma de escritura que no cumple con la especificación puede fallar en otras aplicaciones. La especificación también dice “Keep your main SKILL.md under 500 lines” (mantén tu SKILL.md principal por debajo de 500 líneas), así que conviene dividir los procedimientos largos en archivos separados.
Cuando hay muchos skills, la descripción desaparece de la lista (los 295 de AInformation)
AInformation tiene 295 skills propios. Al ejecutar /skill-doctor con -p en Claude Code, se muestra qué skill se usó y cuándo. Los nombres se mantuvieron en privado por estar relacionados con el trabajo, y solo se desglosó la cantidad.
Skills que tiene AInformation (295, al 31 de octubre de 2026, según /skill-doctor)
| Área | Cantidad | Usados en los últimos 7 días | Nunca usados |
|---|---|---|---|
| Artículos y datos del sitio | 154 | 43 | 40 |
| Ventas y administración | 48 | 14 | 13 |
| Entorno de trabajo y herramientas | 33 | 17 | 10 |
| Capacitación y materiales | 31 | 12 | 10 |
| Video, redes sociales y publicidad | 29 | 7 | 6 |
| Total | 295 | 93 | 79 |
Los usados hoy o ayer fueron 49, y en los últimos 7 días, 93. También hay 79 que nunca se han invocado. El skill que más se usa fue invocado 218 veces, y los 10 primeros representaron el 36.7% del total.
Lo que llamó la atención fue el contenido del listado. En la tabla de /skill-doctor, solo 18 skills tenían también la descripción incluida en el listado. Las otras 277 tienen menos de 20 tokens y solo aparece el nombre. La documentación oficial dice: “The budget scales at 1% of the model’s context window” (el presupuesto escala al 1% de la ventana de contexto del modelo), y agrega que cuando se desborda, “Claude Code drops descriptions starting with the skills you invoke least” (Claude Code elimina las descripciones empezando por los skills que menos invocas). Los skills cuya descripción se elimina terminan siendo invocados solo por el nombre.
La causa no fue la cantidad, sino la longitud de las descripciones. Las descripciones de los skills de AInformation suman 179,040 caracteres, con una mediana de 550 caracteres por skill. Hubo 27 que superaban el límite de 1,024 caracteres que fija la especificación. Al colocar en una carpeta de prueba 300 descripciones ficticias de unos 55 caracteres cada una, con un total de 16,745 caracteres, todas las descripciones quedaron en el listado. El skill del informe semanal también fue invocado las 3 veces, con tiempos de respuesta de entre 14.7 y 22.9 segundos.
La descripción debe escribirse de forma breve, colocando al inicio el caso de uso más frecuente y las palabras que se usan al pedirlo. La documentación oficial también indica que la descripción aparece “truncated at 1,536 characters in the skill listing” (truncada a 1,536 caracteres en el listado de skills). Aunque se escriba más, la parte final no se usa. Puedes comprobar si una descripción se eliminó del listado con /skill-doctor o /context. Otra opción es desactivar los skills que no usas.
Cómo probamos la distribución: de un repositorio a Claude Code y Antigravity
Hay 3 formas de compartir un skill creado con otras personas. AInformation probó un plugin que también puede usarse desde otros repositorios.
3 formas de distribuir skills (según la documentación oficial y lo probado en este artículo)
| Forma de distribución | Indicada para | En esta prueba |
|---|---|---|
| Colocar .claude/skills en el repositorio | Compañeros que trabajan en el mismo repositorio | Se ejecutó en una carpeta de prueba |
| Distribuir mediante un plugin | Personas que también lo usan en otros repositorios | Se probó tanto en Claude Code como en Antigravity |
| Subir un zip a claude.ai | Personas que lo usan en la pantalla de chat | No se probó (los elementos disponibles se reducen a 6) |
La documentación de Antigravity indica que se puede colocar plugin.json para Claude Code y plugin.json para Antigravity en el mismo repositorio. El texto original dice: “for multi-provider repositories that also ship .claude-plugin/plugin.json” (para repositorios multiproveedor que también incluyen .claude-plugin/plugin.json). Así que creamos un repositorio con un solo skill, con la siguiente estructura.
skills-haifu/ (repositorio de Git)
├── .claude-plugin/marketplace.json (catálogo para Claude Code)
└── plugins/shuho/
├── .claude-plugin/plugin.json (para Claude Code)
├── .antigravity-plugin/plugin.json(para Antigravity)
└── skills/shuho-matome/ (un único skill, el mismo de arriba)El catálogo para Claude Code (marketplace.json) tiene unas 10 líneas. En source se escribe la ubicación del plugin vista desde la carpeta del catálogo.
{
"name": "renshu-market",
"description": "Marketplace para distribuir skills de prueba",
"owner": { "name": "AInformation" },
"plugins": [
{ "name": "shuho", "source": "./plugins/shuho", "description": "Skill que genera un informe semanal a partir de los informes diarios" }
]
}Una vez creado, se verifica con claude plugin validate. Tanto el catálogo como el plugin pasaron la validación. Sin embargo, aparece un aviso de que, si se quiere publicar en el directorio oficial de plugins de Anthropic, se necesitan un README y una licencia (LICENSE). Si solo es para compartir con compañeros, se puede usar tal cual.
claude plugin marketplace add /tmp/skills-haifu –scope project
En producción se puede escribir en el formato owner/repo de GitHub. Con –scope project, se registra solo en la configuración de esa carpeta.
claude plugin install shuho@renshu-market –scope project
Tiene el formato nombre@nombre_del_catálogo.
Ambos comandos terminaron en menos de 1 segundo (0.66 y 0.69 segundos). En .claude/settings.json de la carpeta queda escrito lo siguiente. Según la documentación oficial, si este archivo se incluye en el repositorio, el mismo catálogo también se agrega en el entorno de los compañeros. Sin embargo, dice: “The extraKnownMarketplaces entries apply only in a folder the contributor has trusted” (las entradas de extraKnownMarketplaces solo se aplican en una carpeta que el colaborador haya marcado como confiable), por lo que surte efecto después de que el compañero confíe en esa carpeta.
{
"extraKnownMarketplaces": {
"renshu-market": {
"source": {
"source": "directory",
"path": "/tmp/skills-haifu"
}
}
},
"enabledPlugins": {
"shuho@renshu-market": true
}
}Al ejecutar la misma solicitud 3 veces, en las 3 ocasiones se invocó el skill “shuho:shuho-matome”, con el nombre del plugin como prefijo. Los tiempos de respuesta fueron de entre 19.8 y 26.7 segundos, un poco más lentos que cuando se coloca directamente en la carpeta. jikan.py se ejecuta desde la ubicación del plugin, fuera del proyecto.
En Antigravity, se clonó el mismo repositorio y se colocó la carpeta plugins/shuho en .agents/plugins. La documentación oficial dice: “Workspace level: Place your plugin folder in .agents/plugins/” (a nivel de espacio de trabajo: coloca la carpeta de tu plugin en .agents/plugins/). Al reiniciar la aplicación, apareció en el listado de / con la etiqueta “shuho”.
Al ejecutarlo 3 veces, en las 3 ocasiones leyó SKILL.md y devolvió el informe semanal con el formato establecido en un tiempo de entre 27 y 40 segundos. Esto significa que se pudo distribuir el mismo skill desde un solo repositorio a dos aplicaciones.
Esta vez no se probó el método de subir un zip a claude.ai. Según la documentación de Claude Code, en claude.ai o en la API solo se pueden usar 6 campos: name, description, license, compatibility, metadata y allowed-tools. Si se escriben otros campos, se produce un error al subirlo. Para los skills que también se usan en la pantalla de chat, hay que escribirlos solo con estos 6 campos.
Cómo solucionar el problema cuando el skill no se activa
A continuación se presenta una tabla de referencia rápida con los puntos donde se tropezó esta vez y la solución según la documentación oficial.
Cuando no aparece en la lista, primero hay que revisar la ubicación de los archivos. Claude Code usa .claude/skills, y Antigravity usa .agents/skills. Ninguna de las dos aplicaciones lee la ubicación de la otra. Cuando desaparece en Antigravity, se puede ver el motivo en el mensaje “A customization failed to load” que aparece en la parte inferior de la pantalla.
Cuando aparece en la lista pero no se activa automáticamente, hay que revisar si la description incluye la palabra que realmente se usa al hacer la solicitud. Quienes tienen muchos skills pueden usar /skill-doctor para confirmar si alguna descripción se ha quedado fuera de la lista. Si aun así no se activa, se puede invocar directamente con /nombre, lo cual siempre funciona. La forma en que aparecen los errores está recopilada en el artículo sobre errores y límites de Claude Code, y los comandos que se pueden escribir con / están recopilados en la lista de comandos de Claude Code.
Hay que tener cuidado con los skills que se reciben de otras personas. Si se escribe allowed-tools, mientras se usa ese skill se pueden otorgar permisos de herramientas por adelantado. La documentación oficial indica: “Claude Code applies a project skill’s allowed-tools even in a -p run in a folder you’ve never trusted”. En un repositorio desconocido, conviene leer primero el contenido de .claude/skills antes de iniciar Claude Code.
Al comparar skills, también hay que revisar si queda algún skill que se creía eliminado. En esta ocasión, una ronda de comparación falló porque se recuperó y leyó un SKILL.md eliminado desde el historial de git. Las rondas de comparación se deben ejecutar en una carpeta donde nunca se haya instalado ningún skill.
Los resultados de comparar con la misma tarea las herramientas de codificación con IA que pueden usar skills se resumen en la tabla comparativa de herramientas de codificación con IA.
Resumen
Los Claude Skills se crean colocando un único archivo SKILL.md en una carpeta con el nombre correspondiente. El skill de prueba de AInformation tiene 19 líneas. En Claude Code se activó automáticamente las 3 veces, y la misma solicitud pasó de tardar entre 34.7 y 39.3 segundos a entre 13.7 y 16.4 segundos. El mismo archivo SKILL.md también se leyó las 3 veces en Antigravity. Con formatos que no se ajustaban a la especificación, Claude Code funcionó igualmente, pero en Antigravity algunos de ellos hicieron que se detuviera. Para distribuirlo, basta con colocar dos archivos plugin.json en un solo repositorio para que funcione en ambas aplicaciones. Cuando aumenten los skills, conviene acortar las descripciones para evitar que se queden fuera de la lista.
Preguntas frecuentes
- ¿Qué son los Claude Skills?
- Son un conjunto de procedimientos o reglas que se quiere que la IA recuerde, agrupados en una carpeta junto con un archivo llamado SKILL.md y, en algunos casos, programas. El contenido solo se lee cuando la solicitud coincide con la descripción.
- ¿Cuál es la forma más sencilla de crear un skill en Claude Code?
- Hay que crear .claude/skills/nombre/SKILL.md, escribir name y description al principio y debajo los procedimientos. Una vez guardado, se puede usar desde la próxima vez que se inicie Claude Code.
- ¿Qué campos son obligatorios en SKILL.md?
- Según la especificación, son dos: name y description. Claude Code funciona incluso sin ellos, pero si también se va a usar en otras aplicaciones, conviene escribir ambos. El name debe coincidir en minúsculas con el nombre de la carpeta.
- ¿Dónde se colocan los skills?
- En Claude Code, dentro de .claude/skills de esa carpeta, o en ~/.claude/skills si se quiere usar en todas las carpetas. En Antigravity, en .agents/skills o en ~/.gemini/config/skills.
- ¿Se puede usar el mismo skill también en Antigravity?
- Sí. Cuando AInformation colocó el mismo archivo SKILL.md en .agents/skills, se leyó las 3 veces y produjo respuestas con el mismo formato. Es imprescindible escribir la configuración inicial (la parte delimitada por —).
- El skill no se activa automáticamente, ¿qué hago?
- Revisa si la description incluye las palabras que realmente se usan al hacer la solicitud. Quienes tienen muchos skills también pueden usar /skill-doctor para comprobar si alguna descripción se ha quedado fuera de la lista. También se puede invocar directamente con /nombre.
- ¿Cuántos caracteres se pueden escribir en description?
- El límite según la especificación es de 1,024 caracteres. Claude Code usa hasta 1,536 caracteres en la lista. Es mejor escribir primero el uso más importante y mantenerlo breve, para que sea menos probable que quede fuera de la lista.
- ¿Cómo se diferencia el uso de un skill y de CLAUDE.md?
- Las reglas que se quieren respetar siempre se escriben en CLAUDE.md, y los procedimientos de tareas específicas se escriben en un skill. El contenido de un skill solo se lee cuando se usa, así que aunque el procedimiento sea largo no representa una carga adicional.
- ¿Cómo se comparte un skill con otras personas?
- Si se trabaja en el mismo repositorio, basta con incluir .claude/skills en Git. Si también se va a usar en otros repositorios, conviene convertirlo en un plugin, y que lo instalen con claude plugin marketplace add y claude plugin install.
- ¿Cuál es la diferencia entre un skill y MCP?
- Un skill enseña procedimientos o reglas, mientras que MCP agrega herramientas para conectarse a servicios externos o bases de datos. También se pueden combinar ambos: escribir en un skill cómo usar una herramienta agregada mediante MCP.
