Skills para programadores: extiende las capacidades de tu agente de IA

Las Skills son ficheros con instrucciones que transforman a Claude Code, Cursor, OpenCode, Copilot, Amp, Codex o cualquier agente de IA en un especialista de tu dominio. Las creas una vez y las usas para siempre.

Punto.

No hay más misterio. Pero como todo en este mundo del desarrollo, el diablo está en los detalles. Y esos detalles son los que marcan la diferencia entre un agente que te ayuda y uno que te entiende.

Lo que vas a encontrar en este artículo ¶

1. Qué son las Skills y por qué deberías prestarles atención ahora mismo
2. El concepto de Progressive Disclosure que hace que todo funcione
3. La anatomía de un archivo SKILL.md bien construido
4. Cómo instalar Skills con el CLI de Skills
5. Todos los agentes compatibles con el estándar
6. Crear tu primera Skill desde cero, paso a paso
7. Recursos adicionales: scripts, referencias y assets
8. Skills vs MCP: cuándo usar cada uno
9. Problemas comunes y cómo solucionarlos
10. Mejores prácticas para crear Skills

Qué son las Skills y por qué importan ¶

Piensa en la última vez que le pediste algo a Claude Code. Probablemente tuviste que explicarle el contexto, las convenciones de tu proyecto, cómo te gusta que estructure el código, qué herramientas prefieres…

Cada vez. Una y otra vez.

Los modelos de lenguaje funcionan mejor cuanto más claras son las instrucciones. Esto no es ningún secreto. El problema es que escribir esas instrucciones cada vez que inicias una conversación es tedioso, ineficiente y te hace perder un tiempo que podrías dedicar a cosas más interesantes.

Las Skills resuelven esto de una forma elegante.

Una Skill es una carpeta con instrucciones especializadas que tu agente de IA descubre y usa de forma automática cuando son relevantes. En lugar de explicarle a Claude cada vez cómo quieres que valide ideas de negocio o cómo debe estructurar los tests de tu proyecto, creas una Skill una vez y el agente la utiliza cuando detecta que es el momento adecuado.

La estructura básica es simple:

mi-skill/
├── SKILL.md          # Las instrucciones (requerido)
├── scripts/          # Código ejecutable (opcional)
├── references/       # Documentación adicional (opcional)
└── assets/           # Plantillas y recursos (opcional)

El archivo SKILL.md es el corazón de todo. Contiene los metadatos que le dicen al agente cuándo activar la Skill y las instrucciones que debe seguir. El resto son complementos que puedes añadir según tus necesidades.

🎯 Lo fundamental: Una Skill captura conocimiento que usas de forma repetida. Si te encuentras explicando lo mismo una y otra vez a tu agente de IA, eso debería ser una Skill.

Progressive Disclosure (Divulgación progresiva): la clave de la eficiencia ¶

Aquí viene la parte que hace que las Skills sean realmente útiles y no solo un montón de archivos de texto tirados por ahí.

El contexto de un modelo de lenguaje es un recurso limitado. Si cargaras todas las instrucciones de todas tus Skills al iniciar una conversación, pasarían varias cosas malas:

• Desperdiciarías tokens en información que no necesitas para esa tarea concreta
• El modelo tendría menos capacidad de atención para lo que importa
• El número de Skills que podrías tener estaría muy limitado

Las Skills usan un sistema de carga en tres niveles que se llama Progressive Disclosure. Funciona así:

Nivel 1 - Metadatos: Al inicio de la conversación solo se cargan los nombres y descripciones de todas tus Skills. Esto ocupa aproximadamente 100 tokens por Skill. Si tienes 50 Skills instaladas, son unos 5000 tokens. Manejable.

Nivel 2 - Cuerpo: Cuando el agente detecta que una Skill es relevante para tu tarea, carga las instrucciones completas del SKILL.md. Esto no debería superar los 5000 tokens.

Nivel 3 - Recursos: Si necesitas algo específico de los scripts, referencias o assets, se carga bajo demanda. Aquí no hay límite práctico.

Imagina que tienes una Skill para procesar PDFs y otra para escribir documentación técnica. Si le pides a Claude que extraiga datos de un PDF, solo se cargará la primera. La segunda permanece dormida, esperando su momento.

Esto es dos órdenes de magnitud más eficiente que cargar todo al inicio. Y esa eficiencia se traduce en respuestas más rápidas y precisas.

Anatomía de un archivo SKILL.md ¶

El archivo SKILL.md tiene dos partes bien diferenciadas: el frontmatter YAML con los metadatos y el cuerpo Markdown con las instrucciones.

