¿Tu skill de Claude no se activa? Arréglalo en 6 checks

Instalaste un skill, le pediste a Claude que hiciera justo lo que el skill hace, y Claude siguió a lo suyo como si el skill no existiera. Sin error, sin aviso, sin nada que grepear. Solo silencio.

Lo vemos constantemente. SkillProof instala y testea cada skill de nuestro catálogo en una máquina limpia, y el fallo de activación es el defecto más común que encontramos. También es el más arreglable: casi todos los reportes de "el skill no funciona" de nuestros registros de pruebas se remontan a una de seis causas, y cinco de ellas se descartan en menos de un minuto.

Pasa la checklist primero. El resto del artículo desarrolla cada comprobación con el síntoma, la causa y el arreglo.

La checklist de 30 segundos

1. ¿Carpeta correcta? El archivo debe estar en ~/.claude/skills/<skill-name>/SKILL.md, una carpeta por skill, con el nombre exacto SKILL.md.
2. ¿Reiniciaste? Claude escanea los skills al inicio de la sesión. Los cambios hechos a mitad de sesión son invisibles hasta que reinicias.
3. ¿Colisión de nombres? Dos skills con el mismo name se eclipsan mutuamente. Solo uno sobrevive.
4. ¿Descripción demasiado vaga? Si la descripción no menciona lo que los usuarios piden literalmente, Claude nunca la casa. Esta es la causa número uno.
5. ¿Frontmatter válido? Un solo carácter de YAML roto hace invisible el skill entero, en silencio.
6. ¿Skill en conflicto? Otro skill instalado con una descripción solapada puede estar ganando el match.

Si las seis pasan y el skill se activa pero el output no cambia, eso es otro fallo. Salta a cuando se activa pero no hace nada.

Comprobación 1: el skill está en la carpeta equivocada

Síntoma. El skill nunca aparece cuando le preguntas a Claude "¿qué skills tienes instalados?". Como si nunca lo hubieras copiado.

Causa. Claude solo mira en sitios concretos: ~/.claude/skills/ para skills personales y .claude/skills/ dentro de un proyecto para skills de proyecto. Dentro de ellos, la disposición es estricta: una carpeta por skill, con un archivo llamado exactamente SKILL.md. Los errores que más vemos al instalar skills comunitarios para testearlos: copiar el repo clonado entero (con lo que la ruta acaba siendo skills/some-repo/skills/pdf-helper/SKILL.md, un nivel de más), soltar el SKILL.md directamente en ~/.claude/skills/ sin su propia carpeta, y skill.md en minúsculas, que algunos sistemas de archivos perdonan y otros no.

Arreglo. Verifica desde la terminal:

