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

3 de noviembre de 2026 · Alessandro Caprai, Divulgador, formador y consultor de IA

<https://caprai.dev/es/vibe-coding/post/como-crear-skills-de-claude-guia-completa-en-espanol-actualizada-a-2026>

---

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](/es/vibe-coding/post/progressive-disclosure-la-arquitectura-por-capas-que-revoluciona-la-eficiencia-de-claude-code-con-archivos-md):

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

```text
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:

```markdown
---
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:

```markdown
---
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.

```markdown
---
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`:

```bash
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.

```text
/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](/es/empresas).
