🧩 Skills: enseñar un proceso

Una "skill" es un archivo de texto que enseña al agente a realizar una tarea que repites, como un manual de procedimientos que una empresa entrega a un empleado nuevo.

Sin una skill, vuelves a explicar el mismo proceso cada vez. Con ella, lo escribes una vez y después el agente sigue por su cuenta.

POP (procedimiento operativo estándar), reutilización, instrucción persistente.

Cada skill está en una carpeta con nombre propio, que contiene al menos un archivo SKILL.md y, opcionalmente, subcarpetas de referencia y scripts.

Entender la estructura de carpetas es el primer paso para que puedas crear (módulo 3.6) y organizar las tuyas.

Carpeta de skill, archivo raíz, subcarpetas opcionales.

Front matter es un bloque breve al inicio del archivo, entre dos líneas ---, con pares como name: e description: — es la "etiqueta" que el agente lee primero, antes de abrir el resto.

Es esta etiqueta la que decide si se llama a la skill o se ignora: el tema central del módulo 3.4.

Front matter, metadatos, encabezado estructurado.

Documentos adicionales (dentro de una subcarpeta, por ejemplo references/) con los detalles más específicos —tablas grandes, listas de errores, ejemplos largos— que el agente solo abre si la tarea lo requiere.

Mantener el SKILL.md conciso y pasar los detalles a la referencia es lo que reduce el costo de cada skill — tema del módulo 3.2.

Referencia, detalle bajo demanda, archivo profundo.

Una skill puede incluir scripts listos (Python, Node, shell) que el agente ejecuta en lugar de escribir código desde cero cada vez.

Un script integrado es más rápido y confiable que «reinventar» la lógica en cada llamada.

Script integrado, ejecución determinística, WAT — tools.

Una lectura guiada de una skill instalada de verdad: front matter, cuerpo y referencia, para ver cómo funciona su estructura completa.

Ver el ejemplo completo cierra la teoría antes de que construyas la tuya en el módulo 3.6.

Caso de estudio, anatomía aplicada.

Contexto es todo lo que el agente «tiene en la cabeza» durante una conversación: tu mensaje, el historial y los archivos abiertos. Es limitado; cuanto más lleno está, más cara y lenta se vuelve cada respuesta.

La carga progresiva existe precisamente para no llenar este espacio con skills que no se están usando.

Contexto, ventana de memoria, costo por token.

Uno token es un fragmento de texto (cerca de una palabra): la unidad que la IA usa para «leer» y cobrar. En el Nivel 1, solo el nombre y la descripción de cada skill están siempre disponibles y cuestan cerca de 100 tokens cada uno.

Es este nivel económico el que permite que el agente «sepa que la skill existe» sin cargarla entera.

Token, Nivel 1, siempre residente.

Cuando se activa el disparador (módulo 3.4), el agente abre el SKILL.md completo —el paso a paso— y solo en ese momento entra en juego ese costo mayor.

Entender esto de «solo cuando hace falta» explica por qué tener muchas skills instaladas no hace que todo vaya más lento.

Nivel 2, carga bajo demanda.

El último nivel: archivos de referencia o scripts que el agente solo abre si, durante la tarea, necesita ese detalle específico.

Es lo que permite que una skill tenga una documentación enorme sin resultar costosa la mayoría de las veces que se usa.

Nivel 3, lectura condicional.

20 skills × ~100 tokens de Nivel 1 suman cerca de 2 mil tokens fijos: poco en comparación con una ventana de contexto que admite cientos de miles.

Este número concreto disipa el miedo a «tener demasiadas skills instaladas».

Costo agregado, escala sin dolor.

Dejar las tablas grandes, las listas de errores y los ejemplos largos en las referencias, y mantener el SKILL.md como un «resumen ejecutivo» breve.

Es la directriz que aplicas al escribir tu propia skill en el módulo 3.6.

Cuerpo conciso, referencia profunda, separación de responsabilidades.

Un nombre corto y único, más la frase de «activación» que indica cuándo debe entrar en acción esa skill.

Es el primer fragmento que se lee (Nivel 1): si es débil, nunca se llama a la skill.

Nombre, activador, identificación.

