--- 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, the 1Brain node, or {slug}.awesomate.io. Reads and n8n Agents on every plan; installing Awesomate templates needs Support Plus+; workflows are built through the client's own n8n MCP server, which Awesomate never sees or limits. 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, read every execution node by node, build n8n Agents, and install Awesomate's curated templates. Workflows themselves are written through the instance's OWN MCP server (n8n 2.x ships one), which the user connects to their Claude Code. Awesomate never sees that traffic, sets no limits on it and keeps no count. Their n8n API key never reaches this machine; every hub read is consent-gated 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`, and 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` → "Let Claude Code work with your automations". Privacy moved there; the plain `/settings` page no longer has it (old `?tab=privacy` links just redirect). Wait, then re-check. - `403 missingScopes`: the token predates n8n support. Reconnect from hub.awesomate.ai/claude (Connect Claude Code card). - `capabilities.templateInstall: false`: Awesomate template installs (§3a) are Support Plus+. Be honest about it once, then help fully with everything else: reads, n8n Agents, and building through their own n8n MCP server all work on every plan. - `capabilities.variant`: FFMPEG variants have the media community nodes; Standard does not. Never assume a node exists. Verify. - `instance`: community packages + counts (your recon baseline). - `health`: whether their n8n answered its API just now. If `reachable` is false, tell the user n8n isn't answering, say `last_error` in your own words, and stop before building anything: every build step would fail the same way. `key_status: "invalid"` means their n8n rejected the stored key: they create a new API key in n8n and save it in n8n settings on the hub, then you re-check. `reachable: null` only means it wasn't checked (consent off). - `hubNodeCredential`: the **Awesomate node** (`CUSTOM.awesomate`, and the Awesomate Trigger) signs in with the **"Awesomate Hub"** credential. Never ask anyone to paste a Hub Key or an API key for the node: the hub never shows that key, it puts the credential in their n8n for them. By `state`: - `ready`: pick the credential by its `name` on the node. - `missing`: call `awesomate_n8n_hub_credential`; it puts the credential in their n8n (making the account's Hub Key first if it has none) and never hands you the key. Re-check, then build with the node. If `ownerOnly` is true (a team member's key), the tool refuses it (`key_not_yet` or `owner_only`): ask the owner to press **"Add it to my n8n"** on the hub instead (`addUrl`: Automations, Settings, "Awesomate node"). - `no_node`: their n8n does not have the node. Do not build with it. Where the inventory (`awesomate_n8n_inspect` credentials) has the **"Awesomate Hub Key"** Header Auth credential, an HTTP Request node with Generic Credential Type, Header Auth, that credential, reaches the same hub routes; otherwise build the step another way. - `not_connected`: the hub has no n8n key for this account; they connect n8n on the hub first (n8n, Settings). - `unknown`: the hub could not check just now. Say so and re-check later; do not send anyone to press Add. - `null`: consent is off (see `consented`). 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 role (the API says `job`) on the business map, add its `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, capabilities, fingerprint | `awesomate_n8n_context` | | All workflows (node-level summaries) / one workflow (`detail: full\|structure`) | `awesomate_n8n_workflows` | | Node inventory, datatables (+rows), possibilities, credentials, $vars, a credential type's fields (`credential_schema` {credentialType}) | `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` | | **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` | | Awesomate's template library (Support Plus+): 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, invitations: sessions our team asked them to book, taken up with `invitation_id` on book) | `awesomate_book_session` | | Wire any production webhook URL on their n8n 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` | **Writing workflows is not an Awesomate tool.** Creating, editing, publishing and running a workflow happens through the n8n instance's own MCP server, connected to this Claude Code by the user (§3, Phase 4). Reads, agents, template installs and app wiring are the hub's; the workflow JSON goes straight to their n8n. No `awesomate_n8n_*` tools in this session (fresh bootstrap, or the server didn't load)? Suggest a Claude Code restart once. If the n8n MCP server IS connected, you can still design and write workflows with it meanwhile; you just cannot ground the design in the hub's inventory or read executions until the Awesomate tools are back. ## 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) | | "What could I automate?" | [possibilities.md](references/possibilities.md) | | WordPress form → n8n | [wp-form-handler.md](references/wp-form-handler.md) | | **1Brain** in a workflow or agent: procedures, SOPs, policies, the `CUSTOM.oneBrain` node (check it is on the instance first). Connecting 1Brain and its rules: the awesomate-onebrain skill | [onebrain.md](references/onebrain.md) | | The **Awesomate node** (`CUSTOM.awesomate`) in a workflow: add, find, change or tag a person in Contacts, find or add a company and put a person at it, start an email series (Record Event), record a request to stop emailing, read and write the account's own records (or read one by another system's id), give a task, hold for a decision, add the figures KPIs read. From n8n always `/api/hub-key/v1/...`, never `/api/my-crm/v1/...` | [awesomate-node.md](references/awesomate-node.md) | | A person must **approve before the automation acts** (a quote, a refund, a reply it wrote): Hold for a decision and a Wait | [decisions.md](references/decisions.md) | | **Tell someone on the team** (a hot lead, a fault, a staff alert, a customer waiting): a task for them, never Gmail or a text; `urgent` for what can't wait | [staff-alerts.md](references/staff-alerts.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, with one exception: a hook secret or an app server key made with `n8n_credential: true` is created in their n8n by the hub, and the tool returns its credential id. Every other credential, API-key ones included, the user creates in n8n at `{instanceUrl}/home/credentials`; you then re-check the inventory to verify it exists. n8n's own MCP may still say credentials must be configured manually. Check the node points at the credential id the hub returned; if it does, tell the user that warning is n8n's generic one and can be ignored. **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, through their n8n's own MCP server.** Writing happens on their n8n, not through Awesomate. - **Is it connected?** Look for the n8n server's tools in this session (`search_workflows`, `get_workflow_details`, `create_workflow`, `update_workflow`, `publish_workflow`, `execute_workflow`; the server is usually named `n8n`). If they are there, build. - **If it is not connected, say so and hand the user the two steps.** Do not pretend any Awesomate tool can create or change a workflow; none can. 1. Switch on MCP access and get the key, in their own n8n: **Settings → MCP access** on `{instanceUrl}`. The hub's **Set it up for me** button under **n8n Agents access** on `hub.awesomate.ai/n8n/settings` also switches MCP access on. The key is theirs; never ask them to paste it into the chat. 2. Add it to their Claude Code, in a terminal, with their own key in place of the placeholder: `claude mcp add --transport http n8n {instanceUrl}/mcp-server/http --header "Authorization: Bearer "` then restart Claude Code and carry on. Until then, keep designing: everything up to Phase 3 needs only the Awesomate reads. - Compose the workflow JSON from the approved design. Check every node against `awesomate_n8n_node_docs validate_node` before you write it, and fix every error-severity issue (known false positives are listed in platform-notes). Keep `settings.saveExecutionProgress` false yourself; the hub no longer enforces it. - Create it with the n8n server's create tool. It lands unpublished. Give the workflow a name the user will recognise in their n8n list; nothing prefixes or tags it for you now. A webhook's production URL is `{instanceUrl}/webhook/`: take the path from the workflow you created and `instanceUrl` from `awesomate_n8n_context`; never guess the hostname. - Data tables: the user creates them in n8n (Data tables in the left menu), or you do it through the n8n server if it offers a data-table tool; read them back with `awesomate_n8n_inspect {what:'datatables'}` and reference them by name. Full rules: [datatables.md](references/datatables.md). - Iterate with the n8n server's update tool on the same workflow id. Never recreate under a new id: the webhook URLs change. **Phase 5: Testing (mandatory; validated ≠ tested).** Full policy: [testing-policy.md](references/testing-policy.md). Short form: approval → publish through the n8n server → run it (the n8n server's execute tool, a POST to the production webhook with obviously fake data, or ask the user to trigger it) → inspect the execution node-by-node (`awesomate_n8n_executions` with `debug: true`) → 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. Remove any temporary test triggers and, with their OK, any throwaway workflows you created along the way (unpublish first, then delete, through the n8n server). ## 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 `: