Tu primer Skill en 30 minutos, cuando los slash commands ya no bastan

Los slash commands son geniales, siempre que te acuerdes de teclearlos. Ahí está justamente el problema. Después de tres semanas sabes que querías /review, pero simplemente ya no lo tecleas. Las Skills resuelven exactamente eso. Son archivos Markdown como los slash commands, pero se disparan automáticamente cuando Claude reconoce en el prompt que la skill encaja. Dices "échale un ojo al código de auth", y Claude carga tu skill simplify en silencio en segundo plano y trabaja en consecuencia. Te muestro cómo escribir tu primera skill útil en 30 minutos y dónde están las trampas.

1. Entender cómo funcionan las skills técnicamente

Una skill es un directorio bajo ~/.claude/skills/<name>/ con al menos un archivo dentro: SKILL.md. El frontmatter de arriba define cuándo debe dispararse la skill. El body es la instrucción de qué debe hacer Claude cuando se dispara. En cada prompt Claude escanea el frontmatter de todas las skills disponibles y decide, basándose en la description, si alguna hace match. Si es así, carga el body como contexto adicional y lo usa para la respuesta.

Es decir: la descripción en el frontmatter no es documentación, es el mecanismo de trigger. Si dice "for German blog posts", se dispara con "escríbeme un post de blog en alemán". Si dice "use this skill for code review", no se dispara porque "code review" es demasiado vago. Los triggers precisos lo son todo.

2. Crear tu primera skill

Crea el directorio y el archivo:

mkdir -p ~/.claude/skills/simplify
cat > ~/.claude/skills/simplify/SKILL.md <<'EOF'
---
name: simplify
description: |
  Use when reviewing code the user just wrote or edited. Looks
  for unused imports, duplicated logic, premature abstractions,
  dead error paths, and overlong functions. Triggers on phrases
  like "review this", "check my code", "anything to clean up".
---

# Simplify

When invoked:

1. Read the changed files in the working directory
2. Look specifically for:
   - Unused imports or variables
   - Logic duplicated within 50 lines
   - Functions over 60 lines that could split
   - Catch blocks that swallow errors silently
   - Premature abstractions used only once
3. Return max 5 concrete findings with line numbers
4. No general praise, no "looks good overall", just findings
EOF

Guárdalo, listo. Claude Code no necesita reiniciarse, la live detection lo recoge. Si ahora tecleas "revisa mi último archivo", Claude debería cargar la skill en silencio y buscar los patterns nombrados.

3. La description es tu trigger, no tu documentación

Este es el único punto donde los principiantes siempre fallan. Escriben algo como description: A code review helper y se preguntan por qué la skill nunca se dispara. Claude decide en base a la description si la skill encaja, así que tiene que decir de forma concreta CUÁNDO debe encajar. Formátalo como "Use when..." más frases trigger típicas.

Malo: description: Helps with code review.

Bueno: description: Use when the user asks you to review, check, or clean up code they just wrote. Looks for duplication and dead code. Triggers on "review this", "any improvements", "code smell".

Escribe ahí tanto como haga falta para que Claude pueda hacer match de forma fiable. 200 a 400 caracteres es lo habitual. Por encima se vuelve redundante, por debajo se dispara de forma poco fiable.

4. Limitar allowed-tools cuando la seguridad importa

Si tu skill debe ejecutar comandos bash o escribir archivos, puedes acotar los permisos vía frontmatter. Esto no es cosmético, evita que la skill ejecute por accidente rm -rf porque la salida del LLM se torció.

---
name: deploy-staging
description: Use when the user says "deploy to staging" or "push to staging". Runs the staging deploy script and reports back.
allowed-tools: Bash(./scripts/deploy-staging.sh), Read
---

# Deploy Staging

1. Run `./scripts/deploy-staging.sh`
2. Tail the last 50 lines of output
3. Report success or failure clearly

La entrada Bash(./scripts/deploy-staging.sh) permite solo exactamente ese único comando. Las demás llamadas bash siguen pidiendo confirmación. Así construyes una skill que puede hacer mucho, pero que no mata tu servidor por accidente.

5. Empaquetar scripts y referencias

Las skills pueden ser más que solo SKILL.md. Puedes empaquetar archivos de ayuda que Claude lee cuando los necesita. Layout de directorio:

~/.claude/skills/release-notes/
├── SKILL.md
├── scripts/
│   └── git-summary.sh
└── references/
    └── tone-guide.md

En SKILL.md luego los referencias:

# Release Notes

When invoked:
1. Run `./scripts/git-summary.sh` to get commits since last tag
2. Read `./references/tone-guide.md` for our style
3. Write release notes following the tone guide

Ventaja: la skill se mantiene legible, la lógica vive en scripts, las guías de estilo en archivos de referencia. En las actualizaciones solo editas el archivo correspondiente, no todo a la vez.

6. Versionar skills y compartirlas en el equipo

