Cómo crear skills en Claude Code: la guía completa de Agent Skills

Una skill no es un prompt mejor. Es otra categoría de cosa: un módulo con nombre, referencias y comportamiento propios, que persiste en todas las sesiones sin tocar tu system prompt.

Uso trece skills en Claude Code. Cubren diseño de ofertas (el método de Alex Hormozi, destilado en 13 referencias y unos 80KB de decisiones), estrategia de SEO (la de Neil Patel), arquitectura de funnels (la de Russell Brunson), claridad al explicar (la de Feynman), revisión de guiones (la de Arthur Miller), contrarianismo financiero (el de Michael Burry) y una suite lifeos que armé para mi segundo cerebro: revisiones semanales, registro de decisiones, planificación de proyectos. Ninguna vive en mi system prompt. Se cargan cuando hacen falta y desaparecen cuando no.

Este artículo cubre el sistema completo. Los artículos enlazados profundizan en cada pieza; voy a apuntar a ellos en lugar de duplicar el detalle aquí.

¿Qué son las skills de Claude?

Una skill de Claude es un módulo de comportamiento reutilizable que Claude Code carga bajo demanda. Vive en su propio directorio, trae un archivo enrutador SKILL.md y archivos de referencia opcionales, y se activa por su descripción, no por un system prompt fijo. Las skills resuelven la deuda de prompt largo: la acumulación de instrucciones que inflan el system prompt y vuelven más lenta cada sesión, sean relevantes o no.

El artículo qué son las skills de Claude cubre la base conceptual en detalle. La versión corta: una skill es un directorio con un nombre, una descripción y un cuerpo de instrucciones que solo se carga cuando la descripción coincide con la tarea. La documentación oficial está en code.claude.com/docs/en/skills.

La deuda de prompt largo le cobra a cada sesión

Antes de las skills, el comportamiento persistente vivía en el system prompt. Una instrucción para el tono. Otra para el formato de salida. Otra para las convenciones de código. Una por cada persona que querías. Después de unos meses tenías 4.000 tokens de instrucciones cargándose en cada sesión, incluso en las que nunca tocaban la mitad.

La deuda de prompt largo crece de dos maneras. Primero, cada instrucción nueva cuesta tokens para siempre, sea relevante o no para la tarea. Segundo, el modelo atiende a todo a la vez, lo que significa que atiende a lo equivocado más o menos la mitad de las veces. Las skills rompen ese acoplamiento. Un comportamiento entra al contexto solo cuando la tarea lo pide y sale limpio cuando no. Dejas de pagar por capacidades que no estás usando.

Skills vs prompts, memoria, MCP y subagents

Una skill es un módulo persistente y reutilizable que se carga bajo demanda y sobrevive entre sesiones. Un prompt es una instrucción de sesión que se reinicia cuando termina la conversación. La memoria es contexto almacenado sin estructura ejecutable detrás. MCP es un proveedor de herramientas del lado del servidor, no un módulo de comportamiento. Cada uno resuelve un problema distinto. Confundirlos es agarrar la herramienta equivocada.

Las comparaciones que más confunden son skills vs MCP y skills vs memoria. Las dos tienen artículos propios: Skills de Claude vs MCP y subagents cubre la distinción entre herramienta y comportamiento; Skill vs prompt vs memoria tiene un árbol de decisión para el resto. Úsalos cuando la elección no sea obvia.

Prompts y memoria

1. 01Alcance de sesión: se reinicia cuando termina la conversación
2. 02Solo contexto, sin estructura ejecutable ni directorio
3. 03Carga todo en cada sesión, sea relevante o no
4. 04Sin enrutamiento interno a archivos de referencia
5. 05Se convierte en deuda de prompt largo a medida que sumas instrucciones

Skills de Claude

1. 01Persistente: el mismo comportamiento en cada sesión
2. 02Modular: SKILL.md, references/, scripts/, assets/
3. 03Se carga bajo demanda, no por defecto en cada sesión
4. 04El mapa de carga lleva al modelo a la referencia correcta
5. 05Suma capacidades sin tocar el system prompt

