--- name: awesomate-n8n description: Build, test, and fix the user's Awesomate-hosted n8n automations, data tables, and AI agents. Use when the user says "build me an automation", "automate this", "connect X to Y", "why did my workflow fail", "create a data table", "build an AI agent / chatbot", "make an n8n agent", "an agent I can talk to in Slack/Telegram", "what automations do I have", "what could I automate", or mentions n8n, workflows, executions, webhooks, or {slug}.awesomate.io. Reads and n8n Agents on every plan; building workflows needs Support Plus+. Companion to awesomate-hosting: same connection, same PAT. --- # Awesomate n8n — your automations from Claude Code The user's business runs n8n workflows on an Awesomate-hosted instance. You can know their WHOLE instance (every workflow, every node, every connection), look up live documentation for 500+ nodes and 2,500+ community templates, and — on Support Plus and above, with consent — build, test, and safely change automations, data tables, and AI agents. Their n8n API key never reaches this machine; every write is consent-gated, quota-limited, and audited on Awesomate's side. **Routing rule:** live facts about THEIR instance come from tools; judgment and patterns come from references; node schemas come from `awesomate_n8n_node_docs`, not memory. A tool answer beats a reference; a reference beats what you remember about n8n. Most users are business owners, not developers: plain words, one or two short questions at a time, recommend rather than quiz, and report results as outcomes ("your form now emails you") with URLs. ## 0. First run (every session) 1. `awesomate_whoami` — n8n tools act on whichever ACCOUNT this folder resolves to. Wrong slug → stop and fix the pin/connection first. Every tool response is stamped `account: ` — watch it. 2. `awesomate_n8n_context` — cache the result: - `consented: false` → give the user the `settingsUrl` and tell them where it lands: **n8n → Settings → Privacy** at `hub.awesomate.ai/settings?tab=privacy` → "Build and change automations from Claude Code". Privacy moved there; the plain `/settings` page no longer has it (old `?tab=privacy` links just redirect). Wait, then re-check. - `403 missingScopes` → token predates n8n support — reconnect from hub.awesomate.ai/claude (Connect Claude Code card). - `capabilities.builder: false` → reads only; building is Support Plus+. Be honest about it once, then help fully within reads. - `capabilities.variant` → FFMPEG variants have the media community nodes; Standard does not. Never assume a node exists — verify. - `limits` → daily build/test/datatable quotas; don't burn tests. - `instance` → community packages + counts (your recon baseline). 3. **Inventory pass** (before designing or diagnosing anything): `awesomate_n8n_workflows` (no id — every workflow as a node summary in ONE call) and, as needed, `awesomate_n8n_inspect` for `nodes`, `credentials`, `variables`, `datatables`. Cache this world picture for the session; refresh after your own writes. 4. **Writing in the business's name** (agent instructions, email or message templates, anything a customer reads): call `awesomate_business` first and use the owner's name, services, voice and contact details. Copy the values into the text you're building; don't build new workflows on `$vars.biz_*`, which are being replaced. Confirm anything marked *suggestion* first. For an agent that helps a job on the business map, add the job's `instructionLine` from `awesomate_business_map` action `job`. Read [references/platform-notes.md](references/platform-notes.md) BEFORE designing or diagnosing — it is the live truth for THIS platform ($vars not $env, `$json.body`, task-runner limits, activation semantics). When it conflicts with anything under `references/vendor/`, platform-notes wins. ## 0a. Health sweep — the guardian pattern At the START of any n8n session, alongside the context call: run `awesomate_n8n_errors` **with `days: 7`** and `awesomate_n8n_kpis` once. The `days` parameter is not optional in practice — the tool defaults to **30**, so omitting it sweeps a month and dresses old, already-fixed failures up as this week's news. If something is failing, surface it in ONE line in the user's language — "two of your automations failed overnight — want me to look?" — before proceeding with the asked task. If everything is green, say nothing and get on with it. Never let the sweep hijack the session; the user's ask comes first unless they say otherwise. **Zeros on a new account are not a clean bill of health.** A brand-new instance has no error history and no error-reporter workflow installed yet, so the sweep returns empty for the same reason it would on a flawless one. Check the inventory before you interpret it: no workflows, or workflows with no executions, means *there is nothing here yet* — say that, plainly ("nothing has run yet, so there's nothing to report — want to build the first one?"). Never let "no errors found" imply "everything is working". When diagnosing, trust `errorSummary` only when `confident: true` (it then also carries `errorType`, `code`, `lastNodeExecuted`). When `confident: false`, the failing-node name came from a heuristic and may be WRONG — verify the named node actually exists in the workflow before editing anything. ## 1. Tools | Task | Tool | |---|---| | Session context, consent, quotas, fingerprint | `awesomate_n8n_context` | | All workflows (node-level summaries) / one workflow (`detail: full\|structure`) | `awesomate_n8n_workflows` | | Node inventory, datatables (+rows), possibilities, credentials, $vars | `awesomate_n8n_inspect` | | Instance KPIs: exec totals, error rate, avg/p95 duration, time saved, 7d-vs-prior deltas (per-workflow adds `last_error_at` + `clean_days`) | `awesomate_n8n_kpis` | | Instance-WIDE error events grouped by fingerprint (category, workflow, node, occurrences, first/last seen) — "what is broken across everything" | `awesomate_n8n_errors` | | Execution/table/DB byte sizes + 24h per-workflow offenders ("your executions weigh 4GB") | `awesomate_n8n_storage` | | AI error-analyzer findings: clientSummary, needsClientAction, fixReady (Pro/Embedded + the **"Enable AI Error Diagnosis"** toggle under n8n → Settings → Privacy; read-only) | `awesomate_n8n_findings` | | Account-wide numbers in one call: executions by status, error rate, time saved, workflows total/active, chat sessions, 7-day trend, most recent live failure — the single best source for a status update or weekly report | `awesomate_dashboard_metrics` | | Executions list / detail / node-by-node debug | `awesomate_n8n_executions` | | Node schemas, node search, community templates, node-level validation | `awesomate_n8n_node_docs` | | Validate / create draft / update draft / activate / promote / rollback / delete draft | `awesomate_n8n_deploy` | | **n8n Agents** (the Agents tab, n8n 2.41+, every plan): status, then create / edit / validate / test / publish / channels via n8n's own agent tools | `awesomate_n8n_agents` | | Fire a test payload at an active workflow | `awesomate_n8n_test` | | Awesomate's template library: list, detail, install_plan (pauses on a missing credential), install, redeem, installs, activate, test, rollback | `awesomate_n8n_library` | | Book a session with the Awesomate team from their credits (session_types, slots, book, mine) | `awesomate_book_session` | | Create/alter data tables, write rows | `awesomate_n8n_datatable_write` | | Provision a Postgres DB + n8n credential | `awesomate_n8n_provision_pg` | | Wire a tested webhook workflow into one of their hosted apps (stores URL + secret on the app; returns the secret ONCE for the workflow's header check) | `awesomate_n8n_attach_to_app` | | Refresh these skills from the latest package | `awesomate_skill_update` | No `awesomate_n8n_*` tools in this session (fresh bootstrap, or the server didn't load)? Suggest a Claude Code restart once — then BUILD ANYWAY: [references/rest-fallback.md](references/rest-fallback.md) maps every tool to its REST endpoint, and the full loop works over it. Never tell the user they're blocked on a restart. ## 2. References — read on demand | When | Read | |---|---| | Before any design or diagnosis | [platform-notes.md](references/platform-notes.md) | | Designing tests, judging "is it done" | [testing-policy.md](references/testing-policy.md) | | Anything involving data tables | [datatables.md](references/datatables.md) | | An **n8n Agent** (Agents tab, Slack/Telegram channels, schedules, "set it up once, use it anywhere") — or unsure which kind of agent | [n8n-agents.md](references/n8n-agents.md) | | An AI Agent NODE inside a workflow / LLM steps | [ai-agents.md](references/ai-agents.md) | | A workflow is failing | [troubleshooting.md](references/troubleshooting.md) | | Error plans, error workflows, notify-the-owner on failure | [error-handling.md](references/error-handling.md) | | A weekly business report / "email me my numbers" | [recurring-reports.md](references/recurring-reports.md) | | Changing a LIVE workflow | [upgrade-loop.md](references/upgrade-loop.md) | | "What could I automate?" | [possibilities.md](references/possibilities.md) | | WordPress form → n8n | [wp-form-handler.md](references/wp-form-handler.md) | | A designed page served BY n8n — form, phone capture mini-app, approval page, status page | [webhook-pages.md](references/webhook-pages.md) | | Expression syntax details | [vendor/expressions/](references/vendor/expressions/SKILL.md) | | Code-node JavaScript | [vendor/code-node/](references/vendor/code-node/SKILL.md) | | Node configuration patterns | [vendor/node-configuration/](references/vendor/node-configuration/SKILL.md) | | Architecture patterns (webhook/API/DB/AI/scheduled) | [vendor/workflow-patterns/](references/vendor/workflow-patterns/SKILL.md) | | Validation errors & false positives | [vendor/validation/](references/vendor/validation/SKILL.md) | ## 3. The build loop (follow ALL six phases) **Phase 1 — Discovery.** Understand inputs/outputs, trigger, success criteria, error handling — in the user's words. Check the inventory FIRST: reuse existing credentials, $vars, tables, workflows. Email decision tree: existing Gmail/Google credential → reference its ID · none → offer an API-key credential (SMTP / Resend / SendGrid — instant) OR guided Gmail OAuth. A credential existing ≠ working. **Say the credential catch before they pick, not after it fails.** No tool creates a credential on their instance — the one exception is `awesomate_n8n_provision_pg`, which makes a Postgres one. Everything else, API-key credentials included, the user creates in n8n at `{instanceUrl}/home/credentials`; you then re-check the inventory to verify it exists. **Gmail and any other OAuth credential can only ever be finished in the browser** — the consent screen is Google's, so that branch always ends with them, no matter what you try. Flag it while they're choosing: *"Either way you'll paste it in on your n8n — an SMTP or Resend key is one box and a minute; Gmail means clicking through Google's permission screen. Tell me which and I'll give you the exact steps, then pick it up from there."* **Phase 2 — Design.** Resolve EVERY planned node and typeVersion via `awesomate_n8n_node_docs` (search similar community templates too — a proven template beats a blank canvas). Propose the architecture as an arrow diagram (`Webhook -> Validate -> Send Email -> Respond`). Reasoning/ execution separation; descriptive node names; every external call has an error plan. Externally-called workflows use a **webhook trigger with an explicit path** — never a Form Trigger. Data the automation must remember between runs → data table ([datatables.md](references/datatables.md)). **Phase 3 — Confirmation.** Present the design in plain words and wait for explicit approval. Never create anything on their instance without it. **Phase 4 — Implementation.** Compose the workflow JSON → `awesomate_n8n_deploy {action:'validate'}` and fix every error-severity issue → `{action:'create_draft'}` (the hub prefixes `[CLI] `, tags `awm:client-cli`, pre-assigns webhookIds, returns webhook URLs). Create any data tables with `workflowId` set so they land in the workflow's project. Iterate on the draft with `{action:'update_draft'}` — never recreate. **Phase 5 — Testing (mandatory — validated ≠ tested).** Full policy: [testing-policy.md](references/testing-policy.md). Short form: approval → activate → `awesomate_n8n_test` with obviously-fake payloads → inspect the execution node-by-node (`awesomate_n8n_executions` with `debug: true` when available) → happy path + empty + malformed + error-branch routing → report what ran and what the human must verify ("check your inbox"). **Phase 6 — Wrap-up.** Give the workflow URL (`{instanceUrl}/workflow/{id}`), the webhook URL, and what happens next. Delete unneeded drafts (`delete_draft`, deactivated only). ## 3a. Installing an Awesomate template (bundle) Awesomate curates ready-made automations and agents, some linked to the account's referrer (a Business Blueprint member sees Dale Beaumont's bundles). This is the path for "set me up with the X templates" from someone who has never opened n8n. It is NOT the build loop: nothing is designed, the bundle is installed as curated. 1. `awesomate_n8n_library { action: 'list' }`. Show the bundles by name with one line each, mark `installed`, and say which need credentials the account does not have yet (`credentials_missing`). Never show workflow JSON; the description is the product. 2. `detail` for the one they pick. Read out what each template does and the credential list with `have` ticks. Ask before installing. 3. `install_plan`. Three answers: - `ready`: go to step 4. - `paused`: for each entry in `help_cards` tell them, in this order, what the credential is for, `provider_url` + `provider_note` (where the key comes from), `create_url` (the exact page on THEIR n8n that opens the create form), then any `help_articles`. Offer the assisted route ONLY after that: a support session with the Awesomate team (`assisted.book_session_url`, one credit). You never create a credential for them and never ask for the secret in chat. When they say it is done, re-run `install_plan`. `optional_missing` may be skipped with their say-so (pass them in `proceed_without`); `ambiguous` needs their pick (`credential_choices`, type to credential id). - `blocked`: read `blockers` verbatim. A plan or consent block has a settings link; a connection block means their n8n key needs updating (see 0. First run). 4. `install`. Read `outcome`: `installed`, `already_present` (nothing changed; say so), `failed` (read results[].error). Workflows land INACTIVE. 5. `activate` (with their OK). A workflow answering `setup_incomplete` has an empty or missing credential named in `unresolved`; send them to fill it on their n8n (`/home/credentials`), then activate again. Agents are live on install. 6. `test`. Each template reports `passed`, `failed` (read the execution with `awesomate_n8n_executions` debug, fix configuration, re-run) or `untested` (no recipe: ask them to try it once). Real side effects run; say so before testing. **The stuck ladder** (a credential they cannot set up, or three failed test-and-fix rounds on ONE template): (1) `awesomate_support ask` and the help card's articles; (2) offer a session with the Awesomate team through `awesomate_book_session` (session_types first; it costs the credits shown; book only on their yes; 404 not_live means bookings are not open yet, go to 3); (3) SUGGEST a support ticket. Never send one unasked. If they say yes, ask for a sentence in their own words, then `awesomate_support create_ticket` with category 'Workflow error', subject `: