Claude Code Skills en 2026: cómo crear una biblioteca de Skills propia
MarkdownCómo crear Claude Code Skills: estructura de SKILL.md, la fórmula de descripción, colecciones listas para usar de Anthropic y antipatrones. Paso a paso en 30 minutos.
Leer el artículo completo
Puntos clave
Los Claude Code Skills son carpetas que contienen un archivo SKILL.md que Claude carga en el contexto solo cuando hace falta. CLAUDE.md permanece siempre en la memoria y consume el presupuesto de tokens, mientras que un skill se carga cuando se activa un desencadenante; además, decenas de skills pueden coexistir fácilmente en un proyecto. La parte más importante de un skill es su descripción: Claude la usa para decidir si debe activarlo. En este artículo explico la estructura de SKILL.md, la fórmula de descripción, las colecciones listas para usar y cómo crear tu primer skill en 30 minutos.
Documentación de Ailoot: API, claves y configuración.
¿Qué es un skill en Claude Code y por qué no es simplemente «un prompt más grande»?
Puntos clave
Un skill es un directorio que contiene un archivo SKILL.md con instrucciones sobre cuándo y cómo aplicar una metodología específica. Anthropic compara un skill con las instrucciones para un empleado nuevo: no le dictas cada paso todos los días; le das un procedimiento para que lo aplique por su cuenta en las situaciones adecuadas. La principal diferencia con CLAUDE.md es que un skill se carga en el contexto solo cuando hace falta, por lo que pueden convivir decenas de skills en un proyecto sin agotar el presupuesto de tokens.
Claude Code Skills es una función nativa de Claude Code que Anthropic lanzó en octubre de 2025 para Pro/Max/Team/Enterprise. Más adelante, publicó la especificación Agent Skills como un estándar que también funciona fuera de Claude. En el código, no es más que una carpeta:
.claude/skills/
├── deploy-to-prod/
│ ├── SKILL.md
│ └── scripts/
│ └── check-migrations.sh
├── weekly-content-plan/
│ └── SKILL.md
└── triage-support-tickets/
└── SKILL.md
Cada carpeta corresponde a un skill. El archivo SKILL.md es un documento Markdown con metadatos YAML al principio e instrucciones normales debajo. Cuando un usuario dice «vamos a desplegar en producción», Claude ve la descripción del skill deploy-to-prod, reconoce el desencadenante «desplegar en producción», carga el cuerpo de SKILL.md en el contexto y sigue los pasos.
Tres niveles de carga progresiva
Anthropic diseñó los skills con carga progresiva: los datos se cargan por capas según haga falta. En el blog de Anthropic Engineering, el equipo lo describe como el «principio de diseño fundamental que hace que Agent Skills sea flexible y escalable» (Anthropic Engineering).
Los tres niveles de carga:
- Metadatos (siempre) - Al comenzar una sesión, Claude solo ve el
namey ladescriptionde cada skill. Presupuesto: unos 100 tokens por skill. - Instrucciones (al activarse) - Cuando el usuario dice algo pertinente, Claude carga el cuerpo de SKILL.md. Presupuesto: menos de 5000 tokens.
- Recursos (a petición) - Los archivos incluidos (ejemplos, plantillas, conjuntos de datos) se obtienen solo cuando el propio modelo los busca. Presupuesto: ilimitado.
Antes, CLAUDE.md tenía que contener todo lo que la IA debía «recordar», y un proyecto con 50 reglas alcanzaba rápidamente el límite de contexto. Con los skills, pueden coexistir fácilmente decenas en un proyecto porque, al principio, solo se incorporan sus descripciones al contexto.
Dónde se guardan los skills: cuatro niveles
| Nivel | Ruta | Se aplica a |
|---|---|---|
| Enterprise | Ajustes de organización administrados | Todos los usuarios de la empresa |
| Personal | ~/.claude/skills/<name>/SKILL.md | Todos tus proyectos |
| Proyecto | .claude/skills/<name>/SKILL.md | Solo este proyecto |
| Plugin | <plugin>/skills/<name>/SKILL.md | Donde esté habilitado el plugin |
Prioridad: Enterprise prevalece sobre los ajustes personales, y los personales sobre los del proyecto. Los plugins usan el espacio de nombres plugin-name:skill-name y no entran en conflicto. Es práctico: guarda los skills profesionales generales en ~/.claude/skills/ y los específicos de cada proyecto en .claude/skills/, dentro del repositorio.
¿Qué contiene un SKILL.md?
Puntos clave
SKILL.md es un archivo Markdown con metadatos YAML al principio e instrucciones debajo. Como mínimo, contiene dos campos: name (hasta 64 caracteres) y description (hasta 1024 caracteres). El esquema completo incluye allowed-tools, disable-model-invocation, paths, context: fork, agent y hooks. Anthropic recomienda mantener el cuerpo de instrucciones dentro de las 500 líneas y guardar todo lo demás en archivos de referencia cercanos.
Aquí tienes un ejemplo mínimo: veinte líneas y el skill está listo:
---
name: weekly-content-plan
description: Prepares a weekly post plan for a Telegram channel and Instagram. Triggers - "make a post plan", "what should I post this week", "a 7-day channel plan". Do not activate if the request is about a website or email newsletter.
---
# Weekly Content Plan
## Steps
1. Read `knowledge/audience.md` - who we're writing for
2. Read `knowledge/tone-of-voice.md` - how we write
3. Read the last 10 posts in the channel - what has already been covered
4. Come up with 7 topics for the week: 3 sales-focused, 2 expert, 2 personal
5. For each, provide one hook line and three bullets about the post
6. Output as a table: day of the week | type | hook | plan
Es suficiente. Si un usuario escribe «vamos a planificar las publicaciones de la semana», Claude ve el desencadenante en la descripción, carga SKILL.md, lee los archivos indicados y genera una tabla.
Límites que conviene tener en cuenta
La documentación oficial de la API de Claude establece límites estrictos:
name: hasta 64 caracteres; solo letras minúsculas, números y guiones, sin etiquetas XML.anthropicyclaudeestán reservados.description: hasta 1024 caracteres en la API; obligatorio, sin etiquetas XML.- Presupuesto de listado: en Claude Code, las descripciones de todos los skills ocupan en conjunto alrededor del 1 % de la ventana de contexto. Si hay muchos skills, las descripciones se truncarán y podrían desaparecer las palabras clave que Claude necesita para emparejar las solicitudes.
- Cuerpo de SKILL.md: Anthropic recomienda mantenerlo dentro de las 500 líneas. Traslada el contenido más extenso a archivos en
references/,scripts/yexamples/, y cárgalos mediante las instrucciones.
Tras la compactación del contexto (/compact), Claude conserva los primeros 5000 tokens de cada skill invocado anteriormente; el presupuesto total para todos los skills que se vuelven a adjuntar es de 25 000 tokens. Si un skill no cabe, su comportamiento se «olvida».
Esquema completo del frontmatter
Usa como mínimo name y description. Los skills de producción también utilizan otros campos:
| Campo | Propósito | Ejemplo |
|---|---|---|
name | Nombre del skill; si se omite, se usa el nombre de la carpeta | deploy-to-prod |
description | Desencadenante de la invocación automática | Consulta la fórmula más abajo |
when_to_use | Frases desencadenantes adicionales | ["deploy", "let's ship it"] |
allowed-tools | Herramientas que pueden usarse sin pedir permiso | ["Read", "Bash(npm run build)"] |
disable-model-invocation | true - solo el usuario puede invocarlo | Para operaciones peligrosas |
user-invocable | false - solo Claude puede invocarlo | Para conocimientos de fondo |
paths | Patrones glob que indican dónde está activo el skill | ["src/**/*.ts"] |
context: fork | Ejecutarlo en un subagente aislado | Cuando el contexto es extenso |
agent | Tipo de subagente que se debe iniciar | Explore, Plan, general-purpose |
effort | Nivel de razonamiento | low, medium, high, xhigh, max |
model | Modelo asignado al skill | claude-opus-4-7 |
hooks | Hooks del ciclo de vida del skill | Consulta la sección sobre hooks |
El campo disable-model-invocation: true es imprescindible para cualquier cosa que no deba ejecutarse automáticamente. Por ejemplo, un skill deploy-to-prod con esta opción solo puede invocarse si el usuario escribe explícitamente /deploy-to-prod. Sin ella, Claude podría desplegar porque «el código parece listo».
¿Por qué la descripción representa el 90 % del trabajo y cómo se redacta?
Puntos clave
La descripción es el único campo que Claude ve al principio de una sesión. Si está mal redactada, el skill no funcionará, aunque el cuerpo de instrucciones sea perfecto. Una buena descripción tiene tres partes: qué hace + frases desencadenantes entre comillas + cuándo NO se debe usar. En su propio skill-creator, Anthropic recomienda que las descripciones sean «un poco insistentes»: Claude tiende a activar los skills con menos frecuencia de la debida.
El error más común de los vibe-coders es escribir una descripción como «Ayudante para X». El skill existe físicamente en su carpeta, pero Claude no lo invoca.
Una mala descripción
description: Build dashboards.
Lo que Claude no puede saber: cuando el usuario pide «muéstrame las ventas de la semana», ¿se refiere a un panel o no? Cuando pide un «gráfico de ingresos», ¿se refiere a un panel o simplemente a un gráfico en general? Cuando pide un «informe mensual», ¿seguro que no se refiere a un panel?
El skill-creator de Anthropic expresa directamente la recomendación:
Claude tiende actualmente a activar los skills con menos frecuencia de la debida; es decir, no los usa cuando podrían ser útiles. Para contrarrestarlo, redacta las descripciones de los skills de forma un poco «insistente».
La fórmula para una buena descripción
Tres partes:
- Qué hace - una frase sobre el resultado, no el proceso. No «genera SQL», sino «exporta las ventas a una tabla para un canal de Telegram».
- Cuándo activarlo - 3-5 frases entre comillas que los usuarios realmente dicen. No adivines: revisa el historial de tus chats y de soporte.
- Cuándo NO activarlo - 1-2 frases sobre tareas similares a las que el skill no debe responder. Sin esta sección, dos skills similares seguirán entrando en conflicto.
Un ejemplo de descripción eficaz de mi proyecto (simplificado y anonimizado):
description: |
Writes and publishes an SEO guide to the blog, following the editorial policy.
Triggers: "write a guide about X", "let's make a new pillar",
"a blog article about Y", "build a blog guide about Z".
Do not activate if the request is about an email newsletter,
a Telegram post, or an internal team instruction—
those are other skills.
Lo que funciona aquí:
- El verbo «escribe y publica», en lugar de «ayuda con», especifica un resultado concreto.
- Cuatro frases desencadenantes entre comillas abarcan distintas formas de pedirlo.
- También se incluye un desencadenante en inglés: si el usuario cambia al idioma del equipo, el skill seguirá funcionando.
- Una sección independiente de «no activar si» evita conflictos con los skills de correos y publicaciones.
Cómo probar una descripción
En su skill-creator, Anthropic incorporó una metodología de evaluación de desencadenantes: 20 prompts para comprobar si un skill se activa. Diez deberían activarlo y diez no, incluidos casos muy parecidos en los que la formulación es similar, pero la tarea es distinta.
Para un vibe-coder, esto significa que, después de escribir la descripción, debe abrir un chat vacío y probar 5 frases que realmente usa, además de 3 frases parecidas que significan otra cosa. Si el skill no se activa cuando debería o se activa cuando no debería, revisa la descripción. Solo entonces redacta el cuerpo de instrucciones.
¿Qué 5 skills instalaría primero?
Puntos clave
La estrategia más rápida para un emprendedor es empezar con colecciones listas para usar y personalizarlas. Anthropic y Vercel han publicado colecciones públicas que se instalan con un solo comando y cubren tareas habituales como documentos y diseño. En mayo de 2026, el repositorio oficial anthropics/skills tenía ~138,000 estrellas.
Dedicar las dos primeras semanas a escribir tus propios skills es una estrategia perdedora. Empieza instalando algunos ya preparados y observa cómo están hechos; después, añade los tuyos siguiendo el mismo enfoque. Adaptar colecciones probadas por otras personas es más barato que construirlo todo desde cero. Estas son cinco colecciones por las que empezaría:
1. anthropics/skills - colección oficial con skill-creator
Repositorio: github.com/anthropics/skills. 138,000 estrellas en GitHub. Contiene los skills oficiales del equipo de Anthropic: skill-creator (un meta-skill que escribe otros skills), claude-api (ayuda a crear integraciones con API) y skills de documentos listos para usar en PowerPoint, Excel, Word y PDF.
Instalación con Claude Code:
/plugin marketplace add anthropics/skills
/plugin install document-skills@anthropic-agent-skills
/plugin install example-skills@anthropic-agent-skills
El principal valor es skill-creator. A partir de tu descripción, escribe un SKILL.md, ejecuta 20 evaluaciones de desencadenantes y revisa la descripción hasta que el skill empiece a activarse cuando corresponde. En esencia, es «un skill para crear skills».
2. mattpocock/skills - la colección viral de un experto en TypeScript
Contiene 12 skills activos, entre ellos:
Instalación:
npx skills@latest add mattpocock/skills
/setup-matt-pocock-skills
3. coreyhaines31/marketingskills - una colección para profesionales del marketing
Si gestionas programas en línea, trabajas como profesional independiente del marketing o diriges una agencia, no necesitas dedicar seis meses a escribir tus propios skills. La mitad de las tareas ya están preparadas.
4. vercel-labs/agent-skills - diseño sin aspecto de IA
Repositorio: github.com/vercel-labs/agent-skills. Su skill principal es web-design-guidelines; audita el código de UI según más de 100 reglas de accesibilidad, rendimiento y usabilidad.
También está frontend-design de Anthropic, con más de 110,000 instalaciones semanales. Hace que la IA elija un estilo antes de empezar a escribir código. Sin él, todas las páginas que genera Claude usan la fuente Inter, un degradado morado y tarjetas en cuadrícula. El resultado es igual para todo el mundo.
5. obra/superpowers - flujo de trabajo multiagente
En general, si instalas las tres primeras colecciones de esta lista —anthropics/skills, mattpocock/skills y coreyhaines31/marketingskills—, Claude Code tendrá decenas de skills listos para usar que cubrirán la mayoría de las tareas de un emprendedor durante el primer mes.
¿Quieres instalar skills ya preparados y también crear una configuración que convierta a Claude de verdad en tu asistente? Los skills son uno de los tres pilares de la metodología. La configuración funcional tiene tres partes: clon de IA (Skills como experiencia empaquetada) + Second Brain (una estructura de conocimientos para el contexto) + Context Engineering (cómo ve Claude el proyecto en su conjunto). Esta configuración convierte a Claude de un asistente que adivina en una herramienta que piensa con tu lógica.
¿Qué tareas repetitivas deberías convertir en un skill?
Puntos clave
La regla es sencilla: cualquier tarea que hagas más de dos veces por semana y siga aproximadamente los mismos pasos es candidata a convertirse en un skill. No un complejo «informe anual para el auditor», sino trabajo rutinario: un plan de contenido para un canal, revisar los recibos de clientes o escribir un correo de bienvenida para un participante nuevo. Un skill convierte un esfuerzo puntual en un recurso que funciona sin ti.
En trabajos para clientes y proyectos de otras personas he visto este patrón decenas de veces. Alguien tiene «esa cosa que hace desde cero cada vez». Todos los lunes escribe el mismo tipo de informe. Cada vez que llega un cliente nuevo, sigue el mismo procedimiento. Cada publicación utiliza la misma plantilla. Y cada vez tarda entre 30 y 90 minutos porque tiene que recordar los pasos, abrir los archivos adecuados y volver a formular el prompt para Claude.
La solución es reunirlo todo en un skill una vez. Después, dices una frase y Claude carga la metodología, lee las fuentes necesarias y produce el resultado. Aquí van tres ejemplos de ámbitos distintos:
Ejemplo 1. Profesional independiente del marketing - skill weekly-content-plan
Lo que hace a mano: todos los lunes prepara las publicaciones de Telegram para una semana y para tres clientes. Abre la guía de voz de marca del cliente, revisa las publicaciones recientes, piensa temas a partir del calendario de productos y prepara una tabla con frases gancho y viñetas.
Como skill, se convierte en una instrucción de cinco pasos: leer el archivo de tono de voz del cliente, leer el calendario de productos, revisar las últimas 10 publicaciones para evitar repeticiones, proponer siete temas divididos por tipo (comerciales, expertos y personales) y entregar una tabla.
La orden «vamos a planificar las publicaciones de esta semana para el cliente X» convierte una hora de preparación en tres minutos de espera. El profesional revisa el resultado, hace cambios concretos y se lo envía al cliente.
Ejemplo 2. Contable externalizado - skill monthly-receipts-close (ejemplo del autor)
Lo que hace a mano: todos los meses, para cada cliente de su cartera, exporta el extracto bancario, lo concilia con los pagos del sistema contable, marca los pagos sin clasificar, prepara un informe preliminar de ingresos y compara la estructura de los ingresos con la del mes anterior.
El skill consiste en una instrucción de seis pasos y un par de scripts de shell en la carpeta scripts/ para analizar extractos bancarios. El desencadenante «cierra mayo para el cliente X» hace que Claude genere en 4-5 minutos un informe con las anomalías señaladas.
Ejemplo 3. Creador de programas en línea - skill welcome-letter-new-participant
Lo que hace a mano: un participante nuevo ha pagado y hay que escribirle un correo de bienvenida. Un buen mensaje es personal: tiene en cuenta el canal por el que llegó, el producto que compró, a qué grupo pertenece y qué materiales hay que enviarle. Una plantilla que diga «Hola, nos alegramos» no sirve para eso.
El skill indica a Claude que lea knowledge/audience.md (quiénes son estas personas), knowledge/products/<product>.md (qué reciben) y los tres últimos correos de bienvenida (para evitar repeticiones); después, debe redactar el correo con esta estructura: gancho - detalles del producto - tres primeros pasos - despedida.
Es mucho más rápido que hacerlo a mano. La calidad es más uniforme porque Claude recuerda que debe consultar tres fuentes, mientras que una persona con prisa se salta alguna.
Qué NO debes convertir en un skill
- Tareas puntuales. Si haces algo una vez al año para presentar la declaración de la renta, basta con describírselo a Claude en el chat. Un skill compensa a partir de 3+ repeticiones.
- Tareas demasiado generales. «Ayúdame con el marketing» no es un skill: abarca todo el marketing. Un skill es «un plan de contenido semanal»: una acción específica con un resultado específico.
- Tareas sin pasos repetibles. Si el proceso cambia cada vez, no es un skill, sino trabajo puntual.
¿Cómo crear un skill de Claude Code con Skill Creator?
Puntos clave
Skill Creator es un meta-skill de Anthropic, lanzado con el comando /skill-creator. Te guía por seis pasos: borrador, prueba, evaluación, iteración, optimización y empaquetado. El resultado es un SKILL.md listo para usar, probado con 20 evaluaciones de desencadenantes (10 que deberían activarlo y 10 que no). Para alguien que no programa, es la manera más rápida de crear un primer skill funcional, sin tener que entender YAML ni discutir con Claude.
El problema es que resulta difícil escribir un buen skill a la primera. A menudo la descripción queda demasiado limitada o demasiado amplia, no incluye las frases que los usuarios realmente emplean o entra en conflicto con un skill cercano. Anthropic abordó esto publicando skill-creator, un meta-skill capaz de crear otros skills.
Después de instalar anthropics/skills, dile a Claude /skill-creator (o simplemente «vamos a crear un skill para el informe semanal») y sigue un flujo de seis etapas:
- Borrador - skill-creator hace preguntas: qué debe hacer el skill, qué frases desencadenantes debe usar, qué fuentes debe leer y qué pasos seguir. El resultado es la primera versión de SKILL.md.
- Prueba - skill-creator genera 20 prompts de prueba: 10 que deberían activar el skill y 10 que parecen desencadenantes, pero no deberían activarlo (casos muy parecidos).
- Evaluación - ejecuta cada prompt en un chat nuevo y comprueba si se activó el skill. Si se activa cuando no debería o no se activa cuando debería, señala el resultado.
- Iteración - reescribe la descripción a partir de los fallos y vuelve a ejecutar las pruebas.
- Optimización - retoque final: comprueba si se supera el límite de 1024 caracteres y si hay conflictos con los skills existentes del proyecto.
- Empaquetado - empaqueta el SKILL.md definitivo y los archivos de referencia con la estructura correcta.
En la práctica, funciona así: conversas con Claude durante 15-20 minutos, respondes a 7-8 preguntas aclaratorias y al final obtienes un skill listo para usar y probado, que se activa con los desencadenantes adecuados.
Otra ventaja es que skill-creator demuestra un estilo ejemplar para escribir un SKILL.md. Puedes abrir su propio archivo y observar el formato, el tono y la estructura de los pasos. La herramienta enseña con su propio ejemplo: al leerla, aprendes a crear tus propios skills.
Skills, CLAUDE.md, subagentes, MCP, Hooks: ¿cuál deberías usar?
Puntos clave
Claude Code tiene cinco primitivas distintas para ampliar su comportamiento, y no son intercambiables. CLAUDE.md contiene conocimientos permanentes del proyecto. Los skills son flujos de trabajo repetibles que se activan mediante desencadenantes. Los subagentes realizan tareas en paralelo en un contexto separado. MCP conecta sistemas externos (API, bases de datos). Los hooks responden automáticamente a eventos. El error más común de los vibe-coders es meterlo todo en CLAUDE.md o intentar crear un skill con un hook.
El problema más frecuente en los proyectos que he revisado es que CLAUDE.md contiene a la vez las reglas del proyecto, instrucciones paso a paso para publicar, una plantilla de commit y una descripción de la base de datos. Esto sobrecarga el contexto y tampoco funciona en la práctica: Claude no ejecuta la instrucción «cuando el usuario pida publicar» porque el modelo trata todo el contenido de CLAUDE.md como contexto general, sin desencadenantes explícitos.
La solución es asignar cada elemento a la primitiva adecuada:
| Qué | Cuándo usarlo | Ejemplo |
|---|---|---|
| CLAUDE.md | Conocimientos necesarios SIEMPRE | «El proyecto usa una lengua determinada», «no uses rayas largas en el texto», «la marca se escribe con una “o”» |
| Skills | Proceso repetible activado por un desencadenante | «Publicar en producción», «plan semanal de publicaciones», «cerrar las cuentas del cliente del mes» |
| Subagentes | Trabajo en paralelo o aislamiento de un contexto pesado | «Auditoría de seguridad mientras planifico una función nueva», «revisar el código en una sesión separada» |
| MCP | Conexión con un sistema externo | «Obtener datos del CRM», «extraer tareas del gestor», «revisar el sitio web en un navegador» |
| Hooks | Respuesta automática a un evento | «Ejecutar una comprobación después de Edit», «bloquear comandos peligrosos», «enviar una notificación de Telegram al terminar» |
En resumen, Skills y MCP cubren la mayoría de los flujos de trabajo; Hooks automatizan tareas rutinarias, como las comprobaciones de código, las pruebas y las protecciones. Los subagentes hacen falta cuando el contexto se vuelve pesado. El error más común es crear un subagente cuando lo que se necesita es un skill.
Árbol de decisión
Cuando pienses «necesito que Claude haga X»:
- ¿Es un conocimiento que se necesita todo el tiempo? Por ejemplo: «El proyecto usa una lengua determinada» o «no usamos rayas largas». → Ponlo en
CLAUDE.md. - ¿Es un procedimiento activado por una petición que ahora haces a mano? Por ejemplo: «Escribo un informe todos los lunes». → Crea un skill.
- ¿Necesitas acceder a un sistema externo? Por ejemplo, a la API de Stripe o a tu CRM. → Conecta un servidor MCP.
- ¿Claude Code debe responder automáticamente a un evento? Por ejemplo, ejecutar un linter después de cada Edit. → Escribe un hook.
- ¿La tarea es pesada, consumirá todo el contexto y necesitas hacer otra cosa en paralelo? → Ejecútala en un subagente.
El 90 % de las tareas de un emprendedor que usa vibe-coding corresponde a las categorías 1-3. Los Hooks y los subagentes son herramientas más avanzadas, útiles cuando ya has pasado de hacer «una tarea cada vez».
Los comandos slash y los skills son lo mismo
Un cambio importante de Claude Code: el antiguo sistema de comandos slash (.claude/commands/) y los skills se han fusionado en la práctica. Tanto el archivo .claude/commands/deploy.md como .claude/skills/deploy/SKILL.md crean un comando /deploy. Si los nombres coinciden, prevalece el skill. Así que, si aún usas el formato antiguo de comandos slash, pásate a los skills: la sintaxis es más clara y hay más posibilidades.
7 errores que impiden que un skill funcione
Puntos clave
Los problemas más comunes con los skills no son errores de Claude, sino errores del propio skill: una descripción sin desencadenantes, un SKILL.md sobrecargado de 2,000 líneas, dos skills parecidos que entran en conflicto o el intento de descargar «todo lo que hay en el marketplace». Cada uno de estos errores perjudica la activación o el funcionamiento del skill.
1. Una descripción sin desencadenantes: el skill no se activa
Síntoma: has escrito un skill, has comprobado la estructura y todo es válido, pero Claude no lo invoca cuando los usuarios hacen ciertas solicitudes. La causa casi siempre es la misma: una descripción como «Ayudante para escribir contenido». Claude no sabe a qué frases debe responder. Solución: incluye en la descripción, entre comillas, 3-5 frases que los usuarios realmente digan.
2. SKILL.md supera las 500 líneas: se pierde la atención
Anthropic recomienda expresamente mantener el cuerpo del archivo dentro de las 500 líneas. Si tus instrucciones tienen 2,000 líneas, Claude pierde la concentración, sigue los pasos solo parcialmente y se confunde con el orden. Solución: mueve las secciones extensas a archivos cercanos —examples/, references/, scripts/— y haz referencia a ellos desde SKILL.md.
3. Un skill para «todo lo relacionado con el contenido» en vez de tres pequeños
Una configuración tentadora: un gran skill content con publicaciones de Telegram, páginas de aterrizaje y correos electrónicos. No funciona. El skill se activa con solicitudes equivocadas, mezcla metodologías y produce un resultado promedio. Solución: un skill equivale a una acción repetible. Si realmente tienes tres rutinas de «contenido», crea tres skills: telegram-post, landing-section, email-broadcast.
4. Un skill sin una sección «Cuándo NO usarlo»: conflictos
Síntoma: hay dos skills parecidos en el proyecto y Claude invoca el incorrecto. Por ejemplo, un skill trata sobre newsletters por correo electrónico y otro, específicamente, sobre correos de bienvenida para participantes de un programa. Sin una cláusula explícita como «no activar si la solicitud trata de una lista de correo general», el skill de correos de bienvenida se activará con cualquier mención de «correo electrónico». Solución: especifica los casos negativos en la descripción.
5. 50 skills en un proyecto: las descripciones se truncan
Según la documentación de Claude Code:
Los nombres de los skills siempre se incluyen, pero si hay muchos, sus descripciones se recortan para respetar el límite de caracteres, lo que puede eliminar las palabras clave que Claude usa para emparejar tu solicitud. Presupuesto: 1 % de la ventana de contexto del modelo.
Si descargas 50 colecciones de skills de un marketplace, algunas descripciones se truncarán. Las palabras clave en las que confiabas podrían desaparecer. Solución: conserva los 10-15 skills más útiles en el proyecto activo. Guarda el resto en un archivo inactivo fuera de todos los directorios donde se descubren skills, por ejemplo una carpeta skill-archive/ en tus materiales. Instala solo las necesarias en el ámbito del proyecto o personal. ~/.claude/skills/ es una biblioteca personal instalada visible entre proyectos; moverlas allí no las elimina del descubrimiento.
6. Skills de fuentes no verificadas: riesgo para la seguridad
Anthropic advierte de esto en la documentación oficial:
Usa skills solo de fuentes fiables: los que hayas creado tú o hayas recibido de Anthropic. Un skill malicioso puede hacer que Claude invoque herramientas o ejecute código de maneras distintas al propósito declarado del skill.
Un repositorio cualquiera de GitHub puede contener un skill que filtre tus claves API la primera vez que lo invoques. Solución: abre SKILL.md y léelo tú mismo antes de instalarlo. No ejecutes skills de autores desconocidos en proyectos importantes.
7. Un skill sin carpeta de conocimientos produce un «ChatGPT promedio»
Es el antipatrón más sutil y común. Un skill es una metodología, pero sin contexto la metodología no sirve de mucho. Si escribes un skill para «redactar un correo de bienvenida», pero el proyecto no tiene un archivo que describa a la audiencia ni otro sobre la voz de marca, Claude redactará un correo promedio de ChatGPT, indistinguible de los de cualquier otra persona.
Un skill funciona mejor cuando ya has creado el Second Brain del proyecto siguiendo los principios de la guía sobre CLAUDE.md. Primero construye la estructura de conocimientos y después crea skills que dependan de ella. Si inviertes el orden, obtendrás un trabajo rutinario y de calidad promedio en vez de un trabajo personalizado a tu estilo.
Cómo crear tu primer skill en 30 minutos
Puntos clave
Una receta paso a paso para crear tu primer skill funcional: elige una acción repetible, escribe los pasos, crea la estructura de carpetas, redacta la descripción con la fórmula, pruébalo con 5-8 prompts y repite hasta que se active cuando corresponde. Un plazo realista para el primer skill es de 30-40 minutos. Cada uno de los siguientes lleva 10-15 minutos, porque el formato ya resulta familiar.
Este es el plan concreto que utilicé para crear los primeros skills de mis proyectos:
Paso 1. Elige una acción repetible
Abre tu calendario del último mes. Busca una tarea que hayas hecho al menos 4-5 veces y que te lleve entre 30 y 60 minutos cada vez. No algo amplio como «marketing», sino algo específico: «informe de ventas del lunes», «incorporación de un cliente nuevo» o «actualización de la lista de precios para una promoción».
Cuanto más concreta sea la formulación, más sencillo será el skill y más claro el desencadenante.
Paso 2. Escribe el proceso a mano
En un archivo aparte o en un chat con Claude (todavía no para el skill, sino como borrador), escribe los pasos que sigues:
1. Open the client database
2. Filter by status "awaiting welcome email"
3. Check which channel the client came from
4. Get the email template for that channel from the "templates" folder
5. Fill in the name, product, and start date
6. Send
Esto todavía no es un skill, sino una nota. Pero sin estas notas, te confundirás desde el principio al escribir SKILL.md.
Paso 3. Crea la estructura de carpetas
mkdir -p .claude/skills/welcome-email-new-client
touch .claude/skills/welcome-email-new-client/SKILL.md
O, si quieres usar el skill en todos tus proyectos, guárdalo en ~/.claude/skills/.
Paso 4. Escribe SKILL.md usando la plantilla
Esqueleto:
---
name: welcome-email-new-client
description: |
Prepares a welcome email for a new client using the template for their acquisition channel.
Triggers: "write a welcome email for new client X",
"onboard new participant Y", "welcome email for client from channel Z".
Do not activate if the request is about a general mailing list
or an email campaign—those are other skills.
---
# Welcome Email for a New Client
## Steps
1. Read `knowledge/audience/segments.md` - what client segments we have
2. Read `knowledge/templates/welcome/` - templates by channel
3. Identify the client's channel from the request context
4. Insert the client's name, product name, and start date
5. Check the length—it should be no more than 800 characters
6. Output the final email text in a copy-ready format
## Important
- Do not use “dear friend” or “hello”—use natural speech
- One paragraph, one idea
- End with one call to action, not two
Paso 5. Prueba con 5-8 prompts
Abre un chat en blanco con Claude Code en este proyecto. Prueba 5 frases que utilices de verdad y otras 3 parecidas que no deberían activar el skill:
Deberían activarlo:
- “Write a welcome email for new client Ivanov”
- “Onboard a new participant who bought program X”
- “Welcome email for a client from Instagram”
No deberían activarlo:
- “Send a promotion email to the whole list”
- “Email campaign for the New Year holidays”
- “Write a follow-up to a client who hasn't paid”
Comprueba si el skill se activó para cada una. Si se activa en casos incorrectos, acota la descripción. Si no se activa cuando debería, amplía las frases desencadenantes.
Paso 6. Revisa la descripción
Después de cada prueba fallida, edita solo la descripción; no toques el cuerpo de instrucciones. Tras 2-3 iteraciones, el skill empezará a activarse de forma fiable. Guárdalo, haz un commit y úsalo a diario.
Consejo final: no intentes que tu primer skill sea perfecto. Haz que funcione. Ya lo perfeccionarás después de crear el quinto o el décimo, cuando empieces a ver patrones en tus formulaciones y en las respuestas de Claude.
Elige una tarea recurrente de tu calendario para esta semana, reserva 30 minutos y sigue los seis pasos anteriores. Así, Claude trabajará según tu metodología en vez de adivinar.
Fuentes
- Amplía Claude con skills - Documentación de Claude Code
- Descripción general de Agent Skills - Documentación de Claude Platform
- Cómo equipar a los agentes para el mundo real con Agent Skills - Blog de Anthropic Engineering
- anthropics/skills - repositorio oficial con skill-creator
- Skill Creator SKILL.md - fuente de la metodología de evaluación de desencadenantes
- vercel-labs/agent-skills - directrices de diseño
- Estándar abierto Agent Skills - especificación
La configuración funcional es clon de IA + Second Brain + Context Engineering. Tres partes de una misma metodología.
Si necesitas acceder a modelos de IA a través de Ailoot, visita Ailoot.
Más detalles
Preguntas sobre Claude Code
¿Mover una skill a ~/.claude/skills/ la vuelve inactiva?
No. Ese directorio es el ámbito personal instalado y la hace disponible en todos tus proyectos. Guarda los paquetes sin usar en un archivo fuera de todos los directorios de descubrimiento e instala solo los necesarios ahora.
¿Cómo compruebo si una descripción activa la skill correctamente?
Prueba cinco frases que deban invocarla y tres peticiones parecidas que no. Utiliza chats nuevos, registra qué skill se carga y ajusta la descripción si omite una petición real o coincide con una similar incorrecta.