MCP está más cerca de una herramienta que de un módulo de comportamiento. Aporta capacidades del lado del servidor: búsqueda web, acceso a bases de datos, APIs externas. Una skill aporta una forma de pensar y ejecutar que persiste entre sesiones. Puedes correr ambos a la vez. No compiten por nada.

Los subagents son otra división: un orquestador delega una subtarea a un subagent, que corre de forma independiente. Una skill viaja dentro de un solo agente y no lanza una ejecución aparte. Si tu caso implica frentes en paralelo y agentes independientes, es un patrón de subagent. Si implica al mismo agente corriendo un comportamiento especializado en tareas recurrentes, es una skill.

Anatomía de una skill: SKILL.md, frontmatter, references/, scripts/, assets/

Un directorio de skill tiene cuatro capas. Los metadatos (nombre y descripción) identifican y disparan la skill. El cuerpo de SKILL.md aloja el mapa de enrutamiento y las instrucciones de comportamiento. El subdirectorio references/ guarda archivos de conocimiento destilado que se cargan bajo demanda. scripts/ guarda herramientas ejecutables. assets/ guarda lo que produce la skill. La guía de estructura y frontmatter de SKILL.md cubre cada campo por completo; esta sección te da el mapa.

Anatomía del directorio de una skill

• alex-hormozi/skill de persona
  • SKILL.mdenrutador// < 500 líneas, aquí vive el mapa de carga
  • references/// se carga bajo demanda, no por defecto
    • 00-canon.md// principios centrales de la oferta
    • 01-value-equation.md// precio y valor percibido
    • 02-grand-slam-offer.md// construcción de la oferta
    • 04-pricing-and-guarantees.md// precio, reversión de riesgo
    • 08-retention-and-ltv.md// retención y lifetime value
    • 11-decision-checklist.md// veredicto final de la oferta
  • scripts/// ejecutables: bash, python, etc.
    • score-offer.py// puntuación numérica
  • assets/// lo que produce la skill
    • offer-analysis.md// salida de la última ejecución

Mantén SKILL.md por debajo de 500 líneas. Cuando pasa de eso, el cuerpo asumió un trabajo que le corresponde a references/. Un SKILL.md inflado es deuda de prompt largo en un empaque más lindo. Mismo problema. El excedente va a un archivo de referencia con un nombre que refleje la decisión que apoya.

El directorio references/ es donde vive el conocimiento de la skill. Esos archivos no se cargan solos. El modelo los lee solo cuando SKILL.md se lo indica explícitamente. Esa distinción es todo el diseño.

Progressive disclosure: cómo se carga realmente una skill

Claude Code carga las skills en tres niveles. El nivel uno siempre está en contexto: el nombre y la descripción de cada skill instalada. El nivel dos se carga cuando la skill se dispara: el cuerpo completo de SKILL.md. El nivel tres se carga solo cuando SKILL.md lo indica: archivos individuales de references/. Nada en el nivel tres se carga solo. Decide el modelo, a partir de las instrucciones que escribiste. Si esas instrucciones fallan, el modelo se salta las referencias por completo.

Anthropic llama a esta arquitectura progressive disclosure. El contexto es caro y la mayor parte es irrelevante para cualquier tarea concreta. El costo del nivel uno (unos cientos de caracteres por skill) lo pagas en cada sesión. El del nivel dos, solo cuando la skill se dispara. El del nivel tres, solo cuando la tarea necesita una referencia específica.

Progressive disclosure: tres niveles de carga

1. L1

   Siempre en contexto: nombre y descripción

   El nombre y la descripción de cada skill instalada están en contexto en cada sesión. Es lo que Claude escanea para decidir si una skill es relevante. Mantén las descripciones concisas y asertivas: se escanean, no se leen. Nombre + descripción + when_to_use sumados tienen un tope de unos 1.536 caracteres en el listado de skills.

   +
2. L2

   Se carga al dispararse: el cuerpo de SKILL.md

   El cuerpo completo de SKILL.md se carga cuando la descripción coincide. Esta capa contiene las instrucciones de comportamiento de la skill, los modos de salida y (lo más importante) el mapa de carga que lleva al modelo a los archivos de referencia correctos. Menos de 500 líneas. Si se pasa, extrae el excedente.

   ## Loading map
   
   | File                              | When to load                    |
   | --------------------------------- | ------------------------------- |
   | references/01-value-equation.md   | Pricing or perceived value      |
   | references/04-pricing.md          | Price, guarantee, risk reversal |
   | references/11-decision-checklist  | Final verdict on an offer       |

   +
