Qué es un skill de Claude Code: cómo se ve por dentro y por qué la voz importa

Un skill de Claude Code es una carpeta que le enseña al agente a hacer una tarea de una forma específica. Adentro vive un archivo, SKILL.md, con las instrucciones del proceso. Lo defines una vez y el agente lo carga cuando lo necesita, para repetir esa tarea igual cada vez sin que se la expliques de nuevo.

La mayoría de la gente piensa en Claude Code como una caja para escribir código. La parte que casi nadie explica es esta: por dentro, un skill es texto plano que tú controlas. No es magia, es un proceso escrito. Y una vez que ves la anatomía, entiendes por qué un skill genérico y uno hecho a tu marca producen resultados tan distintos.

Te muestro qué hay adentro, sin teoría.

¿Qué es un skill de Claude Code por dentro?

Un skill es una carpeta con un nombre, y adentro un SKILL.md. Ese archivo es la receta: le dice al agente qué hacer, en qué orden y con qué reglas.

Cuando el proceso crece, el skill se parte en tres piezas:

skills/
  voz-gnb/
    SKILL.md            # el índice: qué hace y cuándo cargarlo
    references/
      banned-mx.md      # listas, reglas, ejemplos de apoyo
      anti-slop-es.md
    scripts/
      check.py          # código que el agente corre

El SKILL.md es el índice. Define el propósito del skill y los pasos del proceso, y apunta al resto del material. No metes todo ahí: si una lista de palabras prohibidas tiene 200 entradas, va en references/, no en el cuerpo principal. Así el archivo se mantiene corto y el agente carga el detalle solo cuando lo ocupa.

La carpeta references/ guarda el material de apoyo: listas, ejemplos, reglas largas, plantillas. La carpeta scripts/ guarda código que el agente ejecuta directo, como un validador o un generador. No todos los skills necesitan las tres piezas; los simples viven en un solo SKILL.md.

Lo importante es que todo es texto que tú lees y editas. No hay nada escondido.

¿Cómo se invoca un skill?

Aquí está la parte que separa un skill de un prompt guardado en un bloc de notas. No lo copias y pegas cada vez.

Cada skill lleva una descripción con sus disparadores: las frases o tareas que lo activan. El agente lee esas descripciones y, cuando lo que pides coincide, carga el skill solo. Tú describes lo que quieres en español —"escribe esto con mi voz", "pasa esta junta a tareas"— y el agente decide qué receta aplicar.

También puedes llamarlo a la mano por su nombre cuando quieres ser explícito. Pero el punto es que el proceso se carga bajo demanda. No saturas al agente con todo tu manual de operaciones; el skill correcto aparece cuando la tarea lo pide.

Eso es lo que vuelve esto escalable. Puedes tener veinte skills y el agente solo trae a la mesa el que sirve para lo que estás haciendo ahorita.

¿Qué es un agente con nombre?

Un agente con nombre es un skill, o un grupo de skills, con un rol y un nombre propio. Esa es toda la idea, y es la categoría sobre la que construyo en GNB.

Un prompt suelto es desechable: lo usas, funciona, lo pierdes. Un agente con nombre es una pieza estable de tu operación. En GNB tengo varios:

• Elias hace ventas: toma una cotización cerrada y arma el proyecto completo en la herramienta.
• Naira hace seguimiento de proyectos: registra horas, manda status updates, persigue lo que se está cayendo.
• voz-gnb escribe en mi marca: cualquier skill de contenido lo carga antes de entregar.

Ponerle nombre no es cosmético. Cuando un proceso tiene nombre, lo tratas como parte del equipo: lo mejoras, lo documentas, le ajustas las reglas cuando algo sale mal. Deja de ser un truco y se vuelve infraestructura. Si quieres ver cómo armo la carpeta de cada uno, lo detallo en cómo se estructura la carpeta de skills de Claude Code.

¿Por qué importa la voz en un skill?

Aquí está el diferenciador, y casi nadie lo menciona: un skill genérico escribe como ChatGPT.

Le pides un texto y sale correcto, gramatical y completamente olvidable. Lleno de los tics de siempre —"en el mundo de", "lleva tu negocio al siguiente nivel", "en resumen"—. Es texto de máquina. El lector lo huele en dos líneas.

voz-gnb resuelve eso cargando dos capas de reglas antes de entregar:

• banned-mx.md es mi lista regional: español de México, sin voseo, sin argentinismos. Nada de "acá", "recién", "plata" ni "laburo". Si el texto se cuela un "vos tenés", el skill lo marca.
• anti-slop-es.md es la capa anti-IA: caza los clichés que delatan a un modelo. Las frases corporativas vacías, las afirmaciones tibias, el relleno. Un texto puede pasar la regla regional y aún sonar a ChatGPT; esta segunda capa es la que lo aterriza en mi voz.

Las dos corren juntas en lo que llamo el VOICE GATE: ningún texto sale sin pasar las dos. El resultado no es "un texto en español correcto". Es un texto que suena a mí, con mis afirmaciones en presente y mis frases cortas.

Esa es la lección que más repito: la mecánica del skill es commodity. La voz es lo que nadie te puede copiar, porque sale de tu material real.

¿Qué es el bloque [CUSTOMIZE]?

Si vas a vender o entregar un skill a otra persona, necesitas que sea editable sin que abran el motor. Para eso existe el bloque [CUSTOMIZE].

Es una sección al final del SKILL.md, en YAML, con la configuración que el cliente cambia al adoptarlo. El proceso queda fijo; los datos de marca quedan abiertos. Alguien forkea el skill, edita su nombre, su lista de palabras prohibidas, su tono, y ya está corriendo su versión sin tocar la lógica.

Ese es el patrón con el que empaqueto el Skill Stack GNB, el producto que vendo: cada skill que entra al stack lleva su bloque [CUSTOMIZE]. No es decoración, es lo que vuelve un skill un producto en vez de un archivo personal. El cliente edita el YAML, no la receta.

Si te preguntas cuál construir primero, escribí una guía sobre qué skill de IA construir primero, y otra sobre cómo pasar de la idea al skill con un PRD antes de escribir una línea.

¿Por dónde empiezo a construir mi primer skill?

Empieza por el proceso que más repites a mano con reglas claras. No intentes modelar toda tu operación el primer día.

Mi recomendación concreta, en orden:

1. Elige una tarea repetitiva con reglas que ya tienes en la cabeza: redactar un tipo de correo, armar un reporte, formatear un documento.
2. Escríbela una vez como un SKILL.md. Las instrucciones del proceso, paso a paso, en texto plano.
3. Pruébala en dos o tres casos reales y ajusta. El primer borrador siempre se queda corto en algún caso; lo arreglas una vez y queda.

El error más común es arrancar por el caso más complejo, el que tiene mil excepciones. Empieza por uno aburrido y repetitivo. Ahí es donde un skill te paga rápido, porque los prompts repetidos te están costando dinero cada vez que los reescribes desde cero.

Y antes de bajar skills de un directorio gratis, vale la pena entender la diferencia entre skills gratis y skills a tu medida: la mecánica la copias, la voz no.

El siguiente paso

Un skill, por dentro, es texto que tú controlas: un SKILL.md, sus references/ y sus scripts/. La mecánica es la misma para todos. Lo que cambia el resultado es la voz que le metes y los datos de tu marca.

Si quieres ver cómo se ve un stack de agentes con nombre armado de punta a punta —Elias en ventas, Naira en seguimiento, voz-gnb cuidando cada texto— el documento El Skill Stack GNB lo explica skill por skill. Es lectura, no pitch, y lo terminas en una sentada.