Anatomía de una skill: las 5 partes

Anatomía de una skill: las 5 partes

Ya conoces qué es una skill y elegiste una tarea candidata. El problema ahora es distinto: si escribes el archivo SKILL.md con una descripción vaga o instrucciones sueltas, Claude no la va a activar cuando la necesites, o la va a ejecutar distinto cada vez. Una skill bien construida tiene cinco partes fijas, y cada una cumple un trabajo específico. Esta lección te muestra cada una, con un archivo completo de ejemplo que puedes usar como plantilla mental para el tuyo.

Las cinco partes, una por una

1. El nombre. Va corto, en minúsculas y con guiones en vez de espacios: respuesta-cotizacion, no "Respuesta de Cotización" ni "RC_v2". Ese nombre identifica la carpeta y la skill dentro del sistema.
2. La descripción. Es la parte más importante de las cinco, porque es lo que Claude lee para decidir si activa la skill o no. Tiene que decir dos cosas: qué hace la skill, y cuándo usarla. Una buena fórmula es empezar con "Úsala cuando..." y describir la situación concreta que dispara la skill.
3. Las instrucciones paso a paso. El cuerpo del archivo, en Markdown: qué información necesita la skill para empezar, qué pasos sigue, qué formato debe tener la salida, y qué reglas no puede romper.
4. Los ejemplos de entrada y salida buena. Uno o dos casos completos: qué te escribió el estudiante o el cliente, y cómo se ve la respuesta correcta. Esto reduce la ambigüedad más que cualquier instrucción abstracta.
5. Los archivos de apoyo opcionales. Cuando la tarea lo necesita: una plantilla, una lista de precios, una guía de estilo, un listado de servicios. No siempre hacen falta, pero cuando existen, van en la misma carpeta que el SKILL.md.

El formato real del archivo SKILL.md

El archivo empieza con un bloque llamado frontmatter: dos líneas de tres guiones que encierran los campos name y description. Después de la segunda línea de guiones va el resto del contenido en Markdown normal. Este es el formato exacto, sin nada inventado:

---
name: respuesta-cotizacion
description: Redacta una respuesta de cotización de pintura para un
  cliente que pregunta precio de pintura interior o exterior.
  Úsala cuando el cliente pida un precio, una cotización o
  "cuánto cuesta pintar" por correo, formulario o chat.
---

# Respuesta de cotización

## Qué necesita esta skill para empezar
- Tipo de trabajo: interior, exterior o ambos
- Metros cuadrados aproximados o número de cuartos
- Ciudad del cliente (para el clima y los permisos si aplica)
- Si el cliente mencionó una fecha límite

## Pasos
1. Si falta algún dato de la lista anterior, pregunta por él
   antes de redactar la cotización.
2. Usa el rango de precios de la tabla de precios.md de esta
   carpeta según el tipo de trabajo.
3. Redacta la respuesta con esta estructura: saludo breve,
   rango de precio con una frase que aclare que es estimado,
   qué incluye la cotización (mano de obra, materiales,
   preparación de superficie), y un cierre invitando a agendar
   una visita para el precio final.
4. Deja la respuesta como borrador. Nunca la envíes tú mismo.

## Reglas que no se rompen
- Nunca prometas una fecha de inicio sin confirmar con la agenda.
- Nunca des un precio final sin visita: siempre aclara "estimado".
- Tono profesional y cercano, sin tecnicismos de pintura industrial.

## Ejemplo de entrada y salida
Entrada: "Hola, cuánto cuesta pintar el exterior de mi casa,
son como 3 cuartos de tamaño, en Phoenix"

Salida esperada: un borrador que reconoce que falta el dato de
metros cuadrados exactos, pide una foto o medida aproximada,
y mientras tanto da el rango de precio de exterior de la tabla,
aclarando que es estimado y sujeto a visita.

Fíjate en algo importante: en el frontmatter, la descripción está escrita en tercera persona ("Redacta...", "Úsala cuando..."), no como si Claude te hablara a ti. Es un campo de datos que Claude lee, no una frase de conversación.

Errores que hacen que una skill no se active o falle

El error más común, con mucha diferencia, es la descripción vaga. Si la descripción dice solo "ayuda con clientes" o "responde correos", Claude no tiene forma de saber si esta skill aplica a la tarea que le estás pidiendo, porque esa descripción también le calzaría a otras diez tareas distintas. Una descripción específica, con la situación exacta que dispara la skill, es lo que hace la diferencia entre una skill que se activa sola y una que nunca se usa.

Otros dos errores frecuentes:

• Instrucciones que contradicen el Proyecto. Si tu Proyecto dice que tu negocio nunca da precios por correo sin visita previa, y la skill dice lo contrario, Claude recibe instrucciones cruzadas y el resultado es inconsistente. Revisa que cada skill nueva respete las reglas ya definidas en el Proyecto.
• Skills que intentan hacer cinco cosas a la vez. Una skill que redacta la cotización, además agenda la visita, además hace seguimiento y además factura, es difícil de corregir cuando algo sale mal: no queda claro cuál de las cuatro partes falló. Es mejor dividirla en varias skills angostas, como vas a ver en la lección 3.6.

Ejemplo

Una empresa de pintura en Phoenix creó su primera skill con esta descripción: "ayuda con clientes". La probó pidiéndole a Claude que respondiera a un cliente preguntando por precio, y Claude nunca activó la skill: en vez de eso, respondió de forma genérica, sin seguir ni el formato ni el rango de precios que habían definido. La dueña pensó que la skill "no funcionaba", pero el problema no eran las instrucciones de adentro: era que la descripción nunca le dio a Claude una razón clara para activarla.

Reescribió la descripción siguiendo la fórmula "Úsala cuando...": "Redacta una respuesta de cotización de pintura para un cliente que pregunta precio de pintura interior o exterior. Úsala cuando el cliente pida un precio, una cotización o 'cuánto cuesta pintar' por correo, formulario o chat." Con esa descripción, la siguiente vez que un cliente escribió preguntando cuánto costaba pintar su casa, Claude reconoció la coincidencia de inmediato, activó la skill sin que nadie se lo pidiera, y siguió el formato exacto que habían definido: rango estimado, aclaración de que depende de visita, y cierre invitando a agendar.

Errores comunes

• Escribir la descripción pensando en el nombre de la skill, no en la situación del cliente. "Skill de cotizaciones" describe la skill, no cuándo usarla. "Úsala cuando un cliente pide precio" sí lo hace.
• Dejar las instrucciones incompletas asumiendo que Claude "ya sabe" el resto. Si algo no está escrito en la skill ni en el Proyecto, Claude lo va a inventar o a dejarlo genérico.
• No incluir un ejemplo de entrada y salida. Sin ejemplo, la instrucción queda abstracta; con un ejemplo, queda concreta y repetible.
• Guardar información sensible (contraseñas, datos privados de clientes) dentro del archivo SKILL.md. La skill es para el formato y el procedimiento, no para guardar datos que deberían vivir en otro lugar seguro.
• Cambiar las instrucciones y no volver a probar la skill. Un ajuste pequeño en la descripción o en los pasos puede cambiar si se activa o cómo responde: siempre se prueba de nuevo después de editar.

Tu tarea

1. Retoma la tarea candidata que elegiste en la lección 3.3.
2. Escribe, en papel o en un documento, el nombre corto de la skill (minúsculas y guiones).
3. Escribe la descripción completa, empezando por "Úsala cuando...", describiendo la situación exacta que debería disparar esta skill.
4. Escribe una lista con los datos que la skill necesita para empezar y los pasos que debería seguir.
5. Escribe un ejemplo de entrada real (algo que un cliente o tú mismo escribirían) y cómo se vería la salida correcta.