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.

¿Cómo saber si tu flujo de trabajo necesita un skill o una alternativa más simple?

Para saber si requieres un skill, evalúa si la tarea necesita juicio contextual ante ambigüedad en lenguaje natural y ramificación condicional compleja. Si la tarea es completamente determinista, un slash command o un script bastan; si debe ejecutarse obligatoriamente en cada ciclo de vida, corresponde implementar un hook de sistema.

La siguiente tabla desglosa los criterios operativos para elegir la herramienta correcta de extensión técnica sin sobrecargar el contexto del modelo:

Mecanismo	Mecanismo de activación	Nivel de complejidad lógica	Mantenimiento requerido	Riesgo principal
Entrada en CLAUDE.md	Global en cada prompt	Bajo (reglas y directrices fijas)	Bajo	Saturación de tokens en repositorios grandes
Slash command	Explícita vía comando manual (/cmd)	Nulo o bajo (ejecuta secuencias estáticas)	Bajo	Falta de flexibilidad si cambia el entorno
Hook (Pre/Post Tool)	Automática ligada a eventos de herramienta	Medio (validación y bloqueo)	Medio	Interrupción de ejecuciones válidas por falsos positivos
Skill	Semántica por similitud en la descripción	Alto (árboles de decisión y rescate)	Alto	Activación fantasma o sobreescritura de comportamiento

Qué puede salir mal con los skills mal diseñados

El principal problema en producción es la colisión de disparadores. Cuando dos skills comparten palabras gatillo en su descripción (por ejemplo, "desplegar staging" y "desplegar producción"), el clasificador semántico puede seleccionar la herramienta equivocada. Si el procedimiento no incluye validaciones previas explícitas, el agente puede alterar entornos críticos sin confirmación humana.

Otro error frecuente es la falta de verificación de estado. Un skill que asume que el comando anterior terminó exitosamente sin comprobar códigos de retorno o salidas de red provocará fallos en cascada. Por esta razón, cada paso dentro de la sección de ejecución debe contar con una instrucción de contingencia frente a errores comunes como puertos ocupados, ramas sucias en Git o caídas de sockets.

Implicaciones de costos y contexto para equipos en América Latina

De acuerdo con la documentación técnica de Anthropic sobre uso de contexto y llamadas a herramientas (Tool Use Guide, 2024), las descripciones de las herramientas disponibles se envían en la llamada del sistema durante cada interacción. Si mantienes decenas de skills con descripciones kilométricas, incrementas el consumo base de tokens de entrada hasta en un 15% por cada mensaje enviado por tus desarrolladores.

Para startups y empresas de desarrollo en México, Colombia, Argentina o Chile, donde la facturación de APIs de IA se realiza en dólares estadounidenses, este sobrecosto impacta directamente el margen operativo de los equipos de ingeniería. Un catálogo depurado de skills ahorra dinero real mes a mes y reduce la latencia en las respuestas del asistente.

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?