El frontmatter ¶

---
name: pdf-processing
description: Extrae texto y tablas de archivos PDF, llena formularios, fusiona documentos. Usar cuando el usuario trabaja con PDFs o menciona formularios o extracción de documentos.
license: Apache-2.0
---

Los campos requeridos son name y description. El nombre tiene que ser único, con un máximo de 64 caracteres, usando solo minúsculas, números y guiones. Nada de espacios ni caracteres raros.

La descripción es donde se juega la partida. Este campo es el mecanismo de activación de tu Skill. El agente lee todas las descripciones y decide cuál usar según el contexto de tu petición.

Una buena descripción incluye:

• Qué hace la Skill en términos concretos
• Verbos de acción que el usuario podría usar
• Contextos específicos donde aplicarla

Compara estas dos descripciones:

Mala:

description: Ayuda con PDFs.

Buena:

description: Extrae texto de PDFs, llena formularios PDF y fusiona múltiples PDFs. Usar cuando se trabaja con documentos PDF o cuando el usuario menciona PDFs, formularios o extracción.

La primera es tan vaga que el agente nunca sabrá cuándo activarla. La segunda deja claro qué hace y cuándo usarla.

El cuerpo ¶

Después del frontmatter viene la parte de las instrucciones, escrita en Markdown normal:

# PDF Processing

## Cuándo usar esta skill

Usa esta skill cuando el usuario necesite trabajar con archivos PDF...

## Cómo extraer texto

1. Usa pdfplumber para extracción de texto...
2. Para tablas complejas, considera tabula-py...

## Cómo llenar formularios

Utiliza PyPDF2 para formularios simples...

Aquí no hay reglas estrictas sobre el formato, pero sí algunas recomendaciones que harán que tus Skills funcionen mejor:

• Sé conciso. Claude ya es inteligente. Solo añade lo que no sabe.
• Usa encabezados claros para organizar la información.
• Incluye ejemplos cuando el procedimiento no sea obvio.
• Mantén el cuerpo por debajo de las 500 líneas. Si necesitas más, usa referencias.

📝 Recuerda: El cuerpo de la Skill se carga cada vez que se activa. Todo lo que pongas ahí consume contexto. Sé generoso con la información útil y tacaño con la paja.

Instalar una Skill con el CLI de Skills ¶

Existe una forma más cómoda de gestionar Skills que copiar carpetas a mano. El CLI de Skills (npx skills) funciona como un gestor de paquetes para el ecosistema de Skills, similar a npm para JavaScript o pip para Python.

Vamos a instalar una Skill que te ayudará a descubrir otras Skills: find-skills de Vercel Labs. Es una especie de meta-Skill que enseña a tu agente a buscar e instalar Skills del ecosistema cuando detecta que podrían serte útiles.

Paso 1: Ejecutar el comando de instalación ¶

npx skills add https://github.com/vercel-labs/skills --skill find-skills

Este comando descarga la Skill desde el repositorio de GitHub y la prepara para instalar en tus agentes.

Paso 2: Seleccionar los agentes ¶

El instalador detecta qué agentes tienes configurados en tu sistema y te pregunta en cuáles quieres instalar la Skill:

◆  Select agents to install skills to (space to toggle)
│  ◼ Amp
│  ◼ Antigravity
│  ◼ Claude Code
│  ◼ Cline
│  ◼ Codex
│  ◼ Cursor
│  ◼ Gemini CLI
│  ◼ GitHub Copilot
│  ◼ Goose
│  ◼ OpenCode
│  ◼ Roo Code
│  ◼ Windsurf
│  ... (+20 más)

Usa la barra espaciadora para marcar o desmarcar cada agente. La Skill funciona de la misma manera en todos ellos gracias al estándar abierto.

Paso 3: Elegir el alcance de la instalación ¶

◆  Installation scope
│  ● Project (Install in current directory)
│  ○ Global (Install in home directory)

Tienes dos opciones:

• Project: La Skill se guarda en el directorio actual del proyecto. Puedes hacer commit de ella junto con el resto del código y compartirla con tu equipo.
• Global: La Skill queda disponible en todos tus proyectos. Útil para Skills de propósito general como esta de búsqueda.

Para find-skills tiene más sentido la instalación global, ya que querrás poder buscar Skills desde cualquier proyecto.

Paso 4: Elegir el método de instalación ¶

◆  Installation method
│  ● Symlink (Recommended)
│  ○ Copy to all agents

• Symlink: Crea un enlace simbólico. Solo hay una copia de la Skill y todos los agentes apuntan a ella. Cuando actualices, todos se actualizan.
• Copy: Copia la Skill de forma independiente a cada agente. Útil si necesitas versiones diferentes para distintos agentes, aunque es raro.