Las skills personales viven en ~/.claude/skills/. Las skills de proyecto en .claude/skills/ en el repo, esas las commiteas. Ventaja de las skills de proyecto: todos en el equipo reciben el mismo setup automáticamente. Desventaja: tu skill weekly-review no se cuela en el siguiente repo.

Mi setup: lo que es específico de proyecto (coding standards, scripts de deploy, tono de voz interno) vive en el repo. Lo que es útil en general (simplify, debrief, tone-fix) vive en el home dir. Una skill privada ~/.claude/skills/dailylog/ que gestiona mis propias notas, no la quiero en cada repo de cliente.

Si compartes skills con otros que no trabajan en el mismo repo: empaquétalas en un repo git, deja que la gente lo clone en ~/.claude/skills/. El sistema de plugins es overkill antes de tener 10 skills.

7. Tres skills que casi todo el mundo necesita

Para que no empieces de cero, tres skills que se han probado bien conmigo.

simplify, ya mostrada arriba. Déjala dispararse después de cada edit más grande, atrapa el 80 por ciento de "ah sí, eso se me olvidó limpiar".

debrief, llamada al final de una sesión. Lee las últimas 20 acciones, escribe un resumen corto, lo guarda en nex_summarize o una memory tool. Así sabes días después qué pasó en aquella sesión.

deutsche-texte, cuando escribes a menudo en alemán. Fuerza umlauts reales en lugar de oe/ae/ue/ss. Se dispara con "schreib mir nen", "erstell einen Post auf Deutsch", "uebersetz das ins Deutsche".

---
name: deutsche-texte
description: Use when writing German text users will see (blog posts, landing pages, social media, i18n strings). Forces real umlauts ä, ö, ü, ß instead of ASCII digraphs ae, oe, ue, ss. Skip for filenames, slugs, code identifiers.
---

# Deutsche Texte

When the user asks for German text:
- Use real umlauts: ä, ö, ü, ß
- Never use ASCII digraphs: ae, oe, ue, ss
- Exception: file paths, URL slugs, code identifiers stay ASCII
- After writing, scan output once for accidental digraphs

Tres archivos pequeños, payoff inmediato.

8. Cuándo skill, cuándo slash command

Ambos son Markdown más frontmatter, la diferencia es cómo se disparan. Las skills se disparan cuando Claude lo reconoce desde el prompt natural. Los slash commands se disparan solo cuando tecleas /name. De ahí se sigue:

Las skills son mejores para cosas que Claude siempre debería hacer cuando el contexto encaja. Code review después de cada edit. Chequeo de tono en textos alemanes. Debrief al final de la sesión.

Los slash commands son mejores para cosas que quieres disparar explícitamente. Deploy. Test run con flags específicas. Snapshot de estado donde sabes exactamente que lo necesitas ahora.

Regla práctica: si te olvidarías de iniciarlo a mano, haz una skill. Si es destructivo o caro, haz un slash command para que tengas que teclearlo conscientemente.

9. Los dos errores que todo el mundo comete al principio

Trigger formulado demasiado vago. Si escribes description: Code helper, la skill se dispara o en cada prompt o nunca. Ambas cosas son una mierda. Mete frases trigger concretas, formato "Use when...", al menos dos frases de usuario de ejemplo.

Body demasiado vago. Si el body dice "review the code carefully", recibes un muro de texto de vuelta. Mete criterios de aceptación. Número máximo de findings, forma de salida concreta, qué NO debe volver. Igual que con los slash commands: una skill es tan buena como el prompt que tiene dentro.

Error bonus: crear demasiadas skills a la vez. No te acuerdas de cuáles tienes, colisionan en triggers, una se dispara donde debería otra. Empieza con tres. Construye más solo cuando las tres realmente funcionen.

10. Qué sigue

Cuando las primeras tres skills funcionen, notarás que algunos patterns se repiten. Justo entonces llega el momento para los hooks, que corren automáticamente en eventos sin que siquiera haga falta un prompt. Mira el playbook Hooks gegen Halluzinationen si quieres el siguiente nivel.

Si quieres compartir skills con otros y la distribución se vuelve importante, mira el playbook MCP Server publishen, que aplica análogamente también a los bundles de skills. Y si quieres entrar en workflows más complejos, Erster Sub-Agent in 30 min muestra cómo expandir una skill a un sub-agent dedicado.

Mi consejo: crea ahora una única skill, simplify, con el frontmatter del paso 2. Déjala correr una semana. Después sabrás tú mismo qué te sigue faltando y qué skill tiene sentido a continuación.

Source

Specs verificadas vía verify_anthropic_doc_spec contra la documentación oficial el 2026-05-06:

• https://code.claude.com/docs/en/skills (frontmatter reference, allowed-tools, bundled scripts, live change detection, auto-discovery)

Recipes consultados en la Academy:

• Phase 1, Recipe 1.2 "Skills", introducción corta con ejemplos de trigger
• Lesson L4-04 "Hooks und Skills", distinción conceptual