ls ~/.claude/skills/*/SKILL.md

Cada skill que esperas debería imprimir exactamente una línea. Si un skill falta o su ruta tiene anidamiento extra, mueve la carpeta para que SKILL.md quede un nivel por debajo de skills/. Nuestra guía de instalación recorre la estructura correcta para cada plataforma.

Comprobación 2: no reiniciaste

Síntoma. La estructura de carpetas es correcta, la arreglaste hace dos minutos, y Claude sigue sin ver el skill en la misma conversación.

Causa. El descubrimiento de skills ocurre una vez, al arrancar. Claude lee el frontmatter de cada SKILL.md que encuentra y retiene ese índice durante la sesión. Un skill que añades, renombras o editas a mitad de sesión no existe para la sesión en marcha.

Arreglo. En Claude Code, sal y arranca una sesión nueva. En la app de escritorio, cierra del todo con Cmd+Q en macOS (cerrar la ventana no cuenta) y vuelve a abrir. Esto es tan barato de descartar que lo hacemos antes de cualquier debugging más profundo, igual que reiniciarías el router antes de llamar a tu operadora.

Comprobación 3: una colisión de nombres está eclipsando tu skill

Síntoma. Instalaste el skill, la carpeta está bien, reiniciaste, y la lista de skills muestra o bien nada nuevo o bien un skill distinto respondiendo al mismo nombre.

Causa. Los nombres de skill deben ser únicos. Si un skill personal y uno de proyecto comparten name, o dos packs instalados traen ambos un skill llamado seo-audit, uno eclipsa al otro sin aviso. Nos pasó en nuestro propio trabajo de catálogo: dos packs de marketing instalados en paralelo produjeron un duplicado silencioso, y el que queríamos nunca cargó.

Arreglo. Busca duplicados:

grep -h "^name:" ~/.claude/skills/*/SKILL.md .claude/skills/*/SKILL.md 2>/dev/null | sort | uniq -d

Cualquier salida significa colisión. Renombra la carpeta y el campo name de la copia que controlas, reinicia y revisa la lista de nuevo.

Comprobación 4: la descripción nunca dice cuándo dispararse

Síntoma. El skill aparece en la lista de instalados. Pídelo por su nombre y funciona bien. Pide la tarea con tus propias palabras y no pasa nada.

Causa. Esta es la grande, y merece su propia sección, así que aquí va la versión corta: Claude decide si cargar un skill leyendo únicamente su campo description y comparándolo con tu petición. Si la descripción dice qué es el skill en lugar de cuándo usarlo, el match nunca ocurre. El skill no está roto. Está sin anunciar.

Arreglo. Reescribe la descripción alrededor de las frases que los usuarios teclean de verdad. El análisis a fondo de abajo muestra tres patrones de fallo reales y sus reescrituras.

Comprobación 5: el frontmatter es inválido

Síntoma. Carpeta correcta, reinicio hecho, sin colisión de nombres, y el skill sigue sin aparecer en la lista. Se parece a la comprobación 1, pero la ruta está bien.

Causa. El bloque YAML del principio de SKILL.md no se pudo parsear, y un skill con frontmatter imparseable simplemente se omite. Los culpables habituales de nuestras notas de test: un --- de cierre que falta, dos puntos sin comillas dentro de la descripción ("Use for: reports" rompe el parser), comillas tipográficas pegadas desde un blog o un Google Doc, tabuladores usados para indentar, y un name que viola las reglas de formato (solo minúsculas, dígitos y guiones, máximo 64 caracteres; las descripciones tienen tope de 1024).

Arreglo. Abre el archivo y examina el bloque, o sáltate el examen ocular: pégalo en nuestro validador de skills y señala al instante errores de parseo, violaciones de formato y contaminación de comillas tipográficas. Si el frontmatter parsea y el skill sigue escondido, vuelve a la comprobación 1, porque a esas alturas es casi siempre la ruta.

Comprobación 6: otro skill está ganando el match

Síntoma. Pides la tarea y un skill sí se activa, solo que no el tuyo. O el comportamiento cambia de una forma que encaja con las instrucciones de otro skill.

Causa. Cuando varias descripciones cubren plausiblemente una petición, Claude elige la que parece encajar mejor, y una descripción más amplia y más segura de sí misma tiende a ganar a una más estrecha. Instala un skill genérico de "asistente de escritura" junto a tu "formateador de release notes" y el generalista puede tragarse todas las peticiones de escritura, release notes incluidas.

Arreglo. Afila ambas descripciones para que sus territorios no se solapen, y añade exclusiones explícitas. Una línea como "Do NOT use for release notes or changelogs" en la descripción del generalista es burda y funciona. Si no controlas el skill infractor, desactívalo mientras pruebas el tuyo, y luego decide si de verdad necesitas ambos.

Por qué fallan las descripciones: el análisis a fondo

Testeamos cada skill que listamos, y los problemas de activación son la razón número uno de que los skills puntúen bajo en nuestras reseñas. No scripts rotos, no malas instrucciones. Descripciones que nunca hacen match.

La mecánica explica por qué. Al arrancar, Claude carga solo el name y la description de cada skill, unos cien tokens. El cuerpo, por brillante que sea, se queda en disco hasta que la descripción gana un match contra tu petición. La descripción es un discurso de ventas dirigido a un modelo, y la mayoría de autores la escribe como la etiqueta de un museo.

Aquí están los tres patrones que más penalizamos, con las reescrituras que los arreglaron en nuestros retests.

Patrón 1: la etiqueta modesta.

description: Helps with documents.

Nada de esto conecta con nada que un usuario teclearía. Compáralo con el skill DOCX de Anthropic, que pasó nuestros tests de activación a la primera. Su descripción nombra el formato de archivo, las acciones y las formulaciones que deberían activarlo. La reescritura que sigue la misma lógica:

description: Create, edit, and format Word documents (.docx).
  Use when the user mentions a Word doc, .docx file, memo,
  letter, or asks for a deliverable "as a document."

Patrón 2: el nombre interno.

description: Runs the acme-formatter pipeline with corporate config.

Esto describe la implementación. Ningún usuario le pide a Claude "ejecutar el pipeline acme-formatter"; pide "deja limpio este informe antes de enviárselo a un cliente". La reescritura traduce el skill al vocabulario del usuario:

description: Reformat rough drafts into client-ready reports using
  Acme's corporate style. Use when the user wants to clean up,
  polish, or "make presentable" a document for external sharing.

Patrón 3: la manta codiciosa.

description: Use for any writing task.

El fallo contrario. Esto encaja con todo, lo que significa que colisiona con todos los demás skills relacionados con escritura y se dispara cuando no debe, y los usuarios lo desactivan en una semana. La reescritura estrecha la afirmación y valla los bordes:

description: Write and edit marketing copy: landing pages, ads,
  and email campaigns. Do NOT use for technical docs, code
  comments, or internal memos.

El test que aplicamos al revisar: lee solo la descripción y pregúntate, "si un usuario tecleara su petición con naturalidad, ¿casarían estas palabras con ella?". Escribe en tercera persona, di qué hace el skill y cuándo aplica, e incluye los sustantivos reales que usa la gente. Si estás escribiendo un skill desde cero, nuestra guía de autoría lo cubre con más profundidad, y el Skill Creator de Anthropic genera descripciones que pasan este test por defecto.

Cómo probar la activación como es debido

La mayoría prueba un skill nombrándolo: "usa el skill de facturas con esto". Eso no demuestra nada, porque nombrar un skill se salta por completo el match de la descripción. Es como probar un detector de humo pulsando el botón de test y concluir que tu casa es ignífuga.

Prueba como preguntaría un usuario, en una sesión nueva cada vez. Para un skill de extracción de facturas, tres formulaciones que deberían dispararlo:

• "Sácame los totales de estos PDFs de facturas."
• "Tengo 30 facturas de proveedores, pásame los importes y las fechas a una tabla."
• "Extrae las líneas de detalle de esta factura."

Y dos que no deberían:

• "Resúmeme este PDF." (Trabajo genérico con PDFs; territorio de otro skill.)
• "Escribe un email de factura para este cliente." (Redactar, no extraer.)

Si una formulación que debería disparar no hace nada, pregúntale a Claude directamente: "¿Cuál de tus skills instalados usarías para esta petición, y por qué?". La respuesta te enseña el razonamiento del match, y suele apuntar directo al punto débil de la descripción. Si las formulaciones que no deberían disparar activan el skill igualmente, tienes una manta codiciosa y necesitas exclusiones. Este es exactamente el protocolo que ejecutamos en las pruebas del catálogo, y es la misma disciplina que enseña el skill Systematic Debugging: reproduce primero, una variable cada vez, cree en la evidencia.

Cuando se activa pero no hace nada

Supón que el skill sí se activa. Puedes confirmarlo preguntándole a Claude a mitad de conversación si un skill cargó para la petición, y te lo dirá. Pero el output se ve igual que antes de instalar nada.

Eso no es un problema de activación, y nada de lo de arriba lo arreglará. Es un problema de cuerpo: las instrucciones dentro del skill son demasiado vagas para cambiar el comportamiento, o el skill referencia archivos incluidos que no existen en las rutas que espera, o llama a un script cuyas dependencias nunca se declararon. La descripción hizo pasar al skill por la puerta y el contenido se cayó dentro.

En nuestras pruebas este es el otro gran cubo de fallos, más o menos la imagen especular de los defectos de activación, y es la razón principal de que cerca de la mitad de los skills comunitarios suspendan nuestros tests. El discriminador rápido: si el comportamiento no cambió en absoluto, sospecha de la activación; si el comportamiento cambió pero mal o a medias, sospecha del cuerpo. Depura en consecuencia, porque los arreglos no se solapan.

Trampas por plataforma

El formato de skill es idéntico en todas partes, pero el descubrimiento no, y un skill que funciona en un sitio puede parecer muerto en otro.

Claude Code lee carpetas en disco: ~/.claude/skills/ para lo personal, .claude/skills/ por proyecto. Ambas cargan; las colisiones de nombres entre los dos ámbitos se resuelven con un solo ganador (comprobación 3). Reinicia la sesión tras cualquier cambio.

Claude Desktop no lee tus carpetas de skills. Los skills se suben como zip a través de Ajustes, en Capacidades, y el zip debe contener la carpeta del skill en el nivel superior, no el SKILL.md suelto ni un directorio envoltorio. Un skill que se activa bien en Claude Code estará simplemente ausente en Desktop hasta que lo subas ahí por separado.

claude.ai usa la misma vía de subida que Desktop, con dos maneras extra de perder: los skills necesitan la función de ejecución de código activada en tu plan, y los administradores del workspace pueden desactivar los skills para toda la organización, en cuyo caso nada de lo que subas se disparará jamás y ningún error te lo dirá. Pregunta a tu admin antes de gastar una tarde reescribiendo descripciones.

Una trampa multiplataforma más: un cuerpo de skill escrito para Claude Code que ejecuta git o lee archivos locales del proyecto se activará correctamente en claude.ai y luego fallará dentro del sandbox. Eso es un problema de cuerpo disfrazado de problema de plataforma.

Cuándo dejar de depurar

Si es tu propio skill, sigue adelante, porque cada arreglo de arriba es permanente y el validador más el test de las cinco formulaciones te llevarán hasta el final. Si es un skill de terceros y llevas más de veinte minutos quemados en el campo de descripción de otra persona, es legítimo cambiarlo por uno que ya haya pasado por esta checklist: cada skill de nuestras listas de los mejores superó las pruebas de activación en una máquina limpia antes de que lo listáramos.

FAQ

¿Cómo confirmo que un skill está instalado siquiera?

Pregúntale a Claude "¿qué skills tienes instalados?" en una sesión nueva. Si tu skill no está en la respuesta, el problema es de descubrimiento (comprobaciones 1, 3 y 5: carpeta, colisión, frontmatter), no de activación. Si está listado pero nunca se activa, el problema es la descripción (comprobaciones 4 y 6).

¿Puedo forzar el skill a activarse nombrándolo sin más?

Sí. "Usa el skill docx para escribir este memorando" carga el skill directamente, y es un apaño válido mientras depuras. No es un arreglo, eso sí: un skill que tienes que invocar por su nombre cada vez es un skill con la descripción rota, y se te olvidará invocarlo justo cuando importe.

¿Por qué mi skill funciona en Claude Code pero no en Desktop o claude.ai?

Rutas de descubrimiento distintas. Claude Code lee carpetas en disco; Desktop y claude.ai solo ven skills subidos a través de Ajustes como un zip con la carpeta del skill en el nivel superior. En claude.ai, confirma también que la ejecución de código está activada y que el admin de tu workspace no ha desactivado los skills por completo.

¿Instalar demasiados skills rompe la activación?

No directamente. Cincuenta skills cuestan unos pocos miles de tokens de metadatos, que es barato. El riesgo real es el solapamiento: cuantas más descripciones instalas, más probable es que dos reclamen el mismo territorio, y entonces a veces gana la equivocada (comprobación 6). Instala por necesidad y poda los skills que nunca se disparan.

Mi skill se activó ayer y hoy no. ¿Es normal?

De vez en cuando, sí. El matching lo hace el modelo, no una regex, así que una descripción justita se disparará con una formulación y fallará con otra casi idéntica. Si un skill es intermitente en lugar de estar muerto, trátalo como una descripción débil: añade al campo de descripción las frases exactas que fallaron, reinicia y vuelve a probar. Los skills fiables se activan con cualquier formulación razonable, y por eso probamos con cinco, no con una.