El symlink es la opción recomendada para la mayoría de casos.

Resultado de la instalación ¶

◇  Installed 1 skill to 33 agents
│
│  ✓ ~/.agents/skills/find-skills
│    symlink → Amp, Claude Code, Cursor, Codex +29 more
│
└  Done!

La Skill está lista para usar en todos los agentes que seleccionaste.

Usar la Skill para descubrir otras Skills ¶

Activar la Skill ¶

Tienes dos formas de invocarla:

Invocación directa:

/find-skills

En lenguaje natural:

Busca una skill para trabajar con React y optimización de rendimiento

El agente detectará que estás buscando capacidades adicionales y activará la Skill de forma automática.

Buscar Skills desde la terminal ¶

También puedes buscar desde la línea de comandos sin necesidad de estar en una conversación con tu agente:

npx skills find react performance

El comando devuelve resultados con el nombre de la Skill y el comando para instalarla:

Install with npx skills add <owner/repo@skill>

vercel-labs/agent-skills@vercel-react-best-practices
└ https://skills.sh/vercel-labs/agent-skills/vercel-react-best-practices

Comandos útiles del CLI ¶

El CLI de Skills tiene varios comandos que te harán la vida más fácil:

Comando	Qué hace
npx skills find [query]	Busca Skills por palabra clave
npx skills add <package>	Instala una Skill
npx skills check	Comprueba si hay actualizaciones disponibles
npx skills update	Actualiza todas las Skills instaladas
npx skills init mi-skill	Crea la estructura para una nueva Skill

El catálogo de Skills ¶

Puedes explorar las Skills disponibles en skills.sh. El catálogo muestra información sobre cada Skill: qué hace, cuántas instalaciones tiene, en qué agentes funciona y el enlace al repositorio.

🔍 Consejo: Antes de crear una Skill desde cero, busca si alguien ya ha creado algo similar. El ecosistema crece cada día y es probable que encuentres algo que cubra tus necesidades o que puedas usar como punto de partida.

Todos los agentes compatibles ¶

El estándar Agent Skills es abierto y está soportado por una lista creciente de herramientas. Estos son todos los agentes con los que puedes usar npx skills:

• Amp
• Antigravity
• Augment
• Claude Code
• Cline
• CodeBuddy
• Codex
• Command Code
• Continue
• Crush
• Cursor
• Droid (Factory AI)
• Gemini CLI
• GitHub Copilot
• Goose
• iFlow CLI
• Junie
• Kilo Code
• Kimi Code CLI
• Kiro CLI
• Kode
• MCPJam
• Mistral Vibe
• Mux
• Neovate
• OpenCode
• OpenClaude IDE
• OpenClaw
• OpenHands
• Pi
• Pochi
• Qoder
• Qwen Code
• Replit
• Roo Code
• Trae
• Trae CN
• Windsurf
• Zencoder
• AdaL

Cada agente almacena las Skills en rutas diferentes, pero el CLI de Skills se encarga de detectar cuáles tienes instalados y colocar los archivos en el lugar correcto. No tienes que preocuparte por las rutas específicas a menos que quieras hacer una instalación manual.

Crear tu primera Skill desde cero ¶

Vamos a crear una Skill para explicar conceptos técnicos de forma clara. Es un caso de uso habitual: quieres que Claude te explique algo complejo pero de manera accesible, con analogías y ejemplos.

Paso 1: Crear la estructura ¶

mkdir -p ~/.claude/skills/explainer-tecnico
cd ~/.claude/skills/explainer-tecnico

Paso 2: Crear el archivo SKILL.md ¶

touch SKILL.md

Paso 3: Escribir el contenido ¶

---
name: explainer-tecnico
description: Explica conceptos técnicos de programación, IA y tecnología de forma clara y accesible. Usar cuando el usuario pide explicar, desglosar o entender conceptos técnicos complejos.
---

# Explainer técnico

## Proceso de explicación

Antes de explicar un concepto:

1. Evaluar la audiencia: ¿Qué nivel de conocimiento previo tienen?
2. Elegir una estructura narrativa: Status quo → Problema → Solución
3. Preparar una analogía concreta del mundo real
4. Planificar ejemplos visualizables o ejecutables

## Estructura de respuesta

1. **Una línea resumen**: Qué es en términos simples
2. **Status quo**: Cómo se hacían las cosas antes
3. **El problema**: Qué limitación o necesidad existe
4. **La solución**: Cómo este concepto resuelve el problema
5. **Ejemplo concreto**: Demostración práctica
6. **Por qué importa**: Implicaciones y aplicaciones

