✅ Cuándo SÍ vale la pena una skill
Una skill cuesta contexto y mantenimiento. Solo vale la pena cuando hay una ganancia real y repetida. Hay cuatro señales verdes: cuantas más estén presentes, más clara es la decisión de empaquetarla. La regla práctica: si dos o más las señales coinciden; vale la pena crear la skill.
🔁 Workflow repetible
Ejecutas la misma secuencia de pasos todas las semanas: generar un componente, configurar el deploy, escribir un tipo de prueba. La repetición es la señal número uno.
Ejemplo: patrón de PR, convención de commit, scaffold de una feature.
🧠 Conocimiento del contexto del equipo
Algo que solo tu equipo sabe: convenciones internas, gotchas del código heredado, decisiones de arquitectura. El modelo no puede adivinarlo por sí solo.
Ejemplo: "en este repo, usa siempre el wrapper X en lugar de fetch directo".
🔍 Resultados verificables
Puedes comprobar si quedó bien: las pruebas pasan, el lint queda limpio, el schema valida. Un resultado verificable permite iterar y medir la skill.
Ejemplo: código que compila, JSON que valida contra un schema.
🪜 Varios pasos
La tarea tiene varios pasos encadenados con orden y dependencias. La skill encapsula todo el proceso, no solo un consejo aislado.
Ejemplo: leer config → generar archivos → ejecutar build → validar.
💡 Consejo para calibrar
Si te descubres explicándole lo mismo al agente por tercera vez en la semana, eso es un workflow repetible + conocimiento de contexto. Dos señales verdes: detente y escribe la skill ahora.
🚫 Cuándo NO conviene
Tan importante como saber cuándo crear es saber cuándo no crear. La mayoría de las skills inútiles nace del impulso de «voy a organizar esto en una skill» para algo que no lo necesitaba. Tres señales de alerta indican exceso de ingeniería.
✗ NO crees una skill cuando...
- ✗Tarea puntual: vas a hacer esto una sola vez. La skill es pura sobrecarga.
- ✗El modelo ya hace por su cuenta: dar formato a markdown, traducir, resumir: capacidad nativa, sin valor añadido.
- ✗Query simple de 1 paso: "¿cuál es la capital de Francia?" no se convierte en una skill.
- ✗Todavía no tienes claro el proceso ni en tu propia cabeza.
✓ Haz otra cosa
- ✓One-off → solo inclúyela en el prompt del momento.
- ✓Capacidad nativa → confía en el modelo, no la dupliques.
- ✓1 paso → una frase en el prompt lo resuelve.
- ✓Proceso difuso → hazlo manualmente 3 veces y luego extrae el patrón.
La prueba de "ya lo hace por su cuenta"
Antes de crear, ejecuta la tarea sin skill (baseline). Si el resultado ya es bueno, la skill no aporta nada: solo ocupa contexto. Una skill solo vale la pena si la diferencia entre con-skill y baseline es visible.
🌳 Skill vs CLAUDE.md vs MCP vs subagente
Cuatro herramientas resuelven problemas diferentes. Elegir la incorrecta es el error de diseño más común. El árbol de decisión de abajo te lleva a la opción correcta con dos o tres preguntas.
CLAUDE.md — siempre activo
Reglas que aplican en todas las sesiones, sin activador. Estilo de respuesta, idioma, prohibiciones generales. Ocupan contexto todo el tiempo: úsalas solo para lo que sea universal.
MCP: conexión
Servidor que proporciona herramientas al agente para comunicarse con servicios externos (base de datos, API, browser). MCP es tubería; una skill es conocimiento. No los confundas.
Subagente — aislamiento
Trabajo pesado, paralelo y con contexto propio (p. ej., buscar en todo el repo). Mantiene limpio el contexto principal. Incluso puede usar skills dentro de él.
Skill — bajo demanda
Conocimiento que se activa solo cuando coincide la descripción. No añade peso cuando es irrelevante. Es la opción predeterminada para flujos de trabajo repetibles + contexto que no cabe siempre en CLAUDE.md.
🐘 Antipatrón: alcance gigantesco
El primer antipatrón que acaba con las skills: la tentación de crear una skill "todo-sobre-X". Una skill de 800 líneas que cubre todo React, desde useState hasta deploy. Parece eficiente. Es todo lo contrario.
✗ Alcance enorme
- ✗
tudo-sobre-react.mdcon 800 líneas - ✗La Description se vuelve genérica: "ayuda con React"
- ✗Se activa con todo o con nada
- ✗El agente asimila mal: instrucciones diluidas
- ✗Imposible de probar y versionar
✓ Skills atómicas
- ✓
react-component-scaffold - ✓
react-hooks-conventions - ✓
react-a11y-guidelines - ✓Cada una con un activador preciso y <500 líneas
- ✓Se combinan cuando el contexto lo requiere
La regla de división: un activador por skill:
# ✗ ANTES (uma skill, vários gatilhos misturados) skills/ tudo-sobre-react/SKILL.md # 800 linhas, dispara em "react" # ✓ DEPOIS (uma responsabilidade cada) skills/ react-component-scaffold/SKILL.md # dispara em "novo componente" react-hooks-conventions/SKILL.md # dispara em "usar hook / estado" react-a11y-guidelines/SKILL.md # dispara em "acessibilidade"
💡 Heurística de división
Si no puedes escribir una description de una frase que diga exactamente cuándo se activa la skill, es demasiado grande. Cada trigger distinto = una skill. La atomicidad no es estética: es lo que hace que el trigger funcione.
📢 Antipatrón: MUSTs en mayúsculas y overfit
El segundo antipatrón: llenar la skill de "SIEMPRE DEBES" en mayúsculas y pega ejemplos demasiado específicos. El modelo memoriza los casos exactos y falla ante cualquier variación. La skill pasa tus pruebas y falla en la vida real: eso es overfit.
sobreajuste vs. generalización:
# ✗ OVERFIT (decora o caso, não o princípio) VOCÊ DEVE SEMPRE nomear o arquivo de "Button.tsx". VOCÊ DEVE SEMPRE usar a cor #14b8a6. # ✓ GENERALIZA (ensina o porquê, vale fora dos exemplos) Nomeie componentes em PascalCase, igual ao nome exportado, porque o resolver de imports e a navegação do editor dependem dessa correspondência. Ex.: Button → Button.tsx, UserCard → UserCard.tsx.
✗ MUSTs y sobreajuste
- ✗Mayúsculas e imperativos a gritos
- ✗Ejemplos presentados como reglas fijas
- ✗Ninguna explicación del porqué
- ✗Falla en cualquier caso nuevo
✓ Principio + porqué
- ✓Imperativo tranquilo y normal
- ✓Los ejemplos ilustran, no encorsetan
- ✓Explica la razón detrás
- ✓Generaliza a casos nuevos
Por qué importa el porqué
El modelo es bueno razonando a partir de principios. Cuando explicas la razón («porque el resolver de imports depende de esto»), aplica la regla correctamente en situaciones que nunca previaste. Los MUST en mayúsculas solo expresan ansiedad: no aumentan el cumplimiento y además fomentan memorizar en vez de entender.
🎯 Antipatrón: description vaga
El tercer antipatrón, y el más letal. La description es el activador: el único nivel de la skill que siempre permanece en el contexto. Si es vaga, la skill nunca se activa (subactivación) o se activa en el contexto equivocado. Una skill brillante con una description deficiente es invisible.
activador malo vs. activador bueno:
# ✗ VAGA (nunca dispara ou dispara errado) description: Ajuda com código. # ✓ ESPECÍFICA (diz O QUE faz E QUANDO usar) description: Gera componentes React com a convenção do time (PascalCase, hooks, props tipadas). Use quando o usuário pedir um novo componente, refatorar JSX, ou criar UI em React/Next. Acione também ao mencionar "componente", "tela" ou "página" num projeto React.
Di QUÉ hace
La capacidad concreta, no el área. "Genera componentes React con la convención del equipo" — no "ayuda con frontend".
Di CUÁNDO usarla
Los triggers explícitos: verbos y sustantivos que aparecen en la solicitud del usuario. "Úsala cuando te pidan un componente nuevo, refactorizar JSX...".
Sé un poco pushy
El modelo tiende a activarse menos de lo debido. Incluye «actívala también cuando se mencione X» para los casos límite. Es mejor que se active de más a que no aparezca cuando debería.
💡 La prueba de 5 segundos
Lee solo la description (sin el cuerpo). ¿Puedes decir exactamente ante qué solicitud debería activarse? Si dudaste, el modelo también dudará. La description es la única parte que determina si la skill existe en la práctica.
✅ Resumen del módulo
Próximo módulo:
5.2 — 🚀 Publicar, versionar y medir — decidiste que vale la pena y evitaste los antipatrones; ahora lleva la skill al mundo: repo, git, skills.sh, evals de activación y el ciclo de vida