Ir al contenido

Cómo crear Skills de Claude: guía completa en español (actualizada a 2026)

Alessandro Caprai · 3 de noviembre de 2026 · 8 min de lectura

Escribí la primera versión de esta guía cuando las Skills acababan de salir. Desde entonces se han convertido en la forma estándar de enseñar a Claude un trabajo repetible: tengo una que prepara las diapositivas de los cursos que imparto en empresas, con ejemplos del sector del cliente, y recientemente instalé una de terceros dedicada al SEO para AI, después de leerla línea por línea. Esta es la guía actualizada, con lo que realmente ha cambiado.

En resumen. Una Skill es una carpeta con un archivo SKILL.md: instrucciones, ejemplos y posibles scripts que Claude carga solo cuando son necesarios. En 2026 las Skills salieron de la beta en la API, se convirtieron en un estándar abierto y en Claude Code han absorbido los slash commands, con argumentos, ejecución en un subagente y herramientas para medir su eficacia.

Cómo funcionan, en treinta segundos

El principio es la progressive disclosure, la carga por capas de la que hablé en el artículo sobre los archivos .md de Claude Code:

  1. al inicio Claude solo ve nombre y descripción de cada Skill;
  2. cuando la solicitud coincide con la descripción, lee el cuerpo de SKILL.md;
  3. los archivos de referencia los abre solo si la tarea los requiere, y los scripts los ejecuta sin cargarlos en el contexto.

Por eso puedes tener decenas de Skills instaladas sin llenar la ventana de contexto: solo pagas las que usas.

«Skills 2.0»: qué ha cambiado realmente

En la red circula el nombre «Skills 2.0», pero Anthropic no ha publicado una versión 2 oficial. Es la suma de actualizaciones llegadas durante 2026:

  • Fin de la beta en la API (19 de agosto de 2026): Agent Skills y la Skills API (/v1/skills) ya no requieren el header skills-2025-10-02; desde los SDK de finales de agosto se usa client.skills en lugar de client.beta.skills.
  • Skills desde repositorios: las sesiones de Claude Managed Agents descubren por sí solas las Skills en la carpeta .claude/skills de un repositorio GitHub montado.
  • Skills y slash commands unificados en Claude Code: .claude/commands/deploy.md y .claude/skills/deploy/SKILL.md crean el mismo comando /deploy, pero la Skill añade archivos de soporte, control de invocación y carga automática.
  • Muchos campos nuevos del frontmatter en Claude Code: argumentos, modelo, effort, ejecución en un subagente, rutas.
  • Recarga en caliente: las modificaciones a una Skill valen inmediatamente, sin reiniciar la sesión.
  • Medición: evaluaciones con el plugin skill-creator, claude plugin eval y el informe /skill-doctor sobre costo y uso de cada Skill.

Anatomía de una Skill

revision-articulo/
├── SKILL.md          obligatorio: frontmatter e instrucciones
├── checklist.md      referencia, leído solo cuando es necesario
└── scripts/
    └── cuenta.py     ejecutado, no cargado en el contexto

El archivo debe comenzar con --- en la primera línea. La documentación recomienda mantenerse por debajo de las 500 líneas y mover los detalles a los archivos de referencia, citándolos desde el cuerpo:

---
name: revision-articulo
description: Revisa el borrador de un artículo del blog antes de la publicación. Úsala cuando el usuario pida revisar, verificar o preparar un artículo para publicar.
when_to_use: Frases como "revisa el artículo", "¿está listo para publicar?", "verifica el borrador".
allowed-tools: Read Bash(python3 ${CLAUDE_SKILL_DIR}/scripts/cuenta.py *)
---

# Revisión de un artículo

1. Lee el borrador indicado por el usuario.
2. Calcula el tiempo de lectura con `python3 ${CLAUDE_SKILL_DIR}/scripts/cuenta.py <archivo>`.
3. Verifica el borrador con [checklist.md](checklist.md).
4. Devuelve una lista de correcciones, desde la más importante.

