Introduction to Agent Skills — Resumen de estudio

Paths: Developer · FDE · 6 lecciones, 6 videos (~1 h 45 min)
Crear, configurar, compartir y depurar Skills en Claude Code.

1. Qué son

Un Skill es una carpeta con un SKILL.md (frontmatter con name + description, y debajo las instrucciones) que enseña a Claude a hacer algo una vez. Claude lo aplica automáticamente cuando es relevante.
La description es el criterio de coincidencia: Claude compara tu petición con todas las descripciones y activa las que coinciden (coincidencia semántica).

---
name: pr-review
description: Reviews pull requests for code quality. Use when reviewing PRs or checking code changes.
---
(checklist / instrucciones)

Dónde viven:
- Personales: ~/.claude/skills (en Windows, C:/Users/<user>/.claude/skills); te siguen en todos los proyectos.
- De proyecto: .claude/skills en el repo; se comparten con Git.
Comparación:
- CLAUDE.md se carga en todas las conversaciones.
- Un Skill carga solo el nombre y la descripción al inicio y el resto bajo demanda.
- Un slash command hay que escribirlo; un Skill se activa solo.
Buenos usos: estándares de code review, formato de commits, guías de marca, plantillas de documentación, checklists de debugging por framework.
Regla: si le explicas lo mismo a Claude una y otra vez, ahí hay un Skill.

2. Crear el primero

mkdir -p ~/.claude/skills/pr-description → SKILL.md con una description que diga qué hace y cuándo usarlo ("Use when creating a PR, writing a PR, or when the user asks to summarize changes…") y los pasos (p. ej. git diff main...HEAD, luego el formato What / Why / Changes).
Reinicia Claude Code (los Skills se cargan al arrancar) y verifica que aparezca en la lista.
Al coincidir, Claude te pide confirmación antes de cargar el contenido completo.
Prioridad cuando dos Skills se llaman igual: Enterprise → Personal → Project → Plugins. Usa nombres descriptivos (frontend-review, no review).
Para actualizar, edita el SKILL.md; para eliminar, borra la carpeta. Reinicia en ambos casos.

3. Configuración avanzada y Skills de varios archivos

Campo	Regla
`name` (obligatorio)	Minúsculas, números y guiones; máx. 64 caracteres; igual al nombre de la carpeta
`description` (obligatorio)	Máx. 1,024 caracteres; el campo más importante
`allowed-tools` (opcional)	Limita las tools mientras el Skill está activo (p. ej. `Read, Grep, Glob, Bash` = solo lectura). Si lo omites, aplica el modelo de permisos normal
`model` (opcional)	Qué modelo usa el Skill

Descripciones eficaces: responden qué hace y cuándo usarlo. Si no se activa, añade palabras clave tal como tú formulas las peticiones.
Progressive disclosure: mantén SKILL.md por debajo de 500 líneas y enlaza archivos de apoyo que Claude lee solo cuando hacen falta (una especie de índice en el contexto).
- scripts/ (código ejecutable), references/ (documentación), assets/ (imágenes, plantillas).
Scripts: se ejecutan sin cargar su contenido en contexto; solo la salida consume tokens. Indica en SKILL.md que el script se ejecute, no se lea. Ideal para validar el entorno, transformaciones consistentes y operaciones más fiables como código probado.

4. Skills frente a otras funciones de Claude Code

Función	Cómo se activa	Para qué
CLAUDE.md	Siempre	Estándares permanentes del proyecto ("nunca modificar el schema", estilo, framework)
Skills	Por la petición, bajo demanda	Conocimiento de una tarea que solo a veces es relevante
Subagents	Al delegar	Contexto aislado, otras tools; devuelven resultados
Hooks	Por eventos (guardar un archivo, una tool call)	Operaciones automáticas, validación
MCP servers	Siempre conectados	Tools e integraciones externas (otra categoría)

Combínalos: cada uno hace lo suyo, no fuerces todo dentro de Skills.

5. Compartir Skills

En el repositorio (.claude/skills): llegan a todo el equipo al hacer pull. Para estándares del equipo y workflows del proyecto.
Plugins y marketplaces: para distribuir entre repos y a la comunidad (carpeta skills/ con un SKILL.md por Skill).
Enterprise managed settings: despliegue a toda la organización con la prioridad más alta. Para lo que es obligatorio (compliance, seguridad). Por ejemplo, strictKnownMarketplaces limita de dónde se pueden instalar plugins.
⚠️ Subagents y Skills:
- Los subagents no heredan los Skills.
- Los built-in (Explore, Plan, Verify) no pueden usar Skills.
- Los subagents propios (.claude/agents) los usan solo si los listas en el campo skills: del frontmatter, y se cargan al arrancar el subagent (no bajo demanda).

6. Troubleshooting (checklist)

Primero, el skills validator (se instala fácil con uv): detecta errores de estructura.
No se activa → casi siempre es la descripción. Añade frases que de verdad usas y prueba variantes ("help me profile this", "why is this slow?").
No carga → el SKILL.md debe estar dentro de una carpeta con nombre (no en la raíz de skills) y llamarse exactamente SKILL.md. Revisa el YAML y usa claude --debug.
Se usa el Skill equivocado → las descripciones son demasiado parecidas.
Uno de mayor prioridad lo opaca → renómbralo (o habla con el admin).
Los Skills de un plugin no aparecen → limpia el caché, reinicia y reinstala; luego usa el validator.
Errores en ejecución → dependencias instaladas (documéntalas), chmod +x en los scripts, barras normales / también en Windows.

Los mejores Skills nacen de problemas reales: empieza por lo que más repites.