Una frase que dice exactamente qué entrega la skill al terminar: "genera un informe en CSV", no "ayuda con datos".

Un objetivo vago produce una ejecución vaga; la claridad aquí evita retrabajo.

Objetivo, criterio de éxito.

La secuencia numerada de acciones que debe seguir el agente: el corazón de la skill, equivalente al «workflow» del framework WAT (Ruta 1).

Es esta lista la que garantiza la repetibilidad: la misma tarea da el mismo resultado cada vez que se llama a la skill.

Paso a paso, repetibilidad, workflow.

La lista de archivos adicionales (Nivel 3, módulo 3.2) que la skill puede consultar cuando los pasos no son suficientes.

Sin esta referencia declarada, el agente no sabe que existe ese detalle para consultarlo.

Referencia declarada, indicador de lectura.

Restricciones explícitas — lo que la skill nunca debe hacer sin confirmación, siguiendo las reglas de seguridad de la Trilha 0.6.

Una regla escrita evita que el agente «improvise» más allá de lo que autorizaste.

Regla explícita, límite de autonomía.

Un espacio reservado para anotar qué salió mal y ajustar el paso a paso — la skill no nace perfecta, se va perfeccionando.

Te prepara para el módulo 3.7, donde esta mejora continua se convierte en una práctica habitual.

Ciclo de mejora, refinamiento iterativo.

El agente compara tu solicitud con las descripciones (Nivel 1) de todas las skills disponibles y elige la que mejor encaja, como el índice temático de un libro.

Entender esta combinación explica por qué a veces no se activa la skill correcta.

Coincidencia de intención, índice de descripciones.

Una buena descripción dice "cuándo usarla" (desencadenante) y "qué hace" (resultado), con palabras que la persona realmente escribiría, no jerga interna.

Es la diferencia entre una skill que se activa sola y una que queda olvidada.

Disparador + resultado, lenguaje del usuario.

Las descripciones genéricas como «ayuda con documentos» hacen que la skill nunca se elija, porque no se distingue de las demás.

Reconocer este error es el primer paso para corregir las skills que «existen pero nunca se activan».

Descripción genérica, ambigüedad.

Dos skills con descripciones parecidas pueden confundir al agente sobre cuál elegir; eso indica que una de ellas necesita un activador más específico.

Evita rehacer el trabajo cuando ya tienes varias skills instaladas (módulo 3.5).

Superposición de activadores, desambiguación.

Pedir la misma tarea con frases diferentes («haz un resumen», «resume esto», «TL;DR de esto») y ver si la skill se activa en todos los casos.

Es la prueba real de calidad de una descripción: no basta con que funcione con la frase que escribiste primero.

Prueba de variación, robustez del disparador.

Una skill puede activarse con un comando explícito (como /nome-da-skill) o simplemente describiendo lo que quieres en lenguaje natural.

Conocer las dos opciones te ayuda a elegir cuál usar en cada momento: comando cuando quieres certeza, lenguaje natural cuando quieres fluidez.

Comando explícito, activación mediante lenguaje natural.

Una carpeta .claude/skills/ dentro del propio proyecto, guarda skills que solo existen allí, específicas de ese repositorio.

Las skills del proyecto pueden viajar junto con el código (con control de versiones), así todo el equipo hereda el mismo proceso.

Alcance del proyecto, versionado junto con el código.

Una carpeta dentro de tu carpeta personal (~ = "home") guarda skills disponibles en cualquier proyecto que abras, en cualquiera de tus computadoras.

Es donde están los procesos personales que usas siempre, sin importar en qué proyecto estés trabajando.

Alcance global, carpeta personal (home).

Regla simple: si el proceso solo tiene sentido dentro de este proyecto (p. ej., el deploy de esta app específica), va en el proyecto; si es algo que haces en cualquier lugar (p. ej., generar un resumen), va en global.

Colocarlo en el lugar equivocado es uno de los errores más comunes de quienes están aprendiendo skills —después cuesta encontrarlo.

Criterio de alcance, especificidad frente a generalidad.

Cuando existe una skill de proyecto y una global con el mismo nombre o propósito, la del proyecto normalmente prevalece en ese contexto: es más específica.

