English

Tu mejor skill nunca se ejecuta

Escribiste una skill de la que estás orgulloso: pasos cuidados, experiencia real, exactamente el procedimiento que repites. Nunca se dispara. Terminas haciendo la tarea a mano al lado de un archivo que la habría hecho por ti. La skill no es el problema, y el modelo tampoco.

Solo la descripción está en la sala

Una skill tiene dos partes que se comportan de forma completamente distinta. El frontmatter le dice al agente cuándo usarla; el cuerpo tiene las instrucciones que sigue una vez corriendo. Y algo clave: el cuerpo se carga solo cuando se usa, que es lo que hace barato el material de referencia largo.

Lo que sí vive permanentemente en el contexto es un listado de nombres y descripciones, para que el agente sepa qué hay disponible. Y la descripción es lo que decide la selección: es el campo que el agente usa para saber cuándo aplicar la skill. Si la omites, se usa el primer párrafo del cuerpo.

Así que la descripción no es documentación para un lector humano. Es el enrutador. Es la única parte de tu skill que participa en la decisión de si el resto llega a ejecutarse.

Escríbela para el despachador

Ese cambio de encuadre cambia cómo la escribes. No estás resumiendo la skill; estás describiendo la situación en la que debería dispararse, con las palabras que alguien escribiría estando en esa situación.

• Empieza por el caso que dispara. El texto combinado se trunca en el listado, así que pon la situación primero y la elaboración después; lo que quede después del corte no puede ayudarte.
• Usa las palabras que usan tus pedidos. La selección es un problema de coincidencia. Vocabulario que nunca escribirías es vocabulario que nunca coincide.
• Agrega frases disparadoras explícitas. Hay un campo dedicado en el frontmatter para contexto extra sobre cuándo invocar una skill, incluidos ejemplos de pedidos.
• Sé específico. El arreglo documentado para una skill que no se dispara es una descripción más específica.

Las descripciones vagas no fallan con elegancia: simplemente nunca coinciden, y la falla es silenciosa. No te avisan que una skill estuvo cerca de ser relevante.

La trampa del coleccionista

Acá está la parte que casi nadie sabe, y le pega justo a quienes más invierten en skills.

El listado tiene un presupuesto de caracteres, que escala alrededor del 1% de la ventana de contexto del modelo. Cuando tus skills lo desbordan, las descripciones se acortan para caber, lo que puede quitar justo las palabras clave necesarias para coincidir con tu pedido. Y el orden importa: las descripciones se descartan empezando por las skills que menos invocas, así que las que más usas conservan su texto completo.

Léelo con cuidado, porque es un ciclo de retroalimentación. Una skill poco usada pierde su descripción, lo que la hace más difícil de coincidir, lo que la hace usarse aún menos. Tu skill más nicho, seguido la que más te convendría que te recordaran, es la primera en quedarse callada.

Puedes ver el estado actual: la fila de Skills en /context reporta el tamaño del listado después de aplicar el presupuesto, así que refleja lo que el modelo realmente recibe.

Depurar una skill que no se dispara

• Confirma que siquiera cargó. Un frontmatter YAML mal formado hace que el cuerpo cargue sin metadatos: invocarla por nombre sigue funcionando, pero no hay descripción contra la cual coincidir. Correr en modo debug muestra el error de parseo.
• Reformula tu pedido hacia la descripción: si así se dispara, tienes un problema de descripción, no de skill.
• Haz la descripción más específica, y pon el caso disparador primero.
• Revisa que el listado no esté desbordado con /context, y poda las skills que no usas: le están quitando espacio a las que sí.
• Ajústala con evidencia. El tooling de creación de skills puede generar prompts que deberían y no deberían dispararla, medir la tasa de acierto y proponer ediciones a la descripción.

Para llevar

Una skill que no se encuentra no está instalada, está enterrada. La descripción es el enrutador, así que escríbela para el despachador y empieza por el disparador. Y si coleccionas skills, ten presente que desbordar el presupuesto del listado quita descripciones a las menos usadas primero: justo las skills que esperabas que el agente recordara por ti.