Escribir una Descripción de Habilidad Efectiva Que Claude Active
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.
Resumen
- Idea Central: La descripción de una Habilidad es una señal de coincidencia, no documentación; Claude la compara con la tarea actual para decidir si cargar o no la Habilidad.
- Por Qué Importa: Una Habilidad con excelentes instrucciones y una descripción vaga se comporta igual que ninguna Habilidad, porque nunca se activa.
- Conceptos Clave: campo
description, lenguaje de activación, falso positivo, falso negativo, cláusula "cuándo usar", especificidad. - Cuándo Usar: Recurre a esto siempre que una Habilidad no se active cuando debería, se active cuando no debería, o estés redactando el frontmatter de una Habilidad completamente nueva.
- Limitaciones / Compensaciones: Una descripción demasiado amplia se activa en exceso; una demasiado estrecha se activa en defecto. No existe una redacción "correcta" única, solo un ajuste mejor o peor para el rango de tareas reales que esperas.
- Temas Relacionados: Frontmatter de SKILL.md, estructuración de instrucciones paso a paso, errores comunes en el descubrimiento de Habilidades, cómo Claude descubre y carga Habilidades.
Fundamentos
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.
Mecánica e Interacciones
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.
Consideraciones Avanzadas y Aplicaciones
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.
Conceptos Erróneos Comunes
- "El nombre de la Habilidad hace la mayor parte del trabajo de descubrimiento." - La descripción lleva casi todo el peso. Un nombre preciso con una descripción vaga aún no se activará de manera fiable.
- "Una descripción más larga es siempre una descripción más segura." - La longitud no es la variable que importa; la especificidad sí lo es. Una descripción larga pero vaga aún puede activarse en exceso o en defecto.
- "Solo necesito indicar lo que hace la Habilidad; Claude descubrirá cuándo usarla." - Sin un "cuándo" explícito, Claude tiene que inferir las condiciones de activación solo del "qué", lo cual es mucho menos fiable que indicarlas directamente.
- "Si una Habilidad no se activa, las instrucciones necesitan trabajo." - Un activador perdido es casi siempre un problema de descripción. Las instrucciones nunca se leen si la descripción no coincide primero.
- "Una descripción más amplia significa que la Habilidad será más útil." - El lenguaje amplio es más propenso a causar activación excesiva en tareas no relacionadas que a hacer que la Habilidad sea "más disponible" de una buena manera.
Preguntas Frecuentes
¿Cuáles son las dos cosas que una buena descripción de Habilidad debe indicar?
- Lo que hace realmente la Habilidad, en términos de su resultado concreto.
- Cuándo debe activarse, usando un lenguaje que coincida con cómo se formularía una solicitud real.
¿Por qué la descripción importa más que las instrucciones?
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.
¿Qué significa "activación insuficiente"?
- Una Habilidad no se activa en una tarea que en realidad estaba destinada a manejar, generalmente porque la descripción es demasiado estrecha o abstracta para coincidir con la redacción real de la solicitud.
¿Qué significa "activación excesiva"?
- Una Habilidad se activa en tareas para las que no fue diseñada, generalmente porque la descripción es lo suficientemente amplia como para coincidir con solicitudes no relacionadas.
¿Existe un patrón fiable para la parte "cuándo" de una descripción?
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.
¿Cómo pruebo si una descripción está bien escrita?
- Recopila algunas solicitudes reales que deberían activar la Habilidad y algunas que no deberían.
- Comprueba la descripción del borrador contra todas ellas.
- Ajústala si coincide un ejemplo de "no activar"; amplíala o reformúlala si se omite un ejemplo de "debería activar".
¿Debería una descripción mencionar herramientas específicas o nombres de archivo que la Habilidad usa internamente?
- No. La descripción trata sobre la tarea y el activador, no sobre detalles de implementación. Los detalles internos pertenecen al cuerpo de las instrucciones, no a la descripción.
¿Qué sucede si dos Habilidades en la misma biblioteca tienen descripciones superpuestas?
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.
¿Es normal revisar una descripción después de que la Habilidad ya está en uso?
- Sí. Muy pocas descripciones son correctas en el primer borrador, y revisar una después de observar un activador perdido o falso es un paso normal y esperado, no una señal de un fallo de diseño.
¿Puede una descripción ser demasiado larga?
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.
¿La descripción necesita usar las palabras exactas que un usuario escribiría?
- No exactamente, pero debería ser lo suficientemente cercana en significado y redacción como para que las solicitudes reales coincidan reconociblemente con ella. Un lenguaje demasiado formal o abstracto, aunque sea técnicamente preciso, puede pasar por alto cómo la gente pregunta realmente.
Relacionados
- Fundamentos de Diseño y Empaquetado de Habilidades - donde el campo de descripción aparece por primera vez en un ejemplo práctico.
- Cómo se Une una Habilidad: De la Idea al Paquete - la ruta completa en la que se enfoca esta página.
- Estructurar Instrucciones Paso a Paso Que Claude Pueda Seguir de Forma Fiable - lo que sucede una vez que la descripción tiene éxito.
- Errores Comunes Que Hacen Que una Habilidad Sea Difícil de Encontrar o Usar para Claude - una lista más amplia de fallos de activación.
- Cómo Claude Descubre y Carga Habilidades Automáticamente - el mecanismo para el cual se escriben los consejos de esta página.
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.