Evita sorpresas cuando esperas el comportamiento global, pero el proyecto lo sobrescribe.

Precedencia de alcance, superposición.

Cómo es la carpeta .claude/skills/ vive dentro del repositorio; hacer commit de ella permite que cada colega que clone el proyecto herede las mismas skills automáticamente.

Transforma «la forma en que lo hago» en «la forma en que lo hace el equipo» sin necesidad de reuniones.

Skill versionada, estandarización del equipo.

Con el tiempo, tu carpeta global acumula skills —conviene revisarla de vez en cuando, borrar las que ya no usas y afinar las descripciones confusas.

Prepara el terreno para el módulo 3.7, sobre cómo mantener las skills afiladas con el tiempo.

Mantenimiento, limpieza periódica.

Antes de escribir cualquier skill, elige una tarea que ya repitas manualmente; es la mejor candidata para convertirla en skill.

Una skill que resuelve un problema real es más fácil de probar y de notar sus beneficios.

Candidata a skill, tarea repetitiva.

Un bloque de comandos listo para usar que crea la carpeta y el archivo inicial de la skill, con el front matter ya completado.

Es literalmente el primer paso práctico: copiar y ejecutar elimina el «miedo a la hoja en blanco».

Estructura inicial, plantilla base.

Completar el cuerpo de SKILL.md siguiendo el framework de 6 pasos del módulo 3.3, con la tarea elegida en el tema 1.

Es donde la teoría se convierte en un archivo real y verificable.

Aplicación práctica del framework.

Abrir una conversación nueva y pedir la tarea en lenguaje natural, comprobando si realmente se activa la nueva skill.

Es el «cómo verificar» del ejercicio: sin esta prueba no sabes si la skill funciona.

Verificación del disparador, prueba manual.

Una guía de verificación: ¿descripción demasiado vaga? ¿carpeta en el lugar equivocado? ¿nombre duplicado con otra skill?

La frustración desaparece cuando tienes una lista de posibles causas para revisar, en vez de adivinar.

Diagnóstico, lista de verificación.

Con la skill funcionando, el siguiente paso natural es usarla de verdad algunas veces y observar dónde falla —apertura del módulo 3.7.

Cierra el ciclo práctico de esta ruta antes de pasar al mantenimiento continuo.

Uso real, observación, transición.

Toda skill empieza siendo imperfecta: la invocas, observas dónde se trabó, corriges el texto y la invocas de nuevo. La verdad sin adornos: suele quedar bien recién por la décima ejecución.

Sin esta expectativa, te rindes demasiado pronto pensando que la primera versión debería funcionar a la perfección.

Ciclo iterativo, expectativas realistas.

Mantener estables los nombres de archivo, las secciones y los identificadores dentro de la skill, incluso cuando cambia el contenido — evita romper las referencias cruzadas.

Una skill cuya estructura cambia todo el tiempo es difícil de mantener y depurar.

ID estable, referencia cruzada.

Cuando ya sabes que casi siempre necesitarás una referencia (Nivel 3), puedes indicarle a la skill que la cargue de inmediato, sin esperar a que el agente «descubra» que la necesita.

Ahorra una ida y vuelta cuando el Nivel 3 está prácticamente garantizado.

Precarga, anticipación de necesidades.

Uno subagente es una copia del agente abierta para encargarse de una parte aislada de la tarea y devolver solo el resumen; así, la skill puede delegar partes pesadas sin saturar el contexto principal.

Las skills complejas (por ejemplo, investigar en muchos archivos) son más ágiles y rápidas con este truco.

Subagente, aislamiento del contexto.

Desde el framework WAT de la Trilha 1: el SKILL.md es el «workflow» (los pasos), y los scripts/referencias son las «tools» (las herramientas que usa el workflow).

Conecta todo lo que aprendiste en las dos rutas: las skills no son un concepto aislado, son el WAT aplicado a un proceso específico.

Correspondencia workflow/tools, integración de rutas.

Con procesos enseñados mediante skills, el siguiente desafío es hacer que esas automatizaciones se ejecuten fuera de tu laptop —tema de la Trilha 4, Deploy.

Cierra la Ruta 3 con claridad sobre el siguiente paso del curso.

Transición de trilha.