🎣 Definir el disparador (a description que hace que la skill se active)
A description en el frontmatter, dile al modelo cuándo usar la skill. Una buena tiene verbos de acción + activadores concretos ("Úsala al diagnosticar la madurez de IA de una empresa descrita en texto"). Description vaga = la skill nunca se activa. Es el detalle que separa una skill que funciona de una que duerme en el repositorio.
✓ Buena description
- ✓Empieza con verbo de acción ("Úsalo al diagnosticar...")
- ✓Disparador concreto: «empresa descrita en texto»
- ✓Dice el "usar cuando" — el modelo sabe cuál es el momento adecuado
✗ Description débil
- ✗Genérica: «ayuda con estrategia de IA»
- ✗Sin disparador — no indica cuándo aplicarlo
- ✗Ambigua — choca con otras skills y nunca se activa
// .claude/skills/diagnostico-ia/SKILL.md
--- name: diagnostico-ia description: Use ao diagnosticar a maturidade de IA de uma empresa descrita em texto — gera maturidade 1-5, quick wins (esforço × impacto) e um roadmap 30/60/90. --- # Diagnóstico de IA ## Passos 1. Ler nome + descrição da empresa. 2. Pontuar a maturidade de IA numa escala 1-5. 3. Listar 3 quick wins (baixo esforço, alto impacto). 4. Propor um roadmap 30/60/90 dias. 5. Devolver em Markdown, pronto para virar entregável. ## Referências - referencias/maturidade.md - referencias/quick-wins.md
💡 Consejo práctico
Escribe la description pensando en cómo la lee el modelo: «si viera esta frase, ¿sabría que es AHORA cuando debo usar la skill?». Si la respuesta es «quizás», reescríbela con un desencadenante más concreto. La description es la puerta: sin ella, nadie entra.
el «cuándo usar»
acción concreta
name + description
vaga = nunca se activa
📝 Escribir el cuerpo (pasos claros y deterministas)
El cuerpo en Markdown enumera pasos numerados para que el resultado sea repetible: leer sobre la empresa → calificar la madurez del 1 al 5 → enumerar 3 quick wins → proponer una hoja de ruta 30/60/90. Determinista significa que, al ejecutarlo dos veces, recibes el mismo estructura — no improviso. Cada paso es una orden, no una sugerencia.
Leer la empresa
Extrae el nombre, el sector, el tamaño y el contexto del texto recibido. Sin eso, el diagnóstico es genérico: el paso 1 sirve de base para todos los demás.
Calificar la madurez (1-5)
Asigna una nota del 1 al 5 con una justificación breve. Una escala fija permite comparar los resultados entre empresas: se convierte en una métrica, no en una opinión.
Enumera 3 quick wins
Exactamente tres: poco esfuerzo, alto impacto. El número fijo evita listas infladas y obliga a priorizar de verdad.
Proponer una hoja de ruta 30/60/90
Tres ventanas, acciones concretas en cada una. Devuelve el resultado en Markdown, listo para convertirse en un entregable: el cliente lo abre y lo ejecuta.
pasos en orden
misma estructura
1-5 comparable
Markdown listo
📎 Adjuntar referencias (las cheat sheets de la T2)
La skill apunta a archivos de apoyo —los cheat sheets de madurez y quick wins que sintetizaste en la Trilha 2—, que se cargan solo cuando hacen falta. Es el RAG perezoso aplicado: el SKILL.md queda conciso, pero la skill adquiere el rigor de consultoría al momento de producir.
📄 referencias/maturidade.md
La rúbrica de la escala del 1-5: qué caracteriza cada nivel, señales y ejemplos. Se carga cuando el paso 2 necesita asignar una puntuación.
📄 referencias/quick-wins.md
El catálogo de victorias rápidas por departamento, mapeadas según esfuerzo × impacto. Se incorpora cuando el paso 3 enumera las quick wins.
// estructura de la carpeta de la skill
.claude/skills/diagnostico-ia/
├── SKILL.md
└── referencias/
├── maturidade.md
└── quick-wins.md
💡 Consejo práctico
No pegues el contenido de las cheat sheets dentro del SKILL.md. Indica la ruta (referencias/maturidade.md) y deja que el modelo abra el archivo solo cuando el paso lo requiera. SKILL.md conciso = skill que se activa rápido y no desperdicia contexto.
carga cuando lo necesitas
SKILL.md ligero
cheat sheets de la T2
contexto a medida
🧪 Probar la skill con un caso real
Ejecuta la skill en una empresa real y verifica tres cosas: ¿se activó por sí sola (¿funcionó la descripción)? ¿El resultado tiene madurez + logros rápidos + hoja de ruta? ¿El formato está listo para entregar? La prueba es donde la teoría se enfrenta a la fricción real.
// lo que escribes en Claude Code
Use a skill diagnostico-ia para a empresa "Stripe": B2B payments, fintech, ~8000 funcionários.
🔍 La lista de verificación de la prueba
- •¿Se activó por sí sola? Si tuviste que forzarlo, la description es débil; vuelve al tema 1.
- •¿Salida completa? Madurez 1-5 + 3 quick wins + roadmap 30/60/90 — los tres incluidos.
- •¿Lista para entregar? Markdown limpio, sin borradores ni preguntas en medio.
empresa de verdad
¿se mantuvo sola?
los 3 bloques
entregable limpio
🔁 Iterar y empaquetar
La primera versión rara vez acierta a la primera. Ajusta la description y los pasos según lo que mostró la prueba, completa la carpeta de la skill (SKILL.md + referencias) y déjala lista. Iterar es el trabajo de verdad — la primera versión es solo el borrador que va tomando forma.
✓ Skill lista
- ✓Se activa por sí sola — la description cierra el disparador sin que tengas que forzarlo
- ✓Salida consistente — la misma estructura cada vez que se ejecuta
- ✓Las referencias se cargan — los cheat sheets aparecen en el momento adecuado
✗ Todavía no
- ✗No activa — tienes que pedir la skill por su nombre cada vez
- ✗La salida varía — a veces se salta la hoja de ruta, a veces inventa un formato
- ✗SKILL.md inflado — contenido que debería estar en las referencias
💡 Consejo práctico
Itera una cosa a la vez: ajusta solo la description y prueba; después, solo los pasos y vuelve a probar. Cambiar todo a la vez oculta lo que realmente lo resolvió. Los ciclos cortos te llevan más rápido a la versión que se activa.
description + pasos
carpeta completa
un cambio a la vez
consistente y concisa
🏷️ Versionar y compartir
Versiona la skill en Git (junto con el proyecto) y, opcionalmente, compártela con el equipo o la comunidad. El historial te da una evolución rastreable; el versionado protege el activo; compartirla construye autoridad. La skill deja de ser un archivo suelto y se convierte en una pieza de tu repositorio.
💡 Consejo práctico
Haz commit de una skill junto con el proyecto que la usa, no en un repositorio aparte. Así viaja con el contexto: quien clona el proyecto recibe la herramienta lista. Un buen mensaje de commit ("ajusta el activador de diagnostico-ia") ya forma parte del historial.
junto al proyecto
evolución rastreable
el activo seguro
tú construyes
✅ Resumen del módulo
🎯 Misión 3.2 — diagnostico-ia en línea
Pon en marcha tu primera skill:
- Crear
.claude/skills/diagnostico-ia/SKILL.mdcon frontmatter + 5 pasos. - Adjuntar las cheat sheets de la T2 como referencias.
- Ejecuta la skill para 1 empresa real.
- Itera la description hasta que se active por sí sola.
Éxito: la skill diagnostico-ia se ejecuta y genera un minidiagnóstico (madurez + quick wins + roadmap). Lo que obtuviste: el primer engranaje de la Fábrica — reutilizable y versionado.
Siguiente módulo:
3.3 — La skill de documentos (DocX/PPTX/Excel/PDF)