3. L3

   Se carga bajo demanda: archivos de referencia

   Los archivos individuales de references/ se cargan solo cuando SKILL.md le indica al modelo que los lea. Aquí nada es automático. El mapa de carga asegura la elección correcta. Escríbelo como restricción, no como sugerencia.

El problema en el nivel tres es que opcional no es obligatorio. Si SKILL.md dice “puedes consultar references/pricing.md”, el modelo lo trata como una sugerencia que puede saltarse. Si SKILL.md dice “para cualquier pregunta de precios, lee references/04-pricing-and-guarantees.md antes de escribir una sola palabra de tu respuesta”, se comporta como una restricción. La diferencia de redacción importa. Escribe las instrucciones de carga como requisitos.

La descripción lo decide todo

La descripción es el principal mecanismo de disparo de una skill. Junto con when_to_use, es lo único que Claude lee antes de decidir si activa la skill. Una skill con una descripción débil no se dispara. Queda instalada en la biblioteca, invisible, mientras Claude responde con sus pesos en lugar de tus referencias.

La documentación de Anthropic le pone nombre a esta falla: undertriggering. Las skills se activan menos de lo que deberían porque las descripciones son demasiado pasivas. “Ayuda con el análisis de ofertas” es pasiva. “Usa esta skill siempre que evalúes una oferta, un modelo de precios, una garantía, un value stack, un funnel de adquisición o una tasa de retención. Cárgala antes de escribir cualquier respuesta sobre cualquiera de esos temas” es asertiva. Las descripciones deben ser un poco insistentes. Asertivas sobre cuándo usar la skill, precisas sobre lo que hace.

Una segunda falla es usar la descripción para instrucciones. Las instrucciones van en SKILL.md. El único trabajo de la descripción es traer la skill al contexto cuando la tarea coincide. Una vez que se dispara, SKILL.md toma el control. Mezclar ambos comprime las dos funciones y ninguna sale bien.

Escribe la descripción como si le estuvieras diciendo a Claude exactamente cuándo usar esta skill. Eso es exactamente lo que estás haciendo. Nombra los tipos de tarea, las formas de entrada y los dominios de decisión que cubre la skill. Si armaste una skill de evaluación de ofertas, enumera las palabras que deberían dispararla: oferta, precio, garantía, value stack, conversión, funnel de adquisición, retención. No obligues al modelo a deducir el alcance.

Escribir referencias: divide por decisión, no por fuente

Las referencias son lo que separa una skill de un disfraz. Son el conocimiento destilado que el modelo lee en lugar de improvisar con sus pesos. El principio que rige su estructura: divide por decisión, no por fuente. Un archivo llamado book-1-chapter-4.md es un archivo muerto. Un archivo llamado pricing-and-guarantees.md es una herramienta de decisión.

La pregunta que recibe el modelo nunca llega etiquetada por fuente. Llega como un problema: un precio que no convierte, una garantía que suena débil, una oferta que el prospecto no quiere. La referencia que debe responderla es la organizada alrededor de esa decisión, no la organizada alrededor de dónde salió la información.

Mi biblioteca de skills en uso

13+

skills instaladaspersonas y herramientas de sistema

13

referencias en una skillHormozi, un archivo por dominio de decisión

80KB

conocimiento destiladolibros, charlas y playbooks en una skill de persona

0

líneas en el system promptninguna skill vive en el system prompt

En mi skill de Hormozi, los 13 archivos de referencia mapean 13 dominios de decisión: principios canónicos, la Value Equation, la construcción de la Grand Slam Offer, precios y garantías, generación de leads, cierre y ventas, retención y LTV, el modelo de contenido para adquisición y un checklist final de decisión. Cuando llega una pregunta de precios, el mapa de carga apunta a 04-pricing-and-guarantees.md. Cuando llega una de retención, apunta a 08-retention-and-ltv.md. El modelo no tiene que averiguar qué parte del corpus es relevante. El mapa lo hace. La misma estructura aplica a cada skill de la biblioteca: neil-patel, russell-brunson, gary-vaynerchuk, feynman, arthur-miller, michael-burry y la suite lifeos.

Destilar no es comprimir. Es reconstruir. Tirar tres libros en un directorio de referencias te da un disfraz más grande, no un método. Destilar significa extraer, con tus propias palabras, los principios que sostienen el peso, los frameworks que se repiten, los criterios de decisión que separan aprobado de reprobado, los ejemplos que vuelven concreta la guía abstracta y las frases de calibración que delatan cuando la skill se alejó del método. Lees mucho; te quedas solo con lo que decide.

Skills de persona: ponerle a una skill el nombre de un experto

Una skill de persona lleva el nombre de un experto reconocible y respalda ese nombre con referencias destiladas. El nombre activa una región más densa del conocimiento del modelo. “Alex Hormozi” apunta a libros, charlas, frameworks y frases en los datos de entrenamiento, mientras que “experto en marketing” apunta a un promedio. Pero el nombre solo es teatro. Las referencias son las que cargan el método.

Zheng et al. (arXiv:2311.10054, Findings of EMNLP 2024) probaron 162 personas en cuatro familias de modelos y encontraron que una etiqueta de persona sola en el system prompt no mejora la precisión factual. La propia conclusión del paper se invirtió entre versiones: de “mejora consistentemente” en noviembre de 2023 a “no mejora” en octubre de 2024, después de que los autores ampliaron la prueba. Un nombre sin método debajo es ruido. Un nombre con 13 referencias divididas por decisión y un mapa de carga es otra máquina.

El tratamiento completo (por qué el nombre rinde dentro de una skill cuando falla como etiqueta suelta, cómo destilar un corpus, cómo evitar la falla silenciosa en la que la skill corre entera con los pesos del modelo en lugar de tus referencias) está en Skills de persona en Claude Code: por qué nombrar a un experto le gana al role prompting. La versión corta: usa una persona cuando hay un corpus público real. Usa un nombre funcional (security-reviewer, api-contract-auditor, migration-planner) cuando la skill es técnica e interna y el trabajo depende de tus propios checklists, no del método de una figura pública.

Ejemplos reales: mi biblioteca de skills

Uso un enrutador SKILL.md por dominio, cada uno un módulo independiente con su propio contrato, referencias y salida esperada. Las personas cubren diseño de ofertas (Hormozi), arquitectura de funnels y value ladder (Brunson), contenido orgánico y estrategia de distribución (Gary Vaynerchuk), SEO y estrategia de keywords (Neil Patel), claridad al explicar y enseñanza desde primeros principios (Feynman), estructura dramática y revisión de guiones (Arthur Miller) y análisis macro contrarian (Michael Burry). Las skills lifeos cubren captura de tareas, revisión semanal, registro de decisiones y planificación de proyectos; usan un método destilado propio, no el de una figura pública.

Ninguna intenta hacerlo todo. Cada una tiene un trabajo de una oración. Cuando el trabajo no cabe en una oración, el alcance es demasiado amplio para construir una skill confiable a su alrededor. El artículo Ejemplos de skills de Claude: implementaciones reales de una biblioteca en uso muestra layouts de archivos concretos, estructuras de referencias y fragmentos reales de SKILL.md, incluido el formato del mapa de carga, las restricciones de modo de salida y cómo el checklist de decisión saca al modelo del “depende” genérico y lo obliga a dar un veredicto real.

Las skills que más se usan tienen descripciones asertivas, mapas de carga ajustados y referencias ancladas en decisiones. Las que rinden menos son aquellas en las que fui demasiado blando con la descripción o dejé que las referencias crecieran por fuente en lugar de por decisión. Arreglarlas sigue el mismo patrón cada vez.

Cómo probar e iterar una skill

Probar una skill es verificar que cargó sus referencias y las usó, no solo que la salida sonó plausible. La falla en la superficie se ve bien: la voz correcta, la energía correcta, una respuesta segura. Pero si el modelo corrió entero con sus pesos en lugar de tus archivos, tus referencias no aportaron nada. Destilaste 80KB de método que la skill ignoró.