## Reglas

- Evitar jerga técnica sin explicarla primero
- Usar analogías cotidianas
- Preferir ejemplos visualizables sobre abstractos
- Si el concepto es nuevo, investigar antes de explicar

Reinicia tu agente y prueba la Skill con algo como:

Explícame qué es reinforcement learning

El agente debería activar la Skill de forma automática y usar la estructura que definiste. Si no lo hace, revisa que la descripción contenga palabras clave relevantes como “explicar”, “entender” o “conceptos técnicos”.

Recursos adicionales: scripts, referencias y assets ¶

Las Skills más potentes no se limitan al SKILL.md. Incluyen recursos adicionales que extienden las capacidades del agente.

Scripts ¶

La carpeta scripts/ contiene código que el agente puede ejecutar. Es útil cuando necesitas operaciones deterministas o código que se repite con frecuencia.

# scripts/extract_metadata.py
# Extrae metadatos de un archivo PDF

import sys
from PyPDF2 import PdfReader

def extract_metadata(filepath):
    reader = PdfReader(filepath)
    info = reader.metadata
    return {
        "title": info.title,
        "author": info.author,
        "pages": len(reader.pages)
    }

if __name__ == "__main__":
    result = extract_metadata(sys.argv[1])
    print(result)

Referencias ¶

La carpeta references/ almacena documentación extensa que no siempre se necesita. El agente la carga bajo demanda cuando es relevante.

Por ejemplo, podrías crear un archivo references/research-methodology.md:

# Metodología de investigación

Usar esta guía cuando encuentres conceptos fuera de tu conocimiento o al explicar desarrollos recientes.

## Cuándo investigar

- El concepto fue introducido después de tu fecha de corte
- No tienes certeza sobre detalles específicos
- El usuario pide información actualizada

## Pasos de investigación

1. Buscar fuentes primarias: papers, documentación oficial
2. Verificar múltiples fuentes
3. Priorizar fuentes recientes para temas que evolucionan rápido
4. Citar las fuentes en la respuesta

Para que el agente sepa que existe este recurso, añade al final de tu SKILL.md:

## Recursos adicionales

Si el concepto es desconocido o requiere investigación, cargar [references/research-methodology.md](references/research-methodology.md) para guía detallada.

Assets ¶

La carpeta assets/ guarda archivos estáticos que se usan en la salida: plantillas de documentos, imágenes, configuraciones predefinidas.

🛠️ Cuándo usar cada recurso: Si necesitas que algo se ejecute, va en scripts. Si es documentación de consulta, va en references. Si es un archivo que forma parte del resultado final, va en assets.

Skills vs MCP: cuándo usar cada uno ¶

Existe cierta confusión entre Skills y MCP (Model Context Protocol) porque tienen funcionalidad que se solapa. Entender las diferencias te ayuda a elegir la herramienta correcta para cada situación.

Aspecto	Skills	MCP
Propósito	Enseñar al agente cómo hacer cosas	Dar acceso a herramientas y APIs
Complejidad	Baja (solo archivos Markdown)	Alta (requiere implementar servidor)
Carga de contexto	Progressive disclosure (eficiente)	Todo al inicio (~20k tokens por servidor)
Compatibilidad	Estándar abierto, múltiples agentes	Universal para cualquier LLM

Usa Skills cuando… ¶

• Quieres que Claude siga un proceso específico de tu empresa
• Tienes conocimiento de dominio: esquemas de base de datos, guías de estilo, políticas internas
• Quieres optimizar cómo el agente usa sus herramientas existentes

Usa MCP cuando… ¶

• Necesitas integraciones complejas con servicios externos como Notion, Slack o bases de datos
• La API tiene muchos endpoints y construir la integración de forma manual sería costoso
• Necesitas autenticación OAuth con servicios de terceros

Cómo funcionan juntos ¶

En una sesión típica de trabajo, el agente carga al inicio:

• El sistema base y sus herramientas
• Los metadatos de todas tus Skills (~5k tokens si tienes muchas)
• Las herramientas MCP que tengas configuradas (~20k tokens por servidor)

Cuando surge una tarea, carga el cuerpo de la Skill relevante y llama a las herramientas MCP según necesidad. Es un sistema complementario donde cada parte hace lo que mejor sabe hacer.

Problemas comunes y soluciones ¶

La Skill no se activa de forma automática ¶

Tienes que invocarla de forma manual cada vez. Esto indica que la descripción no contiene las palabras clave que coinciden con tus peticiones.

