La respuesta corta
Si llamar a una Skill por su nombre funciona, está instalada. Que se ejecute por sí sola depende de su descripción, que el agente lee primero y puede acortar. Prueba las dos cosas por separado, porque fallan por motivos distintos.
Cómo elige una Skill cada agente
Cada agente lee primero una lista de nombres y descripciones de Skills, y solo carga las instrucciones completas de una Skill después de elegirla. Esa lista sale del frontmatter de cada SKILL.md (el archivo que mucha gente busca como skills.md), y tiene un presupuesto de tamaño:
| Agente | Lee primero | Cuando se acaba el espacio |
|---|---|---|
| Claude Code | Nombre y descripción, más when_to_use si está definido; hasta 1.536 caracteres cada uno | La lista ocupa alrededor del 1 % de la ventana de contexto; las descripciones menos usadas son las primeras en caer |
| Codex | Nombre, descripción y ruta del archivo | La lista ocupa alrededor del 2 % de la ventana de contexto; primero se acortan las descripciones |
| Cursor | Nombre y descripción | No documentado |
Con muchas Skills instaladas, una descripción larga o vaga puede recortarse o descartarse antes de que el agente llegue a valorarla. Por eso la primera frase es la que más importa.
Escribe una descripción de Skill que se elija
Escribe la descripción como un compañero pediría el trabajo, y pon el uso principal en la primera frase.
El agente compara tu petición con estas palabras, así que usa las que la gente escribe de verdad, como “landing page”, “página de lanzamiento” o “pitch deck”. Nombra primero el resultado y luego di cuándo usarla.
Qué crea y cuándo
- “Crea una página de lanzamiento de producto con Hero, cuadrícula de funciones y selector de precios. Úsala cuando te pidan una landing page o una página de lanzamiento.”
Genérica
- “Ayuda con sitios web.”
- Compite con todas las demás Skills web y, una vez acortada, apenas dice nada.
Cómo probar si se activa
Prueba en este orden. El primer paso descarta un problema de instalación, así que todo lo que falle después apunta a la descripción.
- 1Llámala por su nombre. Si falla, es un problema de instalación; consulta Solución de problemas.
- 2Empieza una sesión nueva, para que la llamada anterior no esté en el contexto, y pídelo con tus palabras sin el nombre.
- 3Pregúntale al agente qué Skill usó y busca una instrucción que solo seguiría esta Skill.
Cuando se ejecuta la Skill equivocada
Normalmente significa que dos descripciones se solapan o que la misma Skill está instalada dos veces.
- Llama a la que quieres por su nombre. Una llamada por nombre siempre gana.
- Acota las descripciones que se solapan por entrada, público o resultado, para que cada Skill tenga una función clara.
- Mismo nombre en dos sitios: Claude Code prefiere Enterprise, luego la personal y después la del proyecto. Codex puede mostrar las dos. Quédate con una sola copia.
Preguntas frecuentes
¿Por qué no se activa mi Claude Skill?
Llámala primero por su nombre. Si falla, la Skill no está instalada donde busca el agente; si solo fallan las peticiones normales, reescribe la descripción con las palabras que realmente escribes.
¿Cómo decide Claude qué Skill usar?
Lee el nombre y la descripción de cada Skill y carga la que mejor encaja con tu petición. Escribir /skill-name se salta esa comparación y ejecuta la Skill que nombraste.
¿Qué debe decir la descripción de una Skill?
Qué crea la Skill y cuándo usarla, con el uso principal en la primera frase. Usa las palabras que la gente escribe de verdad, como “landing page” o “pitch deck”, porque la descripción puede acortarse.
¿El archivo se llama SKILL.md o skills.md?
Se llama SKILL.md, uno en cada carpeta de Skill. Su frontmatter contiene el nombre y la descripción que leen los agentes al elegir una Skill.
Fuentes
¿Te ha sido útil esta guía?