El enfoque sistemático para detectar y diagnosticar esa falla está en Cómo probar skills de Claude Code: un framework de evaluación. El patrón central es comparación y cita: da la misma entrada real antes y después de instalar la skill, revisa si el framework específico de las referencias apareció en la respuesta y confirma que el modelo puede decir qué referencia le indicó qué hacer.

Chequeos mínimos de calidad de una skill

• ✓Obligatorio:
  Usa una entrada real, no un ejemplo de juguete.Una skill que solo funciona con prompts artificiales no está lista para producción.
• ✓Obligatorio:
  Compara la salida antes y después de instalar la skill.Si la salida es la misma, la skill no está sumando nada.
• ✓Obligatorio:
  Revisa si apareció el framework específico de references/.Value Equation, RAISE, Grand Slam Offer: el framework es la señal.
• ✓Obligatorio:
  Corre la misma entrada dos veces en sesiones distintas.Una salida consistente significa que la skill se cargó, no que improvisó.
• ✓Obligatorio:
  Prueba el mapa de carga directamente: haz una pregunta de precios y verifica que cargó la referencia de precios.El mapa de carga es el punto de falla más probable.
• ✓Obligatorio:
  Busca el "depende" genérico.Una skill que cargó sus referencias no se va por las ramas como un asistente genérico. Las respuestas tibias son señal de que se saltaron las referencias.
• •Opcional:
  Pídele al modelo que explique su razonamiento y cite su fuente.Si no puede nombrar la referencia, no la usó.

Iterar sigue el mismo camino de diagnóstico. Cuando una skill responde mal, rastrea la falla capa por capa: ¿se disparó la descripción? ¿Se cargó SKILL.md? ¿El mapa de carga apuntó a la referencia correcta? ¿Esa referencia tenía lo que la tarea necesitaba? Cada capa tiene un modo de falla distinto, y todos se ven idénticos desde afuera: una respuesta equivocada o genérica. La estructura en capas es lo que te permite rastrear la causa.

Cuándo construir una skill y cuándo alcanza con un prompt

Construye una skill cuando el comportamiento se repite entre sesiones y necesita una salida consistente y anclada en referencias. La señal más clara: si estás copiando y pegando el mismo bloque de instrucciones en varias sesiones, ese bloque es una skill esperando a ser construida. La segunda señal: si quieres que un conocimiento destilado específico (no solo el tono, sino frameworks y criterios de decisión reales) aparezca de forma confiable en la salida, ese conocimiento va en referencias, y las referencias van en una skill.

Quédate con un prompt cuando la tarea es puntual, las instrucciones cambian en cada ejecución o el comportamiento no necesita referencias. Solo un ajuste temporal de contexto. Los prompts son rápidos de escribir y gratis de descartar. Las skills requieren inversión: destilación, enrutamiento, pruebas. Construye la skill solo cuando la inversión se paga a lo largo de muchas sesiones.

La decisión más difícil es entre una skill y una herramienta MCP, o entre una skill y la memoria. Esas tienen matices que no se reducen a una sola regla. Skill vs prompt vs memoria: cuándo usar cada uno tiene un árbol de decisión completo y los casos específicos en los que gana cada uno.

La guía práctica: recurre a una skill cuando te descubras recreando el mismo comportamiento desde cero, cuando necesites un comportamiento que se cargue solo sin configuración manual o cuando hayas hecho un trabajo de destilación que merece persistir en lugar de evaporarse al final de la sesión.

Preguntas frecuentes

¿Qué son las skills de Claude?+

Las skills de Claude son módulos de comportamiento reutilizables que Claude Code carga bajo demanda. Cada skill vive en su propio directorio, con un enrutador SKILL.md, archivos de referencia opcionales y una descripción que la dispara. Resuelven la deuda de prompt largo manteniendo las capacidades fuera del system prompt hasta que hacen falta.

La documentación oficial está en code.claude.com/docs/en/skills.

¿Cómo creo una skill en Claude Code?+

Crea un directorio para la skill. Agrega un archivo SKILL.md con name, description, when_to_use y las instrucciones de comportamiento. Agrega un subdirectorio references/ con un archivo por dominio de decisión. Escribe un mapa de carga en SKILL.md que le diga a Claude qué referencia leer para cada tipo de pregunta.

