Creando tu primera skill

Creando tu primera skill

Puntos clave

• Una skill es un directorio que contiene un archivo SKILL.md con metadatos (nombre, descripción) en el frontmatter e instrucciones debajo
• Claude carga solo los nombres y descripciones de las skills al iniciar, y luego hace coincidir las solicitudes entrantes con esas descripciones usando coincidencia semántica
• Cuando hay una coincidencia, una skill que solo tiene nombre, descripción e instrucciones se carga por completo sin pedirte permiso. Si una skill preaprueba herramientas o agrega hooks, Claude Code puede pedirte tu aprobación primero
• Prioridad para conflictos de nombres: Enterprise → Personal → Project. Las skills de plugins tienen espacio de nombres propio, por lo que se cargan junto a una skill con el mismo nombre
• Para actualizar una skill, edita su SKILL.md. Para eliminar una, borra su directorio. Claude Code detecta el cambio en la sesión actual, sin necesidad de reiniciar. Si ~/.claude/skills es nuevo en esta sesión, ejecuta /reload-skills después de cada cambio

Repasemos cómo crear una skill desde cero y luego veamos cómo Claude Code realmente carga y hace coincidir las skills detrás de escena.

Creando una skill

Construiremos una skill personal que le enseña a Claude cómo escribir descripciones de PR en un formato consistente. Como es una skill personal, vive en tu directorio home y funciona en todos tus proyectos.

Primero, crea un directorio para tu skill dentro de la carpeta skills. El nombre del directorio debe coincidir con el nombre de tu skill:

Luego crea un archivo SKILL.md dentro de ese directorio. El archivo tiene dos partes separadas por guiones de frontmatter:

---
name: pr-description
description: Writes pull request descriptions. Use when creating a PR, writing a PR, or when the user asks to summarize changes for a pull request.
---

When writing a PR description:

1. Run `git diff main...HEAD` to see all changes on this branch
2. Write a description following this format:

## What
One sentence explaining what this PR does.

## Why
Brief context on why this change is needed

## Changes
- Bullet points of specific changes made
- Group related changes together
- Mention any files deleted or renamed

El nombre identifica tu skill. La descripción le indica a Claude cuándo usarla; este es el criterio de coincidencia. Todo lo que viene después del segundo conjunto de guiones son las instrucciones que Claude sigue cuando se activa la skill.



Probando tu skill

Claude Code vigila tus directorios de skills, así que una skill nueva está disponible en la sesión actual sin necesidad de reiniciar. Si ~/.claude/skills no existía cuando comenzó la sesión, Claude Code todavía no lo está vigilando, así que ejecuta /reload-skills ahora, y de nuevo después de cada cambio posterior. Puedes verificar que tu skill esté disponible revisando la lista de skills disponibles.



Deberías ver tu skill en la lista. Para probarla, haz algunos cambios en una rama y di algo como "escribe una descripción de PR para mis cambios". Claude indicará que está usando la skill de descripción de PR, revisará tu diff y escribirá una descripción siguiendo tu plantilla, con el mismo formato cada vez.

Cómo funciona la coincidencia de skills

Cuando Claude Code inicia, escanea varias ubicaciones en busca de skills, pero solo carga el nombre y la descripción, no el contenido completo. Este es un detalle importante.

Cuando envías una solicitud, Claude compara tu mensaje con las descripciones de todas las skills disponibles. Por ejemplo, "explica qué hace esta función" coincidiría con una skill descrita como "explicar código con diagramas visuales" porque la intención se superpone.

Una vez que se encuentra una coincidencia, Claude lee el archivo SKILL.md completo y sigue sus instrucciones. Una skill que solo tiene nombre, descripción e instrucciones (como pr-description) se carga sin pedirte permiso. Si una skill preaprueba herramientas o agrega hooks, Claude Code puede pedirte que la apruebes primero, dependiendo de tu modo de permisos. El video de arriba y la imagen de abajo muestran el paso de aprobación que Claude Code v2.1.19 eliminó para skills como pr-description.



Prioridad de skills

Si clonas un repositorio que tiene una skill con el mismo nombre que una de tus skills personales, ¿cuál gana? Hay un orden de prioridad claro:

1. Enterprise: configuración administrada, máxima prioridad
2. Personal: tu directorio home (~/.claude/skills)
3. Project: el directorio .claude/skills dentro de un repositorio

Esto permite que las organizaciones impongan estándares mediante skills de Enterprise, a la vez que permiten la personalización individual. Si tu empresa tiene una skill de Enterprise llamada "code-review" y creas una skill personal "code-review" con el mismo nombre, la versión de Enterprise tiene prioridad. Las skills de plugins instalados quedan fuera de este orden. Tienen espacio de nombres propio como /plugin-name:skill-name, por lo que una skill de plugin y otra skill con el mismo nombre se cargan ambas.

Para evitar conflictos, usa nombres descriptivos. En lugar de simplemente "review", usa algo como "frontend-review" o "backend-review".

Actualizando y eliminando skills

Para actualizar una skill, edita su archivo SKILL.md. Para eliminar una, borra su directorio. Claude Code detecta el cambio en la sesión actual, así que no necesitas reiniciar. Si ejecutaste /reload-skills antes en esta sesión porque ~/.claude/skills era nuevo, ejecútalo de nuevo después de cada cambio.

Reflexión de la lección

• ¿Cuál es una tarea de tu flujo de trabajo diario que podrías convertir en una skill ahora mismo? ¿Cómo se vería la descripción?
• ¿Cómo podría afectar la jerarquía de prioridad a la estrategia de gestión de skills de tu equipo? ¿Confiarías más en skills personales o a nivel de proyecto?

Qué sigue

En la próxima lección, aprenderás sobre opciones de configuración avanzadas, incluidos los campos de metadatos, la preaprobación de herramientas con allowed-tools, y cómo estructurar skills más grandes usando divulgación progresiva y organización de múltiples archivos.