🧭 Code review applied to automations
An automation workflow isn’t “just a few blocks connected.” It’s visual code: has logic, dependencies, failure points, and technical debt. And like code, it quietly rots. The core idea behind this skill is simple and powerful: treat an n8n workflow exactly as you would a pull request — with a senior architect doing the audit no one stopped to do.
🎯 The promise in one sentence
"You build automations. Claude reviews them like a senior engineer." The value isn't in spotting cute little errors—it's in turning a black box that "sometimes works" into a diagnosis that says exactly what will break, where, and how to fix it.
Five fixed categories, in the same order, every time.
Each item has a concrete fix, not vague advice.
The tone of someone who’s seen this break in production.
"This will break" > "maybe consider...".
📥 Five Input Methods
A skill is only truly used if it accepts the material the person has now — not the idealized material. The reviewer was designed to handle imperfect input and be honest about what each format does (or doesn’t) allow you to evaluate.
| Input format | What you can evaluate |
|---|---|
| Complete JSON | Everything: expressions, credentials, parameters, connections. The deepest audit. |
| Partial JSON | The subset of nodes sent; it indicates what can’t be inferred from the rest. |
| Plain text | Rebuilds the assumed structure, states the assumptions, and revises based on them. |
| Error message | Debug mode: asks for the node, full error text, and config; then diagnoses the issue. |
| Screenshot | Read visible nodes, types, and connections; state what only the JSON would reveal. |
💡 Design tip: honest degradation
In the screenshot, the skill does what it can (names, structure, missing connections) and ends with: "Share the JSON for a complete audit, including expressions and parameters." It never pretends to have seen what it hasn’t. That honesty is what prevents people from blindly trusting the output.
🌐 Tip: respond in the user's language
Explicit rule in SKILL.md: always respond in the language the person writes in, even if the workflow labels are in another language. A workflow with nodes in German and a question in Portuguese gets a response in Portuguese.
Accepts what the person has on hand.
States what it assumed before reviewing.
Say what you couldn’t evaluate.
If it’s vague, ask for ONE specific thing.
🚦 The five review categories
The heart of the skill is a fixed five-category framework that always run in the same order, without skipping any. If a category is clean, the skill says so in one line and moves on. Running the same checklist every time removes reviewer bias.
🔴 Errors & Breakages
What will actually fail: an empty required field, a hardcoded credential, an expression referencing a nonexistent field, a missing connection, the wrong HTTP method, an IF/Switch without a fallback.
🟡 Silent error
Doesn’t break now, but fails silently later: no Error Trigger, HTTP without retry/timeout, database writes without checking for duplicates, no alert when it fails.
🔵 Performance & Efficiency
Works, but costs time/money/calls: unnecessary API, no pagination, a loop where a batch would work, a trigger that fires too often, redundant Set nodes.
🟢 Structure & maintainability
What becomes a nightmare in 6 months: nodes named "HTTP Request1," no sticky notes, business logic buried in an expression, a giant workflow that should be a subworkflow.
✅ Summary & priorities list
Ends with ranked fixes in three tiers — now / later / optional — plus a score from 0 to 10 and a one-sentence verdict.
📊 Why five fixed categories work
- • Guaranteed coverage: "don't skip any category" keeps the review from stopping at the first obvious error.
- • Readable severity: the 🔴🟡🔵🟢 colors tell you at a glance what’s urgent and what’s polish.
- • Repeatable: Two different workflows get the same lens—comparable and free from the mood of the day.
Always all five, in order.
🔴 breakage · 🟡 silence · 🔵 cost.
Say in one line when it’s OK.
Now / later / optional + note.
🔇 The Silent Failure
This is the most valuable and most overlooked category. The error that appears is easy: it screams, someone fixes it. The error that some — the record that wasn’t saved, the lead that didn’t come in, the webhook that returned 500 and no one noticed — that’s what erodes trust in the entire system. The 🟡 category exists to hunt down exactly these.
✓ Safeguards required by the skill
- ✓An Error Trigger connected to an alert (Slack, email).
- ✓Retry and timeout in long-running HTTP nodes.
- ✓Response validation in webhooks.
- ✓Duplicate check before writing to the database/Airtable.
- ✓Deliberate "Continue on Fail" decision (sometimes enabled, sometimes not).
✗ Signs of silent failure
- ✗"The workflow runs, but some records don't update."
- ✗"It works when I test it, but fails now and then."
- ✗No notification when a run fails overnight.
- ✗Duplicates piling up because nothing checks before inserting.
- ✗A disconnected Schedule Trigger that no one noticed.
The format for each finding 🟡
⚠️ [Node or section] — [missing safeguard] Risk: [what will silently break] Fix: [what to add, specifically]
Notice the three fields: where, what the risk is e the fix. Without the risk spelled out, no one prioritizes it; without the fix, no one acts.
The minimum safety net.
An unstable API doesn't break the flow.
You know before the client does.
The question that guides the category.
💸 Cost and maintainability
The 🔵 and 🟢 categories take care of what won’t break today but will cost a lot tomorrow: 🔵 looks at the money and time the workflow wastes in production; 🟢 looks at the hours that “you six months from now” will lose trying to understand what each node does.
✓ Efficient, readable workflow
- ✓Batch operation instead of an item-by-item loop.
- ✓Pagination handled for large datasets.
- ✓Search only the fields you’ll use, not the entire object.
- ✓Nodes with descriptive names and sticky notes for complex logic.
- ✓Clear sections: inputs → processing → outputs.
✗ What drains cost and time
- ✗Loop making 1 API call per item — you pay for each one.
- ✗A trigger every minute when once an hour would do.
- ✗Nodes "Set3" and "HTTP Request1" — nobody knows what they do.
- ✗Business logic buried in a 200-character expression.
- ✗A monster workflow that should be three subworkflows.
🔵 The performance finding format
🔵 [Node ou padrão] — [ineficiência] Impacto: [custo / velocidade / confiabilidade] Otimização: [melhoria específica]
💡 Tip: the "6 months" test
The guiding question for the 🟢 category is: "if I open this workflow 6 months from now, with no context, can I understand it in 2 minutes?" If the answer is no, that’s a maintainability finding—and the fix is almost always to rename a node, extract logic into a Set node, or add a sticky note.
Fewer calls, lower cost.
Large datasets don't overflow.
"Search contacts" > "HTTP Request1".
Document the difficult logic.
🏗️ Build your reviewer
Now you bring it all together in a SKILL.md original. The structure is replicable for reviewing any technical artifact — just swap out the domain and checklist. What makes the reviewer good isn't n8n: it's the direct tone, the findings format, and the honest verdict.
Copyable prompt — SKILL.md skeleton
---
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.
Output example — real audit (illustrative recreation)
🔴 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.
Output recreated for educational purposes—illustrates the format, not a real client report.
⭐ The tone rules that make a difference
- • Be direct: "this will break in production" > "you might want to consider...".
- • Name the exact node: vague feedback is useless.
- • Give the fix, not the direction: "add an Error Trigger connected to Slack" > "add error handling".
- • Praise what’s good: if the workflow is solid, say so — don't invent a problem.
- • When someone asks “is it good?”: give an honest rating + the 3 biggest problems; don't just validate.
✍️ Hands-on exercises
Review one of your workflows. Choose a workflow you have (or describe one in text) and mentally run through the five categories. Note at least one 🟡 silent failure you hadn't noticed before.
Create a runnable SKILL.md. Copy the skeleton above to ~/.claude/skills/workflow-reviewer/SKILL.md, adjust the description with its triggers and test it by asking Claude to review a flow described in text.
Generalize. Switch domains: adapt the reviewer to audit a database schema or a CI configuration file. Which of the five categories change? Which stay exactly the same?
Test the “is this good?” check. Ask your reviewer to evaluate a deliberately well-crafted flow. Do they resist the temptation to invent problems and give it an honestly high score?
📌 Module Summary
Next Module:
4.2 — 🔥 Local Leads Abundance System: chain multiple skills into a multi-agent pipeline.