Cargando la bóveda…
Cargando la bóveda…
Guía para construir skills de Claude Code desde cero. Anatomía del SKILL.md (frontmatter + instrucciones), los 3 niveles de carga progresiva (metadata → instrucciones → recursos), buenas prácticas, errores comunes y un ejemplo completo de code-reviewer listo para copiar.
Un Skill es un superpoder modular que le das a Claude. Es una carpeta con:
Claude lo carga automáticamente cuando detecta que aplica. Funciona en Claude Code, la API, claude.ai y el Agent SDK.
A diferencia de prompts (que tenés que recordar), las skills viven con el proyecto y se activan solas.
Todo skill necesita un archivo SKILL.md:
---
name: mi-skill
description: Describe qué hace en tercera persona
version: 1.0.0
---
# Instrucciones
Aquí van las instrucciones en lenguaje natural
que Claude seguirá cuando active este skill.mi-skill/
├── SKILL.md # obligatorio
├── REFERENCE.md # opcional — contexto extra
└── scripts/ # opcional — scripts auxiliares
└── lint.shmkdir -p mi-skillcat > mi-skill/SKILL.md << 'EOF'
---
name: mi-skill
description: Genera resúmenes concisos de archivos de código
version: 1.0.0
---
# Instrucciones
Cuando el usuario pida un resumen de código:
1. Lee el archivo indicado
2. Identifica la función principal
3. Resume en 2-3 oraciones qué hace y cómo
EOFcat > mi-skill/REFERENCE.md << 'EOF'
# Contexto adicional
Reglas de estilo del proyecto:
- Funciones máximo 30 líneas
- Naming: camelCase para variables, PascalCase para clases
- Tests obligatorios para lógica de negocio
EOFPara skills específicas del proyecto (con convenciones del team), usá per-project. Para utilities personales (tu workflow propio), global.
Claude usa carga lazy para no saturar contexto. Cada skill se carga en 3 niveles:
Claude lee solo el frontmatter (name + description). Con eso decide si el skill es relevante para la tarea actual.
Implicación: tu description es crítica. Si es ambigua, Claude carga skills que no aplican. Si es muy específica, no carga skills que sí aplicarían.
Si decide que es relevante, carga el cuerpo del SKILL.md con todas las instrucciones.
Solo si necesita más contexto para una tarea específica, lee REFERENCE.md y archivos auxiliares.
Tu SKILL.md debe ser conciso. La info detallada va en REFERENCE.md. Si todo está en SKILL.md:
División típica:
Si crece más, divide en skills más pequeñas. Skills monolíticas se vuelven inmanejables.
✅ "Genera tests unitarios para funciones JavaScript" ❌ "Genero tests unitarios..." ❌ "Tests unitarios"
Claude lee desc como "este skill hace X". Tercera persona matchea ese mental model.
✅ code-reviewing
✅ api-documenting
✅ pricing-strategizing
Comunica acción + estado de la skill.
Tu skill puede funcionar perfecto en Opus pero romper en Haiku (menos contexto, menos razonamiento). Testealo en al menos Sonnet + Haiku antes de publicar.
ANTES de:
- Borrar archivos
- Modificar config de producción
- Hacer commits/push
- Cualquier acción no-reversible
Confirmar con el usuario:
"Voy a [acción]. ¿Procedo? [s/n]"❌ "Hacé el mejor diseño posible" ❌ "Trata de ser eficiente" ✅ "Generá 3 variantes. Para cada una incluí: paleta, tipografía, estructura"
Vaguedad → resultados vagos.
❌ helper, utils, my-skill
✅ email-marketing-copy, react-test-generator
❌ C:\Users\Pedro\proyecto\config.json
✅ ${PROJECT_ROOT}/config.json o paths relativos
❌ Skill "agencia-completa" con marketing + dev + diseño ✅ Skills separadas que se combinan según necesidad
❌ Skill A llama a skill B que llama a skill A ✅ Dependencias lineales con direcciones claras
❌ 5000 líneas de "by si acaso" ✅ Solo lo necesario para los casos que el SKILL.md menciona
---
name: code-reviewer
description: Revisa código buscando bugs, vulnerabilidades de seguridad y mejoras de rendimiento
version: 1.0.0
---
# Code Reviewer
Cuando el usuario pida revisión de código:
1. Leé los archivos indicados o los cambios staged en git
2. Analizá en este orden:
- Bugs potenciales y errores lógicos
- Vulnerabilidades de seguridad (OWASP top 10)
- Problemas de rendimiento (queries N+1, loops innecesarios)
- Legibilidad y mantenibilidad
3. Presentá hallazgos agrupados por severidad:
- CRÍTICO — debe corregirse antes de merge
- ADVERTENCIA — recomendado corregir
- SUGERENCIA — mejora opcional
4. Para cada hallazgo incluí:
- Archivo y línea
- Descripción del problema
- Código sugerido de corrección
5. Al final, dá veredicto:
- APROBAR — todo bien
- APROBAR CON CAMBIOS — críticos resueltos, advertencias post-merge
- SOLICITAR CAMBIOS — hay críticos que bloquean
Si REFERENCE.md está disponible, usá sus convenciones de estilo
del proyecto al evaluar legibilidad.
Si la revisión es de >500 líneas cambiadas, sugerí al usuario
dividir el PR antes de continuar.Copialo, modificalo, y tenés tu primer skill.
Notás que repetís el mismo prompt 3+ veces. Eso es candidato a skill.
Convertí el prompt a SKILL.md básico (15-20 líneas). Probalo.
Cada vez que activá pero falla algo:
Cuando la skill funciona consistentemente:
description para mejor activación automáticaversion: 1.1.0)Si funciona bien para vos, considerá publicarla:
Si tu skill es "abrí archivo Y leelo", no es skill — es comando.
Skills aportan cuando hay decisión + workflow estructurado.
Si tu SKILL.md dice "siempre X" y después "excepto cuando Y", clarificá. Reglas claras > listas de excepciones.
Una skill que funciona en tu proyecto puede romperse en otro con stack distinto. Testealo en al menos 2-3 proyectos distintos antes de declarar listo.
Si nunca cambiás version, no podés revertir cambios mal aplicados. Versioná desde el día 1.
description es para Claude. Pero los humanos también necesitan saber cómo invocar el skill. Agregá README breve si lo compartís.
Si todos los lunes hacés "X, Y, Z", convertilo en skill lunes-routine.
Si tu equipo tiene reglas custom (naming, structure, review checklist), empacalas como skill team-standards.
Si tu stack tiene templates específicos (componente React + test + story + docs), skill new-component.
Si trabajás en industria específica (legal, médico, finanzas), skill que aplica conocimiento de tu dominio.
Si tu equipo tiene CLI/scripts propios, skill que sabe cuándo y cómo invocarlos.
Usá ese meta-prompt para diseñar el contenido de tu skill antes de escribirlo. Te ahorra iteraciones.
Si necesitás mental model más profundo de cómo Claude usa skills, leelo antes de invertir tiempo creando muchas.
El skill oficial skill-creator de Anthropic genera skills custom describiéndolas. Atajo cuando tenés idea pero no tiempo de escribir el SKILL.md a mano.