Anatomía de un skill bien diseñado

El campo que decide si tu skill se activa

El error más común al escribir un skill para Claude Code es obsesionarse con el nombre. Importa, pero menos de lo que crees. Lo que realmente decide si el skill se invoca es el campo description del frontmatter. Ahí va el clasificador: una frase que enumera contextos, sinónimos y palabras gatillo que un humano usaría en su prompt. Si tu description dice "para desplegar el frontend", se va a perder. Si dice "Use when the user wants to deploy the SCRAM frontend to prod-server (gcloud ssh, docker compose, rebuild). Triggers: 'deploy', 'subir cambios', 'rebuild container', 'pull en server'", se activa.

La regla de los tres usos

No codifiques un skill antes de haber repetido el flujo manualmente al menos tres veces. La primera vez es aprendizaje. La segunda confirma que el patrón existe. La tercera revela las variaciones reales que tu skill debe manejar. Si codificas después del primer uso, vas a empaquetar un caso particular como si fuera general, y el skill estorbará más de lo que ayuda.

Corolario: la mitad de los skills que la gente escribe deberían ser slash commands o entradas en CLAUDE.md. Un skill tiene sentido cuando hay lógica condicional ("si el build falla por X, hacer Y; si por Z, hacer W") o cuando documenta un procedimiento de varios pasos con verificaciones intermedias.

Estructura mínima que funciona

---
name: deploy-scram-frontend
description: Use when the user wants to deploy the SCRAM frontend (scram2k.com) to prod-server. Triggers: "deploy", "subir cambios", "rebuild", "pull en server", "push a prod". Handles gcloud ssh + docker compose rebuild + verification.
---

# Deploy SCRAM Frontend

## Preconditions
- git status clean on master
- npm run build passes locally
- VERSION bumped in public/version.json

## Steps
1. git push origin master
2. gcloud compute ssh prod-server --zone=us-central1-c --command="cd /srv/scram-frontend && sudo git pull origin master"
3. If git pull fails with "local changes": sudo git stash first
4. Rebuild: sudo docker compose up -d --build --force-recreate scram-web
5. Verify: curl -I https://www.scram2k.com (expect 200, x-nextjs-cache header)

## Anti-patterns
- NEVER docker compose down -- traefik routes break
- NEVER --no-cache unless build is corrupt -- adds 4 min

Lo que NO va en un skill

• Credenciales o tokens. Van en variables de entorno o en el secret manager.
• Decisiones de producto. Un skill ejecuta procedimientos; no decide si vale la pena hacerlo.
• Lógica que cambia cada semana. Si el flujo muta seguido, el skill se desactualiza y miente. Mejor un script versionado en el repo.

Cuándo NO crear un skill

Si lo que vas a documentar cabe en tres líneas de CLAUDE.md, no es un skill: es una nota. Si es una secuencia de comandos fija sin ramificación, es un slash command o un Makefile. Si es validación automática que debe correr siempre, es un hook (PreToolUse/PostToolUse). El skill ocupa el nicho intermedio: procedimiento con condicionales, activado por contexto en lenguaje natural.

Métrica honesta de calidad

Un skill bien diseñado se activa cuando debe, no se activa cuando no debe, y cuando lo lees a los tres meses sigues entendiendo por qué cada paso está ahí. Si tu repositorio tiene 40 skills y usas 6, los otros 34 son ruido cognitivo que confunde al clasificador y desgasta tu propia paciencia.

La próxima vez que sientas el impulso de "automatizar esto con un skill", anota la fecha y haz el flujo a mano. Si en un mes lo hiciste tres veces y siguen siendo los mismos pasos, entonces sí: escribe el skill. Mientras tanto, ¿cuántos de tus skills actuales pasarían esa prueba?