Escribir una Descripción de Habilidad Efectiva Que Claude Active
Una Habilidad puede tener instrucciones impecables y aun así nunca ser utilizada.
//
Busca en todas las páginas de la documentación
Una Habilidad puede tener instrucciones impecables y aun así nunca ser utilizada.
Eso sucede cuando su campo description no cumple su función: decirle a Claude, de antemano, qué hace la Habilidad y cuándo se aplica.
De todo lo que hay en un archivo SKILL.md, la descripción tiene el mayor peso, porque es la única parte que Claude evalúa antes de decidir leer cualquier otra cosa.
Esta página se centra enteramente en ese único campo: qué lo hace funcionar, qué lo hace fallar y cómo diferenciar.
description, lenguaje de activación, falso positivo, falso negativo, cláusula "cuándo usar", especificidad.El campo description de una Habilidad cumple una única función: permitir que Claude decida, sin leer el resto del archivo, si esta Habilidad es relevante para la tarea en cuestión.
Esa decisión se toma en el contexto de todas las demás Habilidades disponibles en el mismo contexto. Una descripción vaga no solo corre el riesgo de no coincidir con su propia tarea, sino que corre el riesgo de perder ante una descripción más precisa de una Habilidad no relacionada, o peor aún, de coincidir con tareas para las que nunca fue diseñada.
Una descripción sólida tiene de forma fiable dos partes.
description: >-
Summarizes a customer support transcript into a structured ticket with
issue, steps taken, and resolution status. Use when the user pastes a
support conversation or asks to turn a conversation into a ticket.La primera frase indica lo que hace la Habilidad, en términos de su resultado concreto: "un ticket estructurado con problema, pasos seguidos y estado de resolución", no "ayuda con el soporte".
La segunda frase indica cuándo debe activarse, nombrando las señales reales que mostraría una tarea real: una transcripción pegada, una frase específica como "convierte esto en un ticket".
Ambas mitades importan. Una descripción con solo la mitad del "qué" le dice a Claude lo que produce la Habilidad, pero no cuándo una tarea la requiere. Una descripción con solo la mitad del "cuándo" puede activarse correctamente, pero deja a Claude adivinando qué hacer una vez dentro de la Habilidad.
Claude evalúa las descripciones de la misma manera que tú evaluarías una oferta de trabajo corta: ¿coincide esta tarea con lo que se describe, lo suficientemente de cerca como para merecer una mirada más detallada?
Eso significa que las palabras que eliges importan más de lo que podrían en prosa ordinaria. Dos direcciones de fallo aparecen repetidamente.
Activación insuficiente ocurre cuando la descripción es demasiado estrecha o abstracta para coincidir con la redacción real de una solicitud. Una descripción que dice "ayuda con el soporte" rara vez coincide con una solicitud redactada como "puedes convertir esta llamada en un ticket".
Activación excesiva ocurre cuando la descripción es lo suficientemente amplia como para coincidir con tareas para las que nunca fue diseñada. "Resume texto" como descripción se activará con gusto en un artículo de noticias, un documento legal y una transcripción de reunión por igual, incluso si las instrucciones de la Habilidad fueron escritas de forma restrictiva para uno de ellos.
Demasiado estrecha: "Formatea tickets de soporte."
Demasiado amplia: "Ayuda a organizar información de conversaciones."
Equilibrada: "Resume una transcripción de soporte al cliente en un
ticket estructurado. Usar cuando el usuario pegue una
conversación de soporte o pida convertir una conversación
en un ticket."La versión equilibrada se ancla en una forma de entrada específica (una transcripción de soporte), una forma de salida específica (un ticket estructurado) y frases de activación específicas que un usuario real escribiría o pegaría.
Una comprobación útil al redactar: lee la descripción como si fueras el autor de otra Habilidad, compitiendo por la misma tarea. ¿Ganaría claramente tu redacción frente a una Habilidad cercana y de nombre similar? Si dos descripciones en la misma biblioteca pudieran reclamar plausiblemente ambas una tarea dada, esa ambigüedad debe resolverse antes de que se envíe cualquiera de las Habilidades.
La cláusula "Usar cuando..." merece especial atención. Funciona mejor cuando nombra algo detectable en la entrada o solicitud real (un tipo de archivo, un patrón de frase, una situación descrita) en lugar de una decisión interna que solo el autor de la Habilidad reconocería.
A medida que una biblioteca de Habilidades crece, las descripciones dejan de evaluarse de forma aislada y comienzan a competir entre sí. Una descripción que estaba perfectamente bien como la única Habilidad en una carpeta puede convertirse en una fuente de confusión una vez que cinco Habilidades relacionadas se sientan a su lado.
Aquí es donde la especificidad justifica su costo. Una descripción ligeramente más larga y concreta que descarta claramente las Habilidades vecinas vale las palabras adicionales.
| Enfoque | Fortaleza | Debilidad | Mejor Ajuste |
|---|---|---|---|
| Descripción corta y general | Fácil de escribir, bajo mantenimiento | Propenso tanto a la activación excesiva como a la insuficiente a medida que la biblioteca crece | Una Habilidad solitaria sin vecinos cercanos |
| Descripción de dos partes "qué + cuándo" | Equilibra precisión con brevedad | Requiere ejemplos reales de frases de activación para escribir bien | La mayoría de las Habilidades de producción |
| Descripción larga y exhaustiva con muchos ejemplos de activación | Muy difícil de pasar por alto el activador previsto | Se lee como inflada; aún puede fallar si los ejemplos no cubren la redacción real | Habilidades de alto riesgo con un historial de activadores perdidos |
Una forma práctica de escribir la mitad del "cuándo" es recopilar dos o tres solicitudes reales que deberían activar la Habilidad, y una o dos que deliberadamente no deberían. Redacta la descripción y luego compruébala contra todas ellas. Si permite que los ejemplos de "no activar" coincidan, ajústala. Si omite uno de los ejemplos de "debería activar", amplíala o reformúlala.
Este proceso es intrínsecamente iterativo. Muy pocas descripciones son correctas en el primer borrador, y revisar una descripción después de observar que falla o se activa en exceso en una tarea real es una parte normal y esperada de la creación de una Habilidad, no una señal de que algo salió mal antes.
Las descripciones también envejecen. Una Habilidad originalmente limitada al flujo de trabajo de un equipo puede, con el tiempo, ser solicitada para manejar casos adyacentes que su descripción nunca anticipó. Revisar la descripción periódicamente, de la misma manera que revisarías cualquier pieza de documentación, mantiene la activación precisa a medida que cambian los patrones de uso reales.
Porque Claude compara la descripción con una nueva tarea antes de leer las instrucciones. Si la descripción no coincide, las instrucciones nunca se evalúan.
El patrón "Usar cuando..." funciona bien porque nombra explícitamente las condiciones de activación en lugar de dejarlas implícitas. Nombrar una señal concreta (una frase, un tipo de archivo, una situación descrita) funciona mejor que una categoría abstracta.
Claude puede elegir una u otra de manera inconsistente, o la descripción más específica puede ganar consistentemente, dejando la otra Habilidad efectivamente sin usar. Las descripciones superpuestas deben resolverse reduciendo el alcance de una o ambas.
La longitud en sí no es el problema, pero una descripción rellenada con detalles que no agudizan el "qué" o el "cuándo" añade ruido sin añadir precisión. Cada frase debe ganarse su lugar.
Versiones de Stack: Escrito contra la línea de modelos de Claude actual a partir de ~junio de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (el predeterminado) y Claude Haiku 4.5. Los nombres de los modelos, los precios y las características del producto cambian rápidamente; verifica los detalles actuales en platform.claude.com/docs antes de confiar en ellos.
Revisado por Chris St. John·Última actualización: 16 jul 2026