🧭 La revisión de código aplicada a las automatizaciones
Un workflow de automatización no es «solo unos bloques conectados». Es código visual: tiene lógica, dependencias, puntos de falla y deuda técnica. Y, como el código, se deteriora en silencio. La idea central de esta skill es sencilla y poderosa: tratar un workflow n8n exactamente como tratarías un pull request, con un arquitecto sénior que hace la auditoría que nadie se detuvo a hacer.
🎯 La promesa en una frase
"Creas automatizaciones. Claude las revisa como un ingeniero sénior." El valor no está en encontrar errores menores, sino en convertir una caja negra que "a veces funciona" en un diagnóstico que dice exactamente qué se va a romper, dónde y cómo solucionarlo.
Cinco categorías fijas, en el mismo orden, cada vez.
Cada elemento tiene el arreglo concreto, no un consejo vago.
Tono de alguien que ya vio cómo esto falla en producción.
"Esto va a fallar" > "quizás considera...".
📥 Cinco formas de entrada
Una skill solo se usa de verdad si acepta el material que la persona tiene ahora — no el material idealizado. El reviewer se diseñó para aceptar entradas imperfectas y ser honesto sobre lo que cada formato permite (o no) evaluar.
| Formato de entrada | Lo que se puede evaluar |
|---|---|
| JSON completo | Todo: expresiones, credenciales, parámetros, conexiones. La auditoría más profunda. |
| JSON parcial | El subconjunto de nodos enviado; indica lo que no se puede inferir del resto. |
| Texto sin formato | Reconstruye la estructura asumida, declara las suposiciones y revisa basándose en ellas. |
| Mensaje de error | Modo de depuración: pide node, el texto completo del error y la configuración; luego diagnostica. |
| Captura de pantalla | Lee los nodos, tipos y conexiones visibles; declara lo que solo revelaría el JSON. |
💡 Consejo de diseño: degradación honesta
En la captura de pantalla, la skill hace lo que puede (nombres, estructura, conexiones faltantes) y termina con: "Comparte el JSON para una auditoría completa, incluidas las expresiones y los parámetros." Nunca finge haber visto lo que no vio. Esa honestidad es lo que evita que se confíe ciegamente en el resultado.
🌐 Consejo: responde en el idioma del usuario
Regla explícita del SKILL.md: responde siempre en el idioma en que la persona escribe, aunque las etiquetas del workflow estén en otro idioma. Un workflow con nodos en alemán y una pregunta en portugués recibe la respuesta en portugués.
Acepta lo que la persona tiene a mano.
Declara lo que asumió antes de revisar.
Di qué no pudo evaluar.
Si es vago, pide UNA cosa específica.
🚦 Las cinco categorías de la revisión
El corazón de la skill es un framework fijo de cinco categorías que siempre se ejecutan, en el mismo orden, sin saltarse ninguno. Si una categoría está limpia, la skill lo indica en una línea y continúa. Ejecutar la misma lista de verificación cada vez es lo que elimina el sesgo del revisor.
🔴 Errores y fallos
Lo que realmente va a fallar: campo obligatorio vacío, credencial hardcodeada, expresión que hace referencia a un campo inexistente, conexión faltante, método HTTP incorrecto, IF/Switch sin fallback.
🟡 Error silencioso
Ahora no se rompe, pero después falla en silencio: sin Error Trigger, HTTP sin retry/timeout, escrituras en la base de datos sin comprobar duplicados y ninguna alerta cuando falla.
🔵 Rendimiento y eficiencia
Funciona, pero cuesta tiempo/dinero/llamadas: API innecesaria, sin paginación, loop donde cabría un batch, activador demasiado frecuente, nodos Set redundantes.
🟢 Estructura y mantenibilidad
Lo que se vuelve una pesadilla en 6 meses: nodos "HTTP Request1", sin sticky notes, lógica de negocio enterrada en una expresión, workflow gigante que debería convertirse en un subworkflow.
✅ Resumen y lista de prioridades
Termina con correcciones clasificadas en tres niveles — ahora / después / opcional — más una nota de 0 a 10 con un veredicto de una frase.
📊 Por qué funcionan cinco categorías fijas
- • Cobertura garantizada: "no omitas ninguna categoría" evita que la revisión se detenga en el primer error evidente.
- • Severidad legible: los colores 🔴🟡🔵🟢 indican de un vistazo qué es urgente y qué es solo un retoque.
- • Repetible: dos workflows diferentes reciben la misma perspectiva — comparable y sin el humor del día.
Siempre las cinco, en ese orden.
🔴 fallo · 🟡 silencio · 🔵 costo.
Di en una línea cuándo está OK.
Ahora / después / opcional + nota.
🔇 El fallo silencioso
Esta es la categoría más valiosa y la más ignorada. El error que aparece es fácil: lo anuncia a gritos y alguien lo corrige. El error que desaparece — el registro que no se guardó, el lead que no entró, el webhook que devolvió 500 y nadie vio: eso es lo que erosiona la confianza en todo el sistema. La categoría 🟡 existe para buscar exactamente estos casos.
✓ Salvaguardas que exige la skill
- ✓Un Error Trigger conectado a una alerta (Slack, correo electrónico).
- ✓Reintento y tiempo de espera en los nodos HTTP de larga duración.
- ✓Validación de respuestas en los webhooks.
- ✓Verificación de duplicados antes de escribir en la base de datos/Airtable.
- ✓Decisión consciente de "Continue on Fail" (a veces se activa, a veces no).
✗ Síntomas de una falla silenciosa
- ✗"El workflow se ejecuta, pero algunos registros no se actualizan."
- ✗"Funciona cuando lo pruebo, pero falla de vez en cuando."
- ✗Ninguna notificación cuando una ejecución falla de madrugada.
- ✗Se acumulan duplicados porque nada verifica antes de insertar.
- ✗Un Schedule Trigger desconectado que nadie notó.
El formato de cada hallazgo 🟡
⚠️ [Node o sección] — [salvaguarda faltante] Riesgo: [lo que fallará sin aviso] Fix: [qué agregar, en concreto]
Fíjate en los tres campos: dónde, cuál es el riesgo e la reparación. Sin el riesgo explícito, nadie prioriza; sin el fix, nadie actúa.
La red de seguridad mínima.
Una API inestable no interrumpe el flujo.
Lo sabes antes que el cliente.
La pregunta que guía la categoría.
💸 Costo y facilidad de mantenimiento
Las categorías 🔵 y 🟢 se ocupan de lo que no se rompe hoy, pero cuesta caro mañana: la 🔵 analiza el dinero y el tiempo que el workflow desperdicia en producción; la 🟢 analiza las horas que «tú dentro de 6 meses» perderás intentando entender qué hace cada node.
✓ Workflow eficiente y legible
- ✓Operación por lotes en lugar de un bucle elemento por elemento.
- ✓Paginación preparada para grandes conjuntos de datos.
- ✓Busca solo los campos que vas a usar, no el objeto entero.
- ✓Nodes con nombres descriptivos y sticky notes en la lógica compleja.
- ✓Secciones claras: entradas → procesamiento → salidas.
✗ Lo que dispara los costos y consume tiempo
- ✗El bucle hace 1 llamada a la API por elemento: pagas por cada una.
- ✗Se activa cada minuto cuando cada hora sería suficiente.
- ✗Nodes "Set3" y "HTTP Request1": nadie sabe qué hacen.
- ✗Lógica de negocio enterrada en una expresión de 200 caracteres.
- ✗Un workflow monstruoso que debería ser tres subworkflows.
🔵 El formato del hallazgo de rendimiento
🔵 [Node ou padrão] — [ineficiência] Impacto: [custo / velocidade / confiabilidade] Otimização: [melhoria específica]
💡 Consejo: la prueba de los «6 meses»
La pregunta guía de la categoría 🟢 es: "si abro este workflow dentro de 6 meses, sin contexto, ¿lo entiendo en 2 minutos?" Si la respuesta es no, hay un hallazgo de mantenibilidad, y la solución casi siempre es cambiar el nombre de un node, extraer la lógica a un Set node o agregar una sticky note.
Menos llamadas, menos costo.
Los datasets grandes no se desbordan.
"Buscar contactos" > "HTTP Request1".
Documentan la lógica difícil.
🏗️ Construir tu reviewer
Ahora juntas todo en un SKILL.md de autor. La estructura se puede replicar para revisar cualquier artefacto técnico: basta con cambiar el dominio y la lista de verificación. Lo que hace que el reviewer sea bueno no es n8n: es el tono directo, el formato de los hallazgos y el veredicto honesto.
Prompt copiable: esqueleto del SKILL.md
---
name: workflow-reviewer
description: Reviews automation workflows for errors, inefficiencies and
missing best practices. Use whenever a user shares a workflow JSON,
pastes node configs, describes their setup in plain text, sends an
error message, or asks "what's wrong with my automation". Trigger
even on a partial workflow or a single node.
---
# Workflow Reviewer
You are an expert automation engineer doing a senior code review.
No fluff, no vague advice. Name the exact node. Give the exact fix.
## Run ALL five categories, in order. Skip none.
1. 🔴 ERRORS & BREAKS — what will fail in production
2. 🟡 MISSING ERROR HANDLING — what will fail silently
3. 🔵 PERFORMANCE — unnecessary calls, cost leaks, slow loops
4. 🟢 STRUCTURE — naming, maintainability, subworkflow candidates
5. ✅ SUMMARY — priority fix list + OVERALL SCORE: [X/10]
For each finding use:
[emoji] [Node Name] — [issue]
Fix: [exact fix, 1-2 sentences]
If a category is clean, say so in one line. If the input is too vague,
ask ONE specific question. If it's well-built, say so — don't invent problems.
Ejemplo de salida — auditoría real (recreación ilustrativa)
🔴 ERRORS & BREAKS
❌ Schedule Trigger — node desconectado do resto do fluxo.
Fix: conecte a saída do Schedule Trigger ao node "Buscar leads".
❌ Parse JSON — expressão {{ $json.data.items }} quebra quando a API
retorna {error}. Fix: adicione um IF checando $json.error antes do parse.
🟡 MISSING ERROR HANDLING
⚠️ HTTP Request "Enviar Slack" — sem retry nem alerta.
Risco: notificação some se o Slack der 429. Fix: ative retry (3x) e
conecte um Error Trigger a um e-mail de fallback.
⚠️ Airtable "Inserir" — sem checagem de duplicata.
Risco: leads duplicados a cada re-execução. Fix: use "Upsert" pela chave email.
🔵 PERFORMANCE
🔵 Loop "Para cada lead" — 1 chamada HTTP por item.
Impacto: ~600 chamadas/dia, custo e lentidão. Otimização: troque por
uma chamada batch enviando o array inteiro.
🟢 STRUCTURE
🟢 Nodes "Set3", "HTTP Request1" — nomes default.
Sugestão: renomeie para "Montar payload" e "Buscar perfil".
✅ SUMMARY
PRIORITY FIXES (do these now):
1. Conectar o Schedule Trigger.
2. Tratar o parse de JSON na resposta de erro.
3. Adicionar Error Trigger + retry no Slack.
IMPROVEMENTS (next): batch no loop; upsert no Airtable.
OPTIONAL: renomear nodes; sticky notes nas seções.
OVERALL SCORE: 5/10 — funciona no caminho feliz, frágil em produção.
Salida recreada con fines didácticos: ilustra el formato, no es un informe real de un cliente.
⭐ Las reglas de tono que marcan la diferencia
- • Sé directo: "esto va a fallar en producción" > "quizás quieras considerar...".
- • Nombra el node exacto: el feedback vago no sirve.
- • Da la solución, no la dirección: "agrega un Error Trigger conectado a Slack" > "agrega manejo de errores".
- • Elogia lo que está bien: si el workflow es sólido, dilo; no inventes problemas.
- • Cuando preguntan «¿está bien?»: da una calificación honesta + los 3 problemas más importantes; no solo valides.
✍️ Ejercicios prácticos
Revisa uno de tus flujos. Toma un workflow que tengas (o describe uno por escrito) y recorre mentalmente las cinco categorías. Anota al menos un hallazgo 🟡 de fallo silencioso que nunca habías notado.
Crea un SKILL.md ejecutable. Copia el esqueleto de arriba en ~/.claude/skills/workflow-reviewer/SKILL.md, ajusta la description con sus activadores y prueba pidiéndole a Claude que revise un flujo descrito en texto.
Generaliza. Cambia el dominio: adapta el reviewer para auditar un schema de base de datos o un archivo de configuración de CI. ¿Cuáles de las cinco categorías cambian? ¿Cuáles permanecen idénticas?
Prueba el "¿está bien?". Pídele a tu reviewer que evalúe un flujo deliberadamente bien hecho. ¿Resiste la tentación de inventar problemas y da una nota alta honesta?
📌 Resumen del módulo
Siguiente Módulo:
4.2 — 🔥 Local Leads Abundance System: encadenar varias skills en un pipeline multiagente.