Escribiste la skill. Está buena: tiene tu formato, tus reglas, el ejemplo de cómo se ve bien. La usas una vez y funciona. A los tres días le pides lo mismo con otras palabras y Claude te contesta como si la skill no existiera.
La conclusión natural es que la skill está mal escrita, así que la reescribes. Y eso casi nunca es el problema. El cuerpo de tu skill probablemente está bien. Lo que está roto es el disparador.
Cómo decide Claude si usar una skill
Esto es lo que cambia todo cuando lo entiendes: Claude no lee tus skills completas todo el tiempo. De cada skill instalada solo carga dos cosas, el name y la description. El cuerpo lo abre nada más cuando decide que esa skill aplica.
O sea que la decisión de activarla se toma leyendo una sola línea. Toda tu skill se juega ahí. Si esa línea dice "skill para escribir correos", Claude tiene que adivinar si tu mensaje de hoy cae adentro o no. A veces le atina. A veces no. Y tú lo lees como que la skill está descompuesta.
El diagnóstico, en treinta segundos
Antes de tocar nada, pregúntale directo. Abre un chat y pega esto:
¿Cuándo usarías la skill [nombre]? Léeme su descripción palabra
por palabra y explícame en qué situaciones la dispararías y en
cuáles no. Después dame tres mensajes que yo podría escribir y
que NO la activarían aunque debieran.Esos tres mensajes son el diagnóstico completo. Casi siempre son las formas normales en que tú pides la cosa. Y si son las normales, la descripción no está describiendo tu trabajo real.
Las tres razones por las que no jala
1. La descripción está escrita como título, no como disparador
Es el 80% de los casos. La gente escribe la descripción como si fuera el nombre de una carpeta. Y lo que se necesita ahí es una instrucción de cuándo.
Así se ve mal: "Escribe correos de seguimiento."
Así se ve bien:
description: Escribe correos de seguimiento a clientes después de
una llamada, en la voz del usuario, en menos de cinco oraciones y
con un siguiente paso claro. Úsala cuando pida dar seguimiento,
cerrar el pendiente de una junta, escribirle a un prospecto, o
cuando pegue notas de una llamada sin decir qué quiere.La fórmula que uso: qué hace, para quién, con qué formato, y después la lista de las frases con las que tú realmente lo pides. Esa última parte es la que casi nadie escribe y es la que activa la skill. Ponle cuatro o cinco variantes, incluyendo la floja: "dale seguimiento a esto".
2. La corres fuera del proyecto donde vive el contexto
Una skill que depende de archivos —tu guía de marca, la lista de precios, las plantillas— necesita estar en el proyecto donde esos archivos están cargados. Si la invocas desde un chat suelto, la skill se activa igual pero trabaja a ciegas, y la salida se ve genérica.
Eso se lee exactamente igual que "la skill no jaló". No es lo mismo. Revisa primero desde dónde la estás corriendo.
3. Dos skills se pelean el mismo terreno
Pasa mucho en equipos donde cada quien creó las suyas: hay una de propuesta comercial y otra de cotización, con descripciones que se traslapan. Claude elige una y no siempre la que tú querías.
Arreglo: que cada descripción diga también qué no es. Una línea basta. "No la uses para cotizaciones de renovación, para eso está la skill de renovaciones." Las instrucciones en negativo delimitan mejor que cinco frases más de lo que sí hace.
El paso que todo mundo se salta: ponle a cada skill un comando con diagonal, corto y en minúsculas. Es el interruptor manual: cuando la necesitas seguro, la llamas por su nombre y ya no dependes de que el disparador atine. Yo dejo que el disparador trabaje en el día a día y uso el comando cuando el entregable importa. Las dos cosas conviven; no es una u otra.
El arreglo, en cuatro pasos
- Junta las frases reales. Busca en tus últimos chats cómo pediste esa tarea. No cómo crees que la pides: cómo la pediste. Tres o cuatro ejemplos.
- Reescribe la descripción con la fórmula de arriba y mete esas frases textuales en la parte de "úsala cuando".
- Agrega el límite: una línea de para qué no sirve.
- Vuelve a correr el diagnóstico. Si los tres mensajes que Claude te da como "no la activarían" ya son casos raros de verdad, quedó.
Todo esto toma unos diez minutos y no toca el cuerpo de la skill.
El otro síntoma: sí se activa, pero sale floja
Distinto problema, distinta cura. Si la skill se dispara y aun así la salida se siente a medias, casi nunca es la skill: es que la petición pedía poco. Agregar en tu mensaje algo como "tómate el tiempo, no te saltes pasos, dame la versión completa" cambia el resultado más que reescribir el archivo. Funciona mejor en el mensaje que adentro de la skill.
Y la tercera versión del problema, la más común de todas en operación: la skill jala, la salida está bien, pero nunca la iteraste. La primera versión de una skill es un borrador. Después de usarla cinco veces ya sabes qué corriges siempre a mano. Eso que corriges es la regla que falta. Pégasela.
Lo que veo en las empresas
Cuando entro a una operación que ya tiene quince skills creadas, el patrón es siempre el mismo: nadie las escribió mal, nadie les puso disparadores decentes, y como no se activan solas, cada persona acabó copiando el texto de la skill a mano dentro del chat. Que es exactamente el trabajo que la skill venía a quitar.
Antes de construir la siguiente, dale diez minutos a las descripciones de las que ya tienes. Es el arreglo más barato de todo el sistema. Si de plano hay que reconstruir, el proceso completo está en 3 formas de construir una skill, y hay cinco atajos más en 5 trucos de skills de los que nadie habla.