¿Qué problema resuelven los skills?
Sin skills, cada conversación empieza desde cero — reescribes las mismas instrucciones, repites el mismo contexto, reformateas el mismo output. Con skills, ese trabajo se escribe una vez y se activa automáticamente cuando el contexto lo requiere. El equivalente de contratar un empleado brillante vs. reentrenarlo todos los días.
El Playbook del quarterback
Un equipo de fútbol americano tiene un playbook con 200+ jugadas organizadas por situación. El quarterback no ejecuta las 200 en cada partido — identifica la situación y carga la jugada relevante. Los skills son el playbook de Claude: todo el conocimiento existe, pero solo se carga lo necesario cuando es necesario.
- 📚 200+ jugadas disponibles
- 🎯 Activadas por situación
- ⚡ No se ejecutan todas
- 🏆 Escritas por el coach, usadas por el QB
- 📚 N skills disponibles en el proyecto
- 🎯 Activados por invocación o contexto
- ⚡ Solo se carga el relevante
- 🏆 Escritos por humanos, usados por el agente
Los skills son para Claude lo que los paquetes npm son para Node.js. En lugar de escribir código de validación de emails en cada proyecto, instalas un paquete. En lugar de instruir a Claude sobre cómo generar reportes financieros en cada sesión, instalas un skill. Conocimiento reutilizable, empaquetado, instalable, versionable.
El ecosistema de skills en números (2026)
Skills vs. otras formas de dar instrucciones
| Mecanismo | Persiste | Se activa | Costo tokens | Recomendado para |
|---|---|---|---|---|
| Prompt | No (se pierde) | Manual | Por conversación | Tareas únicas |
| CLAUDE.md | Sí (archivo) | En toda sesión | Constante siempre | Contexto del proyecto |
| Skill ← | Sí (archivo) | Por demanda/contexto | Solo al activarse | Expertise especializado |
| Agente | No (por sesión) | Por tarea | Alto (loop completo) | Autonomía compleja |
Anatomía de un Skill
Un skill es un directorio con un archivo SKILL.md obligatorio. Todo lo demás es opcional. La clave está en entender el frontmatter YAML — es el contrato entre el skill y el modelo.
Estructura del directorio
Estructura mínima (funcional)
mi-skill/
└── SKILL.md ← único requerido
Estructura completa
mi-skill/ ├── SKILL.md ← obligatorio ├── template.md ← Claude llena esto ├── examples/ │ └── sample.md ← output esperado ├── scripts/ │ └── validate.sh ← Claude ejecuta └── resources/ └── checklist.md ← referencia
Solo SKILL.md es obligatorio. Empezar simple, escalar cuando la tarea lo exige. El material de referencia detallado va en resources/ — no en SKILL.md. Así funciona Progressive Disclosure.
Anatomía de SKILL.md
Dos partes: frontmatter YAML (metadatos que Claude lee siempre) + cuerpo markdown (instrucciones que se cargan al activar).
La description es lo que Claude lee para decidir si activar el skill. Una descripción pobre = skill que nunca se activa (problema #1) o que se activa en momentos incorrectos (problema #2). Incluye: qué hace + cuándo usarlo + cuándo NO. A
Todos los campos del frontmatter
| Campo | Requerido | Descripción |
|---|---|---|
description | Recomendado | Qué hace y cuándo usarlo. Máx 1,536 chars. El más importante. |
name | No | Nombre display. Solo minúsculas, números, guiones. Máx 64 chars. |
when_to_use | No | Contexto adicional de cuándo Claude debe invocarlo. |
allowed-tools | No | Tools que Claude usa sin pedir permiso con este skill activo. |
disable-model-invocation | No | true = solo el usuario puede invocarlo (no Claude). |
user-invocable | No | false = oculto del menú /. Se activa solo automáticamente. |
model | No | Modelo específico cuando el skill está activo. |
effort | No | Nivel de esfuerzo: low, medium, high, xhigh, max. |
context | No | fork = ejecuta en subagente aislado con su propio contexto. |
paths | No | Glob patterns que limitan cuándo se activa (ej: solo en archivos .py). |
hooks | No | Hooks con scope al ciclo de vida de este skill. |
shell | No | Shell para inyección dinámica: bash (default) o powershell. |
Variables de sustitución
# Argumentos del usuario $ARGUMENTS ← todos los args pasados al invocar $ARGUMENTS[0] ← primer argumento por índice $nombre ← argumento nombrado declarado en `arguments:` # Variables del entorno de sesión ${CLAUDE_SESSION_ID} ← ID de sesión actual ${CLAUDE_EFFORT} ← nivel de esfuerzo actual ${CLAUDE_SKILL_DIR} ← directorio del skill (para leer resources/)
Inyección dinámica de contexto
La sintaxis !`comando` ejecuta comandos shell ANTES de enviar el contenido a Claude. Esto convierte el skill de texto estático a instrucciones que incorporan el estado actual del sistema. A
## Estado actual del repo !`git status --short` ## Tests que fallaron !`cat .ci/last-run.log | grep FAIL` ## Dependencies del proyecto !`npm list --depth=0 2>/dev/null | head -20`
Para comandos multilínea, usar bloque de código con ```!:
```! find . -name "*.test.ts" -newer src/api.ts ```
Progressive Disclosure — Por qué los skills escalan
Esta es la decisión de diseño más importante del sistema. Entenderla explica por qué puedes tener 50 skills sin penalizar el rendimiento del primer prompt. A — Anthropic Engineering + SwirlAI
Las 3 capas de carga
Startup de sesión — solo frontmatter
Claude lee el nombre + description de cada skill. Nada más. Si tienes 8 skills con descriptions de ~60 palabras cada una, el costo es ~500 tokens total.
Activación — SKILL.md completo
Cuando el usuario invoca /skill-name o Claude detecta relevancia, se carga el SKILL.md completo del skill específico. Solo ese skill, no todos.
Ejecución — archivos de soporte por demanda
Claude carga archivos de resources/, templates/, examples/ solo si los necesita durante la ejecución. Carga progresiva real.
Anti-patrón vs. Patrón correcto
---
description: Genera reportes financieros
---
## Instrucciones
[500 líneas de instrucciones]
## Todas las fórmulas de cálculo
[200 líneas de fórmulas]
## Ejemplos completos
[1000 líneas de ejemplos]
← TODO entra al contexto al activar
← 1700 líneas = ~25,000 tokens
← Puede llegar al límite de compactación
---
description: Genera reportes financieros según
template estándar. Usar para informe mensual,
trimestral o anual.
---
## Proceso
1. Lee datos: !`cat $ARGUMENTS`
2. Sigue template en
${CLAUDE_SKILL_DIR}/templates/reporte.md
3. Valida con
${CLAUDE_SKILL_DIR}/resources/checklist.md
## Output esperado
Ver ${CLAUDE_SKILL_DIR}/examples/ejemplo.md
← SKILL.md: ~30 líneas (~400 tokens)
← resources/ se carga SOLO si Claude llega ahí
← Escala sin límite
Regla de compactación de contexto
Cuando el contexto se acerca al límite, Claude Code compacta. Los skills que fueron invocados se re-adjuntan con un presupuesto combinado: A
→ Implicación: mantener SKILL.md < 500 líneas / < 5,000 palabras
El Estándar Abierto — Agent Skills
El 18 de diciembre de 2025, Anthropic publicó Agent Skills como estándar abierto. En 48 horas, Microsoft y OpenAI lo integraron. En marzo 2026, 32 herramientas de empresas competidoras leen el mismo SKILL.md. A
Línea de tiempo del estándar
Las 32 herramientas del ecosistema (selección)
| Herramienta | Empresa | Categoría | Ruta de skills |
|---|---|---|---|
| Claude Code | Anthropic | Terminal AI | ~/.claude/skills/ |
| Codex CLI | OpenAI | Terminal AI | ~/.codex/skills/ |
| Gemini CLI | Terminal AI | ~/.gemini/skills/ | |
| Cursor | Anysphere | IDE AI | .cursor/skills/ |
| GitHub Copilot (Agent) | Microsoft | IDE Extension | Via VS Code |
| Junie | JetBrains | IDE AI | Varía |
| Kiro | AWS | IDE AI | Varía |
| Goose | Block (Square) | Terminal Agent | Varía |
| Windsurf | Codeium | IDE AI | Varía |
| Cline / Roo Code | Comunidad | VS Code Extension | Varía |
Portabilidad real vs. features propias de Claude Code
- → Frontmatter YAML (name, description)
- → Cuerpo markdown con instrucciones
- → Templates y examples en subdirectorios
- → Argumentos básicos ($ARGUMENTS)
- →
context: fork(subagente aislado) - →
!`comando`(inyección dinámica) - →
disable-model-invocation - →
allowed-tools
Los campos de extensión son ignorados (no causan error). El skill funciona en otras herramientas, pero sin las capacidades avanzadas. Para máxima portabilidad: diseñar con el estándar base. B
Skills oficiales de empresas reales
Qué hace: Analiza y corrige automáticamente bugs detectados en GitHub Pull Requests usando los datos de error monitoring histórico de Sentry. Correlaciona el código nuevo con errores en producción — detecta bugs antes del merge.
Disponible en: Skills.sh y awesome-agent-skills.
Por qué importa: Es un skill que combina datos de una herramienta externa (Sentry) con revisión de código — sin MCP adicional, porque el skill mismo carga el contexto de Sentry via inyección dinámica.
A — Anthropic announcement Dec 2025
3 principios que publicaron:
- Skills por dominio de negocio, no por tecnología — POS crash investigation, feature flag management, oncall runbooks, API style enforcement. No un skill genérico de "debugging".
- Cada skill tiene una persona responsable — si nadie es dueño del skill, se degrada.
- Skills como documentación viva — tan útil para el agente como para un empleado nuevo.
Resultado medido: Sus agentes resuelven incidentes de POS 3x más rápido que sin skills.
A — Block Engineering Blog
Qué hicieron: Vercel creó el marketplace de facto del ecosistema de skills. Lanzado el 20 de enero 2026, alcanzó 20,000 instalaciones en las primeras 6 horas.
Por qué "el npm": Sistema de leaderboard de skills más usados, dependencias declaradas, versiones semánticas, instalación con un comando. Lo que npm hizo por Node.js, Skills.sh lo hace por los agentes.
Skills más populares (según leaderboard): daily-standup, git-summary, code-review, frontend-design (277K+ instalaciones).
A — Vercel announcement Jan 2026
7 Canales de Distribución
Los skills no se obtienen ni distribuyen por un solo canal. Existen 7 formas — cada una con sus trade-offs de velocidad, control y escala. A
Dónde viven los skills — 4 niveles de ubicación
| Nivel | Ruta | Aplica a | Prioridad |
|---|---|---|---|
| Enterprise (managed) | Admin settings | Todos los usuarios de la org | Máxima |
| Personal global | ~/.claude/skills/nombre/SKILL.md | Todos tus proyectos | Alta |
| Proyecto | .claude/skills/nombre/SKILL.md | Solo este proyecto | Media |
| Plugin | <plugin>/skills/nombre/SKILL.md | Donde el plugin esté habilitado | Namespace separado |
Regla de precedencia: Enterprise > Personal > Proyecto. Detección en vivo — agregar/editar un skill surte efecto sin reiniciar. Soporte monorepo nativo. A
Los 7 canales de distribución
📁 Carpeta .claude/skills/
Crear el directorio directamente en tu proyecto. Control total, versionado con git. Solo disponible en ese proyecto.
→ Cuándo: skills del equipo (convenciones, deploy, PR templates)
🏠 ~/.claude/skills/
Disponible en TODOS tus proyectos. Reutilización sin duplicar. No se comparte automáticamente con el equipo.
→ Cuándo: productividad personal (standup, commits, notas)
🏪 claude-plugins-official
9,000+ plugins disponibles (feb 2026). /plugin install nombre@claude-plugins-official. Actualizaciones automáticas.
→ Cuándo: funcionalidad estándar sin construirla
⭐ El npm de los skills
Marketplace de facto. 20K instalaciones en 6 horas del lanzamiento. Skills oficiales de Stripe, Sentry, Cloudflare, Figma, Atlassian, Hugging Face, Zapier.
→ Cuándo: skills de empresas conocidas, comunidad
🏢 Git repository privado
/plugin marketplace add mi-org/claude-plugins /plugin marketplace add https://gitlab.com/empresa/plugins.git /plugin marketplace add mi-org/plugins#v2.0.0
→ Cuándo: catálogo interno que no debe ser público
📦 Descarga directa
Descomprimir en la ruta correcta. Sin actualización automática. Funciona offline.
→ Cuándo: offline, compartido por email, descargado de sitios
🖥️ Interfaz gráfica
Instalación sin terminal. Para usuarios no-developer en Claude Desktop (Cowork).
→ Cuándo: equipo no técnico que no usa terminal
Tabla comparativa de canales
| Canal | Terminal requerida | Auto-update | Compartir equipo | Offline |
|---|---|---|---|---|
| Local proyecto | No | No | Sí (git) | Sí |
| Personal global | No | No | No | Sí |
| Marketplace Anthropic | Sí | Sí | N/A | No |
| Skills.sh (Vercel) ★ | Sí | Sí | Vía URL | No |
| Marketplace terceros | Sí | Configurable | Sí | No |
| ZIP manual | No | No | Manual | Sí |
| Cowork GUI | No | Sí | Vía plugins | No |
Las 7 Categorías de Skills
Cada categoría tiene formatos típicos, herramientas compatibles, y casos reales documentados de empresas que los usan en producción.
Patrones Avanzados y Control de Acceso
Subagentes aislados, pre-aprobación de herramientas, control granular de visibilidad, árbol de decisión, troubleshooting.
Ciclo de vida completo en contexto
Patrones avanzados
Árbol de decisión — ¿Necesito un skill?
Troubleshooting
| Problema | Causa probable | Solución |
|---|---|---|
| Skill no se activa solo | description sin keywords relevantes | Agregar keywords claros del dominio |
| Skill se activa demasiado | description demasiado amplia | Hacer más específica o disable-model-invocation: true |
| Description cortada | Budget de listing excedido | Reducir description o usar "name-only" |
| Skill no aparece en / | user-invocable: false | Revisar frontmatter o settings.json |
| Plugin no reconocido | Versión antigua de Claude Code | Actualizar (requiere v1.0.33+) |
| Cache corrupto | Plugin cache corrupto | rm -rf ~/.claude/plugins/cache, reiniciar |
| Skill funciona en Claude pero no en Cursor | Usa features de extensión (context: fork) | Remover features no estándar para compatibilidad |