La descripción es el disparador. Escríbela de forma asertiva para que la skill se dispare con las entradas correctas, no tímida al punto de que se la salten.

¿Qué va en SKILL.md?+

SKILL.md contiene el nombre de la skill, la descripción, el campo when_to_use, las instrucciones principales de comportamiento, las restricciones de modo de salida y el mapa de carga que lleva al modelo a archivos de referencia específicos. Mantenlo por debajo de 500 líneas. Lo que pase de eso va a un archivo de referencia.

El mapa de carga es la parte más importante. Debe nombrar archivos específicos y los tipos de pregunta que requieren cada uno. No sugerirlos: exigirlos.

¿Qué es progressive disclosure en el contexto de las skills de Claude?+

Progressive disclosure es el modelo de carga en tres niveles que Anthropic usa para las skills. El nivel uno (nombre y descripción) siempre está en contexto. El nivel dos (cuerpo de SKILL.md) se carga cuando la descripción coincide. El nivel tres (archivos de referencia individuales) se carga solo cuando SKILL.md le indica explícitamente al modelo que los lea.

Nada en el nivel tres es automático. El mapa de carga es cómo haces que el modelo busque el archivo correcto en lugar de improvisar con sus pesos.

¿Por qué importa tanto el campo description?+

Porque es la única parte de la skill que Claude lee antes de decidir si la activa. Una descripción pasiva o vaga hace que la skill se dispare menos de lo que debería (undertriggering). Se pierde, en silencio, los casos para los que fue construida.

Las descripciones deben nombrar de forma asertiva los tipos de tarea, entradas y dominios de decisión exactos que deben disparar la skill. Escríbelas como si le estuvieras diciendo a Claude exactamente cuándo usar esa herramienta, porque eso es lo que estás haciendo.

¿En qué se diferencia una skill de Claude de una herramienta MCP?+

Una herramienta MCP aporta capacidades del lado del servidor: acceso web, bases de datos, APIs externas. Una skill de Claude aporta un módulo de comportamiento: una forma de pensar y ejecutar, con referencias destiladas, que persiste entre sesiones. Puedes usar ambos a la vez. No compiten por el mismo lugar.

La comparación detallada, incluido dónde entran los subagents, está en el artículo sobre skills vs MCP y subagents.

¿Las skills de persona funcionan de verdad? Creía que el role prompting estaba desmentido.+

El role prompting solo no funciona de forma confiable. Zheng et al. (arXiv:2311.10054, Findings of EMNLP 2024) probaron 162 personas en cuatro familias de modelos y no encontraron mejora en la precisión factual con solo una etiqueta de persona. La conclusión del paper se invirtió entre la v1 y la v3 del mismo estudio.

Una skill de persona es otra arquitectura. El nombre activa un cúmulo más denso en el conocimiento del modelo, pero las referencias destiladas son las que cargan el método. Sin referencias, tienes un disfraz. Con 13 referencias divididas por decisión y un mapa de carga, tienes una skill que usa de forma consistente los frameworks reales del experto en lugar de improvisar la voz.

¿Cuántas referencias debería tener una skill?+

Tantas como decisiones distintas haya que apoyar, y ninguna más. Mi skill de Hormozi tiene 13 porque hay 13 dominios de decisión identificables en el diseño de ofertas. Una skill más acotada puede empezar con 3 a 5 archivos bien destilados.

La regla: un archivo por decisión, no un archivo por fuente. Un archivo llamado 'book-2.md' es un archivo muerto. Un archivo llamado 'pricing-and-guarantees.md' es una herramienta de decisión.

¿Cuándo debería usar una skill en lugar de un prompt?+

Usa una skill cuando el comportamiento se repite entre sesiones, tienes conocimiento destilado que va en referencias y quieres una salida consistente sin recrear el contexto a mano cada vez.

Quédate con un prompt cuando la tarea es puntual, las instrucciones cambian en cada ejecución o el comportamiento no necesita referencias. La señal más clara para construir una skill: estás copiando el mismo bloque de instrucciones en varias sesiones.