Claude Code Skills: cómo extender al agente con instrucciones reutilizables

A finales de 2025 Anthropic introdujo en Claude Code una primitiva llamada Skill: una carpeta con un SKILL.md que el agente puede cargar bajo demanda para hacer cosas que su conocimiento general no sabe hacer bien. En 2026 las Skills son la forma principal de extender Claude Code más allá de prompts y MCPs.

Esta guía explica qué son las Skills, cómo se crean, cuándo usar una Skill en vez de un MCP server o un slash command, y los errores típicos al adoptarlas. Forma parte del cluster Claude Code por dentro.

Qué es una Skill

Una Skill es una unidad de conocimiento ejecutable que se puede entregar a Claude bajo demanda. Estructura mínima:

my-skill/
  SKILL.md       # instrucciones principales (obligatorio)
  templates/     # plantillas que Claude rellena (opcional)
  scripts/       # scripts que Claude puede ejecutar (opcional)
  references/    # docs detalladas que Claude consulta (opcional)
  examples/      # ejemplos de output esperado (opcional)

El SKILL.md lleva un frontmatter:

---
name: my-skill
description: Cuándo usar esta skill — descripción precisa que Claude consulta para decidir si activarla.
---

# Cómo hacer X

Pasos detallados, decisiones de diseño, output esperado.

Cuando el usuario pide algo que matchea con la description, Claude carga el SKILL.md en contexto y ejecuta lo que dice.

El insight: just-in-time loading

Las Skills resuelven un problema de context engineering (detalle aquí): no quieres meter 50K tokens de instrucciones especializadas en cada prompt si el usuario no las necesita.

Una Skill bien escrita:

1. Tiene description corta y precisa que Claude evalúa por defecto (cabe en system prompt).

2. Solo se carga el contenido completo cuando Claude decide que aplica.

3. Templates, scripts, references se cargan a su vez bajo demanda dentro de la Skill.

Resultado: agentes con cientos de Skills disponibles consumen menos tokens que agentes con un system prompt monolítico.

Skills vs MCP vs slash commands

Tres primitivas, distinto propósito:

Ejemplo concreto: "publicar un post en el blog".

• Slash command /publish → Claude lee el archivo, ejecuta bun import-post. Determinístico.

• Skill publish-post → Claude lee SKILL.md, decide si necesita verificar metadata, generar imagen, validar links, antes de publicar. Adaptativo.

• MCP server wordpress-mcp → expone tools create_post, update_post, upload_media. Otra capa.

Las tres pueden coexistir. La Skill orquesta; el slash es el atajo; el MCP es el músculo.

Skills built-in en Claude Code

Claude Code 2026 viene con varias Skills bundled:

• /simplify — refactor agresivo, elimina overengineering.

• /batch — divide tareas grandes en subtareas paralelizables.

• /debug — hipótesis-experimentación-diagnóstico para bugs.

• /loop — corre un agente en loop hasta que se cumpla una condición.

• /claude-api — guía para construir contra la Claude API.

• /test — generar tests con buenas prácticas.

• /explain — explicar código complejo paso a paso.

Las puedes invocar como slash commands. Por debajo, son Skills con SKILL.md que se cargan al activarse.

Crear tu primera Skill

Estructura mínima para una Skill custom:

# en tu proyecto
mkdir -p .claude/skills/release-notes
cat > .claude/skills/release-notes/SKILL.md <<'EOF'
---
name: release-notes
description: Genera notas de release a partir de git log entre dos tags. Usa esto cuando el usuario pida "release notes", "changelog", o "qué hay nuevo desde la última versión".
---

# Generar release notes

## Pasos

1. Pregunta el tag base si no lo dice (default: `git describe --tags --abbrev=0`).
2. Ejecuta `git log <base>..HEAD --pretty=format:'%h %s'`.
3. Agrupa los commits en: feat, fix, refactor, docs, otros.
4. Filtra commits ruido (typo, fix lint).
5. Escribe el changelog con:
   - Resumen de 1 línea
   - Sección por grupo
   - Mención a contribuidores

## Output esperado

Markdown con secciones h2 por grupo. Ver ejemplo en examples/example.md.
EOF

Con esto, cuando el usuario pida "haz release notes", Claude detecta el match en description, carga el SKILL.md, y ejecuta los pasos.

Skills con scripts

Si necesitas lógica determinística (no solo prompting), añade scripts:

release-notes/
  SKILL.md
  scripts/
    extract_commits.sh
    group_commits.py

En SKILL.md:

## Pasos
1. Ejecuta `bash scripts/extract_commits.sh <base>..HEAD`
2. Pasa el output a `python scripts/group_commits.py`
3. Toma el resultado y formatea como changelog.

Claude ejecuta los scripts vía Bash tool. Esto es genial para dejar lo determinístico fuera del LLM y lo creativo dentro.

Ámbitos: project, user, marketplace

Las Skills viven en tres ámbitos:

1. Project (.claude/skills/ en tu repo): se cargan al abrir el proyecto. Comprometidas a git, compartidas con el equipo.

2. User (~/.claude/skills/): personales del developer. No se comparten.

3. Marketplace (instaladas vía /plugin install): de la comunidad o terceros, descargables.

Buena práctica: las Skills específicas del proyecto van en project. Las personales del workflow van en user. Las utilities universales se descargan del marketplace.

Anthropic mantiene un repo público de Skills con ejemplos.

Caso real: Skill para publicar posts de blog

En el repo seomachine que mantengo, tengo esta estructura para publicar artículos al CMS de Levante:

.claude/skills/import-post/
  SKILL.md

SKILL.md describe:

• Cuándo usarse (cuando el usuario quiere publicar un post).

• Validaciones previas (frontmatter, slug, description ≤160 chars).

• Comando exacto (cd apps/web && bun run import-post <ruta>).

• Verificación de datos via WebSearch antes de redactar (si crea uno desde cero).

Resultado: cada vez que pido "sube este post al blog", Claude carga la Skill, ejecuta el flujo correctamente sin que tenga que repetirlo.

Ahorro estimado: ~15-20 minutos por publicación que antes se iban en pegar instrucciones repetidas.

Cuándo NO crear una Skill

• Si la tarea es de un solo paso: un slash command es más ligero.

• Si la "skill" es solo "lee este archivo": no necesitas estructura, basta con que Claude lo lea.

• Si el conocimiento cambia cada semana: mantenerlo en un MCP que apunta a docs vivas escala mejor.

• Si la tarea ya está cubierta por una bundled: usa la nativa.

Las Skills son útiles cuando: (1) la tarea se repite, (2) tiene varios pasos no triviales, (3) hay contexto que Claude debería tener pero no por defecto.

Errores comunes

Description vaga

description: "Para hacer cosas con git"

Claude no sabrá cuándo activarla. Sé específico:

description: "Generar release notes a partir de git log entre dos tags. Activar cuando el usuario pida 'release notes', 'changelog', o 'novedades desde X'."

Skill que duplica conocimiento de Claude

Si la Skill explica cómo escribir tests Python, sobra. Claude ya sabe. Las Skills útiles aportan conocimiento del proyecto (convenciones, paths, comandos), no genérico.

Skill demasiado grande

Si tu SKILL.md tiene 5000 líneas, ya no es una Skill, es un proyecto. Divide:

• SKILL.md corto, con pasos.

• references/ con docs largas que Claude consulta solo si las necesita.

No versionar Skills del proyecto

Si la Skill vive en .claude/skills/ y no está en git, otro miembro del equipo no la tiene. Commit siempre.

Mezclar slash commands con Skills

Un slash command es una macro, una Skill es un procedimiento. No metas un /deploy que ejecute 30 pasos complejos como slash; conviértelo en Skill, así Claude puede razonar.

Skills + MCP: el patrón potente

Combinar ambos da resultados que ninguno consigue solo:

---
name: triage-issues
description: Triage de issues de Linear, etiquetar y asignar.
---

## Pasos
1. Llama mcp__linear__list_issues(filter="unassigned")
2. Para cada issue, lee descripción + comentarios
3. Aplica reglas:
   - Si menciona "production down" → label `urgent`, asigna a oncall (mcp__linear__assign)
   - Si es feature request → label `feature-request`, asigna a product
4. Devuelve resumen al usuario

La Skill orquesta. El MCP ejecuta. Resultado: agente que hace triage real.

Roadmap interno (lo que viene)

Anthropic ha anunciado para Q2-Q3 2026:

• Skill marketplace oficial integrado en Claude Code.

• Versionado de Skills (similar a paquetes npm).

• Skill testing con eval frameworks integrados.

• Sharing entre proyectos: usar Skills de otro repo sin copiar.

Si construyes Skills serias, sigue de cerca el GitHub de anthropics/skills.

Conclusión

Las Skills son al agente lo que los paquetes son al lenguaje: piezas reutilizables que evitan reinventar lógica común. En 2026, equipos que adoptan Skills antes que MCP genérico ven 30-50% menos tokens consumidos en tareas repetitivas — y velocidad de iteración mucho mayor.

Si tu equipo usa Claude Code más de 10h/semana sin Skills custom, hay valor enorme en empezar a construir las primeras 3-5.

Para profundizar:

• Claude Code por dentro — pillar del cluster.

• Hooks de Claude Code — automatización profunda.

• Slash commands custom — el atajo complementario.

• Subagentes de Claude Code — delegación.

Fuentes verificadas

• Claude Code Skills docs oficiales — referencia.

• Agent Skills overview (Anthropic) — concepto general.

• GitHub anthropics/skills — Skills oficiales.

• Equipping agents for the real world (Anthropic blog) — fundamentos.

• Datos verificados el 29 de abril de 2026.