18 — Cómo crear tu propio skill

Ya tienes tu agente configurado con tu identidad, tus herramientas y tus plantillas. Este capítulo es el siguiente escalón: convertir un proceso que repites en algo que tu agente ejecuta igual todas las veces.

Eso es un skill. Y al final de este capítulo te regalo el mío para crear skills.

Qué es un skill (y qué no)

Un skill es una carpeta con instrucciones que tu agente lee cuando detecta que las necesita. No es un programa, no se instala con un ejecutable, no requiere programar. Son archivos de texto.

La diferencia con una plantilla del capítulo 14: la plantilla es un documento que tú le pasas. El skill es un procedimiento que el agente decide usar solo, cuando reconoce que la tarea encaja.

Ejemplo concreto. Cada lunes revisas tres reportes, sacas los números, los comparas contra la semana pasada y escribes un resumen. Sin skill, cada lunes le explicas el proceso otra vez. Con skill, escribes "arma el reporte semanal" y el agente ya sabe qué archivos abrir, en qué orden, y con qué formato entregarlo.

Cuándo vale la pena hacer uno

No todo merece un skill. Una carpeta más es una carpeta que hay que mantener.

Si el proceso…	Hazlo así
Se repite, tiene 3 o más pasos, y decides lo mismo cada vez	Skill
Es una regla que aplica siempre, sin pasos	Instrucciones globales (capítulo 09)
Es de una sola vez, aunque sea largo	Un prompt directo
Son datos que consultas (precios, catálogos)	Un archivo de referencia

Dos preguntas resuelven la mayoría de los casos: ¿lo vas a correr más de tres veces? Si no, es un prompt. ¿Decides lo mismo cada vez? Si cada corrida es distinta, tampoco es skill.

La estructura

Un skill bien hecho no es un archivo gigante. Es un índice que apunta a archivos pequeños:

mi-skill/
  SKILL.md              # el índice — máximo 100 líneas
  steps/1-primer-paso.md
  steps/2-segundo-paso.md
  references/tono.md    # lo que no cambia

La razón es de eficiencia: el agente lee el índice siempre, pero abre cada paso solo cuando llega a él. Un archivo de 800 líneas obliga a cargar todo el proceso para ejecutar el primer paso. Partido en pedazos, lee lo que necesita cuando lo necesita.

Las dos reglas que más importan

De todas las reglas del patrón, estas dos son las que rompen un skill cuando se ignoran.

1. El description decide si el skill se usa

Cada skill empieza con un bloque de configuración. El campo description es lo único que el agente lee siempre; el resto se carga cuando el skill ya se activó.

Si el description está mal escrito, el skill nunca dispara. No importa qué tan bueno sea por dentro.

---
name: reporte-semanal
description: >
  Arma el reporte semanal leyendo los tres reportes de ventas, compara
  contra la semana anterior y escribe el resumen ejecutivo.
  Use when: "reporte semanal", "resumen de la semana", "/reporte-semanal".
---

Debe decir qué hace y cuándo se usa. El agente hace coincidencias por significado, no por palabra exacta — pero solo si describiste bien el territorio.

2. Un paso, un archivo

No combines dos pasos "porque son cortos". Y no partas en archivo propio algo trivial como "verificar que exista la carpeta" — eso vive dentro del paso que la necesita.

El truco de la prueba

Aquí es donde casi todos se equivocan. Escribes el skill, lo pruebas tecleando /mi-skill, funciona, lo das por terminado.

Eso no es una prueba. Con el slash explícito estás forzando la invocación. Lo que quieres saber es si dispara solo.

Abre una sesión nueva y describe la tarea con tus palabras normales, sin mencionar el nombre del skill. Si se activa, quedó bien. Si no, el description está mal y hay que reescribirlo — ese es el único motivo válido para tocarlo.

La versión 1 siempre es un borrador

Tu primer skill va a tener secciones que nadie usa y le van a faltar cosas que solo aparecen con el uso real. Es normal. El skill se afina corriéndolo, no diseñándolo.

El bucle es simple, y lo puedes hacer con el propio agente:

• Mide: ¿qué molestó en la última corrida? Una pregunta que sobró, una sección que corriges a mano cada vez.
• Analiza: ¿pasó una vez o es un patrón? Si pasó dos veces, es señal.
• Actúa: dile al agente "actualiza el skill para que la próxima vez pida X".

Lo que corriges cada vez ya te está diciendo qué cambiar.

Descarga /agentiza

Todo lo de arriba está sistematizado en un skill que uso a diario y que puedes tener gratis.

/agentiza toma un proceso tuyo —un documento, la transcripción de una llamada, o simplemente tu descripción de cómo lo haces a mano— y te devuelve el skill armado: el índice, un archivo por paso, las referencias separadas, y una lista de lo que le faltó a tu proceso original.

También sirve para arreglar skills que ya crecieron sin estructura.

Hay dos formas de instalarlo, y conviene la primera:

Como plugin (se actualiza solo). Dentro de Claude Code:

/plugin marketplace add gneuman/agentiza-skill
/plugin install agentiza

Cuando yo mejore el skill, tú recibes el cambio sin hacer nada.

Como carpeta (el .zip de abajo). Si no usas plugins, descarga el archivo y copia la carpeta a ~/.claude/skills/. El README de adentro trae los comandos para Mac y para Windows. La contra: es una foto del skill al momento de bajarlo, no recibe mejoras.

Cualquiera de las dos es MIT: úsalo, modifícalo, quítale mi nombre. No pide crédito. La página completa del skill, con el detalle de qué hace en cada paso, está en gabrielneuman.com/agentiza.

Y sí, /agentiza está hecho con el mismo patrón que enseña. Puedes abrir sus archivos y ver cómo está armado por dentro — es el mejor ejemplo de referencia que te puedo dar.

Portable, no amarrado

El núcleo de un skill es markdown puro: texto plano. Si le quitas la configuración específica de Claude Code, las instrucciones siguen teniendo sentido en Codex, Cursor o Gemini.

Eso importa más de lo que parece. El trabajo que inviertes en documentar tu proceso no se pierde si cambias de herramienta el año que entra.

Para seguir leyendo

Este capítulo es el resumen operativo. Si quieres el detalle de cada pieza:

• Qué es un skill de Claude Code — cómo se ve uno por dentro, archivo por archivo, y por qué la voz importa tanto como la estructura.
• Cómo estructuro las carpetas de mis skills — el origen de este patrón y un caso real: un skill nuevo armado en 20 minutos siguiéndolo.
• Qué skill construir primero — el framework 3A para elegir, cuando tienes diez procesos y no sabes por cuál empezar.
• Las 12 reglas de un CLAUDE.md que sí funciona — la otra mitad de la configuración. El CLAUDE.md se carga siempre; el skill solo cuando aplica. Saber qué va en cada uno es la diferencia entre un agente que obedece y uno que improvisa.
• Documentar procesos en tu negocio — el paso previo. Si el proceso no está escrito, no hay nada que agentizar todavía.

Y si prefieres que alguien lo arme contigo en vez de armarlo tú: skills gratis vs. a la medida explica cuándo conviene cada uno.

---

Anterior: 17 — Solucionar problemas

Con esto cierras la guía. Tienes un agente con tu identidad, con herramientas, y ahora con la capacidad de aprender tus procesos.