Solución: Mejora el campo description incluyendo verbos de acción que usarías de forma natural, sinónimos y variaciones, y contextos específicos de uso. Si pides “explícame X” pero la descripción solo dice “ayuda con explicaciones técnicas”, el agente puede no hacer la conexión.

El agente no encuentra archivos de referencias ¶

Aparece un error al intentar leer archivos en references/ o scripts/.

Solución: Usa rutas relativas desde la raíz de la Skill y verifica que los archivos existen donde dices que están. Un error de tipeo en el nombre del archivo es suficiente para romper todo.

La Skill consume demasiado contexto ¶

Las respuestas son lentas o se truncan cuando la Skill se activa.

Solución: Si el cuerpo de tu SKILL.md supera las 500 líneas, es hora de mover contenido a references/. El cuerpo debería contener solo lo esencial para que el agente sepa qué hacer. Los detalles van aparte.

Mejores prácticas para crear Skills efectivas ¶

Sobre el contenido ¶

Sé conciso. Claude ya es inteligente. Tu trabajo es añadir lo que no sabe, no explicarle cosas que ya domina. Si tu Skill repite información que cualquier desarrollador conoce, estás desperdiciando contexto.

Escribe buenas descripciones. Es el mecanismo de activación. Dedica tiempo a pensar cómo formularías la petición si fueras el usuario y asegúrate de que esas palabras están en la descripción.

Prueba con casos reales. No asumas que tu Skill funciona porque tiene buena pinta. Úsala durante varios días en tu trabajo diario y toma nota de dónde falla o se queda corta.

Sobre la estructura ¶

Un nivel de profundidad. Las referencias deben estar accesibles desde SKILL.md, no anidadas en subcarpetas dentro de subcarpetas.

Archivos enfocados. Es mejor tener varios archivos pequeños y específicos que uno gigante donde está todo mezclado.

Nombres descriptivos. finance-api.md le dice al agente (y a ti dentro de seis meses) de qué va el archivo. ref1.md no le dice nada a nadie.

Sobre el grado de libertad ¶

No todas las instrucciones necesitan el mismo nivel de detalle:

Situación	Grado de libertad	Formato
Múltiples enfoques válidos	Alto	Instrucciones de texto
Patrón preferido con variaciones	Medio	Pseudocódigo
Operación crítica o frágil	Bajo	Script específico

Si hay varias formas correctas de hacer algo, dale libertad al agente. Si hay una forma que debe seguirse al pie de la letra, proporciona el código exacto.

💡 Consejo final: Las Skills evolucionan. Tu primera versión no será perfecta. Crea algo que funcione, úsalo, y mejóralo basándote en la experiencia real. Es mejor una Skill imperfecta que funciona que una Skill perfecta que nunca terminas de escribir.

Crea una Skill con un solo comando ¶

Si vas a crear Skills par, existe una Skill llamada skill-creator que incluye herramientas de automatización y validación.

1. Instalar la skill oficial (hay varias con el mismo nombre, la de Anthropic es la primera)

Ejecuta esto:

npx skills add https://github.com/anthropics/skills --skill skill-creator

2. Elegirás tu agente (Claude, Cursor…) y dónde la quieres instalar (proyecto o global para todo tu ordenador)

3. Arrancas el agente y escribes

Quiero usar la skill skill-creator para crear una skill de revisión de código

O también:

/skill-creator revisión de código

Y arrancará un proceso donde verás que ejecutará ficheros en Python para desplegar la plantilla de la skill y adaptarla a tus necesidades.

Un rato más y la tendrás lista.

Conclusión ¶

Las Skills son una forma simple y potente de extender las capacidades de tu agente de IA. Capturan conocimiento que usas de forma repetida y lo ponen a disposición del agente de forma automática.

Lo esencial:

• Son carpetas con un archivo SKILL.md que contiene metadatos e instrucciones
• Usan Progressive Disclosure para ser eficientes con el contexto
• Se activan de forma automática cuando la descripción coincide con tu tarea
• Pueden incluir scripts, referencias y assets para funcionalidades avanzadas
• Son complementarias a MCP: las Skills enseñan cómo, MCP da acceso

El estándar Agent Skills es abierto y está soportado por más de 35 herramientas diferentes. Lo que crees hoy funcionará mañana en cualquier agente compatible.

Empieza con algo pequeño. Una Skill para ese proceso que repites cada semana. Pruébala, mejórala, y cuando veas los resultados, crearás más. Es la mejor forma de hacer que tu agente de IA pase de ser una herramienta genérica a convertirse en un asistente que entiende tu forma de trabajar.