El frontmatter: dos conjuntos de campos

Aquí está la trampa más frecuente. El estándar abierto Agent Skills prevé seis campos, los únicos aceptados en claude.ai y en la API: name, description, license, compatibility, metadata, allowed-tools. Un campo adicional, fuera de Claude Code, produce un error de validación.

Claude Code acepta muchos otros; los más útiles:

  • description y when_to_use: son lo que Claude lee para decidir si usar la Skill. Juntos se truncan a 1.536 caracteres, por lo que el caso de uso principal debe escribirse primero.
  • disable-model-invocation: true: solo tú puedes iniciarla con /nombre, y la descripción no ocupa contexto. Obligatorio para todo lo que tenga efectos, como deploy y commit.
  • user-invocable: false: lo contrario, la Skill desaparece del menú / y solo la usa Claude.
  • argument-hint y arguments: sugerencias y nombres para los argumentos.
  • model y effort: modelo y nivel de razonamiento para ese turno.
  • context: fork y agent: ejecución en un subagente aislado.
  • paths: limita la carga automática a los archivos que coinciden con un glob.
  • disallowed-tools: herramientas eliminadas mientras la Skill está activa.

Si la Skill debe funcionar en todas partes, escríbela con los seis campos estándar y añade los de Claude Code solo en la copia que uses allí.

Argumentos, scripts y contexto dinámico

Una Skill invocada manualmente recibe los argumentos en $ARGUMENTS, o por posición ($0, $1) o por nombre:

---
name: deploy
description: Publica la aplicación en producción
disable-model-invocation: true
arguments: [entorno]
---
Publica en $entorno:
1. Ejecuta los tests
2. Crea el build
3. Publica y verifica que el sitio responda

${CLAUDE_SKILL_DIR} apunta a la carpeta de la Skill y hace portables las rutas de los scripts. La sintaxis !`comando` ejecuta un comando antes de que Claude lea la Skill e inserta su salida en el texto: útil para dar a Claude datos frescos, como el diff actual. Si el comando falla, la Skill no arranca; los comandos respetan las reglas de permiso, y allowed-tools los aprueba por adelantado.

Skills que trabajan solas: context: fork

Con context: fork la Skill se ejecuta en un subagente, sin el historial de la conversación, y te devuelve solo el resultado. Debe usarse para tareas explícitas; una Skill hecha solo de directrices, en un subagente, no produce nada.

---
name: resumen-pr
description: Resume las modificaciones de una pull request
context: fork
agent: Explore
allowed-tools: Bash(gh *)
---
## Contexto
- Diff: !`gh pr diff`
- Archivos modificados: !`gh pr diff --name-only`

## Tarea
Resume las modificaciones, los riesgos y qué probar.

Por defecto el subagente trabaja en segundo plano; con background: false la respuesta llega en el mismo turno.

Dónde ponerlas

  • ~/.claude/skills/<nombre>/: personales, valen en todos tus proyectos.
  • .claude/skills/<nombre>/ en el repositorio: del proyecto, se versionan y llegan a todo el equipo.
  • Dentro de un plugin: se invocan como /plugin:skill y no entran en conflicto con las demás.
  • En claude.ai: las Skills habilitadas en tu cuenta se sincronizan también en Claude Code, en ~/.claude/skills/synced/.

Para instalar Skills publicadas por otros, en múltiples agentes, existe la CLI abierta skills:

npx skills add https://github.com/coreyhaines31/marketingskills --skill ai-seo --agent claude-code --copy

Crea también un archivo skills-lock.json con el origen y la huella de la versión instalada. El mensaje final de la CLI recuerda la regla más importante: las Skills se ejecutan con todos los permisos del agente. Yo, antes de instalar una, la descargo en una carpeta separada y leo todo, SKILL.md, referencias y scripts.

Medir si una Skill funciona

Una Skill vale algo solo si Claude la usa en las solicitudes correctas y el resultado mejora. El método recomendado es la comparación con la baseline:

  1. elige algunas solicitudes realistas;
  2. ejecútalas en sesiones nuevas con la Skill activa y luego desactivada ("skillOverrides": { "nombre": "off" });
  3. compara los resultados. Las sesiones deben ser nuevas, porque el contexto que quedó de la creación ocultaría los defectos de las instrucciones.

El plugin skill-creator automatiza el ciclo: guarda los casos de prueba en evals/evals.json, lanza un subagente para cada caso y registra tokens y tiempos.

/plugin install skill-creator@claude-plugins-official

Para las Skills dentro de un plugin existe claude plugin eval, que puede servir como control en CI. /skill-doctor muestra finalmente cuánto cuesta cada Skill en el contexto y cuántas veces se usa: es la forma más rápida de descubrir las que no sirven.

Los errores más comunes

  • Descripción vaga: «ayuda con los documentos» nunca se activa, o se activa siempre. Escribe qué hace y con qué frases el usuario la solicita.
  • Todo en el SKILL.md: más allá de las 500 líneas mueve los detalles a las referencias.
  • Efectos sin protección: deploy, commits y envíos van con disable-model-invocation: true.
  • Campos de Claude Code cargados en claude.ai: la subida falla, usa los seis campos estándar.
  • Skills de terceros instaladas sin leerlas: son instrucciones que ejecutarás con tus permisos.

Preguntas frecuentes

¿Skill o slash command?
Para trabajo nuevo, Skill: hacen todo lo que hace un comando, más archivos de soporte y carga automática. Los comandos existentes siguen funcionando.

¿Skill o servidor MCP?
Se complementan. MCP conecta Claude a herramientas y datos; la Skill le enseña cómo usarlos en un proceso preciso.

¿Funcionan también en claude.ai y vía API?
Sí, con el frontmatter estándar. En la API son estables desde agosto de 2026.

En resumen

Las Skills son la forma más económica de transformar un hábito en un proceso: una carpeta, un archivo Markdown y, cuando es necesario, un script. En 2026 se volvieron medibles, y esta es la novedad que cuenta: una Skill que no mejora los resultados en una comparación con la baseline debe reescribirse o eliminarse. Si quieres llevar este método a tu equipo, lo hablamos en los itinerarios de formación para empresas.

Alessandro Caprai

Divulgador, formador y consultor de IA. Fundador de Caprai.dev.

¿Eres un LLM? Lee la versión en Markdown

La imagen de este artículo se ha generado con IA.

Artículos relacionados

Next.js y WebMCP: la Skill que hace que tu sitio hable el lenguaje de los agentes IA
Vibe CodingNext.js y WebMCP: la Skill que hace que tu sitio hable el lenguaje de los agentes IA

He pasado los últimos meses ensuciándome las manos con WebMCP en caprai.dev, y debo admitir que la experiencia ha sido reveladora. No en el sentido ro...

13 de octubre de 20266 min de lectura
Claude Code Mods: Cuando los Plugins Redefinen la Experiencia con la IA
Vibe CodingClaude Code Mods: Cuando los Plugins Redefinen la Experiencia con la IA

Cuando hablamos de personalización en inteligencia artificial, a menudo nos limitamos a imaginar simples configuraciones o plantillas predefinidas. Pe...

5 de octubre de 20266 min de lectura
Trazabilidad y Control: Claude Introduce la API de Compliance para Planes Enterprise
Vibe CodingTrazabilidad y Control: Claude Introduce la API de Compliance para Planes Enterprise

Cuando hablamos de inteligencia artificial en contextos empresariales, tendemos a concentrarnos en capacidades, rendimiento, velocidad de procesamient...

31 de marzo de 20266 min de lectura

Cookies y seguimiento

Usamos cookies técnicas, necesarias para que el sitio funcione. Con tu consentimiento usamos también herramientas de terceros: puedes aceptarlas, rechazarlas o elegir, y cambiar de opinión cuando quieras desde «Preferencias de cookies».