n8n-expert — livello di conoscenza "di casa" per n8n

Scopo e confini (leggi prima)

Questa skill è il livello di casa (context layer) su n8n: ciò che è specifico di Ettore —
stack, convenzioni, agenti, lezioni apprese, gotcha. NON è un catalogo nodi né un riferimento
generico: quella è commodity coperta meglio da strumenti dedicati (vedi "Tooling correlato").

Due livelli, non sovrapporli:

• Verità a livello nodo / validazione → usa n8n-mcp (525+ nodi documentati + validazione) e, per il dettaglio versionato, il cluster vault 01_STRUMENTI_di_LAVORO/n8n/progettazione/.
• Contesto di casa → questa skill.

Quando attivare

Ogni volta che si progetta, costruisce, debugga o ragiona su n8n nel contesto di Ettore:
workflow, AI Agent (Mr.Kapable), scelte Cloud vs self-hosted, convenzioni, error handling.
NON per operare n8n via API/MCP (quello è il connettore/MCP).

Modello mentale (qui si risolve l'80% della confusione)

• n8n = automazione visuale: nodi collegati in un workflow che parte da un trigger e fa scorrere dati da un nodo al successivo.
• I dati viaggiano SEMPRE come array di item [{ json: {...}, binary: {} }].
• Architettura base: Trigger → Elabora → Trasforma → Output, con rami di logica e un error handler.
• Regola d'oro: nomi nodi descrittivi, credenziali mai a mano nei nodi, ogni workflow di produzione ha il suo Error Trigger.
• Per l'elenco nodi e i loro parametri NON andare a memoria: interroga n8n-mcp o il catalogo_nodi del vault.

Espressioni {{ }} (essenziale + gotcha)

{{ $json.campo }} · {{ $node["Nome"].json.campo }} · {{ $input.first().json.campo }} · {{ $input.all() }}
{{ $now }} · {{ $now.toISO() }} · {{ $today }} · {{ $vars.x }} · {{ $env.API_KEY }} (solo self-hosted)
{{ $workflow.name }} · {{ $execution.id }}

⚠️ Gotcha critico: i dati di un Webhook stanno sotto `$json.body` (non $json diretto).

Nodo Code (JS/Python) — gotcha che fanno perdere tempo

• JS: deve restituire un array di item [{ json: {...} }]. Accesso dati $input.all()/first()/item.
• Python nel Code node: niente librerie esterne (no requests/pandas/numpy), solo standard library. Regola pratica: usa JS per il 95% dei casi.
• Code Tool (nodo dell'AI Agent) ≠ Code node: nodo diverso, ritorna una stringa (JSON.stringify(...)) non [{json}], e $fromAI() non funziona lì. Non confonderli.

Pattern di workflow

Sequenziale · Split/Merge · Routing (IF/Switch) · Loop (Split In Batches) · Gestione errori (Error
Trigger). In produzione l'error handling non è opzionale.

AI Agent — il caso Mr.Kapable (cuore del nostro stack)

L'AI Agent è un loop di ragionamento (chiama tool → legge → ragiona → decide). Ingredienti:

• System Prompt — ruolo/capacità/vincoli/formato (versionalo: mrk_prompt_v7→v11).
• Tools — ognuno con una descrizione che spiega QUANDO usarlo (conta più del nome).
• Memoria — window buffer / summary / vector store.

Struttura Mr.Kapable: `Telegram Trigger → AI Agent (Claude Sonnet via OpenRouter) → [tool: Airtable,
Supabase docs, ricerca Brave/Perplexity, sub-agente Ricercatore] → risposta Telegram`.
Lezioni di casa: valida un tool alla volta; la descrizione del tool è il vero prompt;
versiona il system prompt; esporta i workflow come backup (la perdita è già successa).

Cloud vs self-hosted (situazione di Ettore)

• n8n Cloud — stack attuale: istanza "hectorai", collegata via API REST. Gestito, sempre aggiornato; $env e alcune funzioni avanzate limitate. Scelto dopo il "casino Docker".
• Self-hosted (Docker sul minipc) — controllo totale, esecuzioni illimitate, $env/filesystem; backup e aggiornamenti a tuo carico.
• Regola: Cloud finché le automazioni sono poche/leggere; self-hosted per esecuzioni illimitate, accesso al disco, o integrazione con Claude Code.

Problemi noti → soluzioni (di casa)

• Tool dell'agente non chiamato → descrizione vaga: riscrivi spiegando quando usarlo.
• $fromAI/parametri vuoti nei tool → vincolo noto (issue #16095): imposta i parametri esplicitamente.
• Dati undefined → riferimento a campo/nodo sbagliato: controlla la struttura json dell'esecuzione precedente.
• Timeout su liste lunghe → Split In Batches. · Risposta AI troppo lunga per Telegram → limita i caratteri nel prompt. (Per gli errori di validazione dei nodi, delega a n8n-mcp: ha profili e catalogo errori.)

Fonte-verità viva (dettaglio nel vault, non a memoria)

Cluster: C:\Users\Ettore\Claude\Projects\MD_DB_v1\01_STRUMENTI_di_LAVORO\n8n\

• 00_indice_n8n.md · guida/n8n_guida_completa.md
• progettazione/ — 01_schema_json_workflow.md, 02_catalogo_nodi.md, 03_libreria_pattern.md, 04_glossario_espressioni.md, 05_checklist_progettazione.md, 06_convenzioni_naming.md + template JSON.
• automazioni/ (backup workflow) · progetti/ (brief). Scheda: 07_n8n.md. Investimenti: 02_CONOSCENZA/04_investimenti_finanza/progetto_trading/05_automazioni_n8n_investimenti.md. Doc ufficiale: docs.n8n.io.

Tooling correlato (il 90% commodity: adotta, non riscrivere)

• `czlonkowski/n8n-mcp` (MIT) — MCP server con documentazione di 525+ nodi + validazione workflow. È il motore a livello nodo. Da adottare dopo vetting (skill-vetter/Bartolomeo) + OK di Ettore.
• `czlonkowski/n8n-skills` — suite di 14 skill Claude Code costruita sopra n8n-mcp (espressioni, uso tool MCP, pattern, errori di validazione, config nodi, Code node JS/Python, Code Tool). Valutabile in un secondo momento; richiede n8n-mcp.
• Questa skill (n8n-expert) si posa sopra quel motore e aggiunge il contesto di casa.

Mantenere e migliorare (migliorabile per design)

• Lezione nuova (vincolo/pattern/fix) → aggiungila qui E nel file vault pertinente, poi bumpa la versione.
• Tieni la skill allineata al cluster vault e a cosa deleghiamo a n8n-mcp (evita duplicazioni).
• Aggancio all'auto-miglioramento: usa self-improving-agent per catturare errori/correzioni n8n.

Changelog

• v2 (2026-07-09): ri-scopata a "livello di casa" a due livelli dopo ricerca sull'ecosistema esistente. Aggiunti gotcha (Webhook $json.body; Python Code node senza librerie esterne; Code Tool ≠ Code node); rimosso il catalogo nodi ridondante, delegato a n8n-mcp/vault; aggiunta sezione "Tooling correlato".
• v1 (2026-07-09): prima stesura, sintesi da 07_n8n.md + cluster n8n del vault.