@awesomate/hosting-mcp/skill/awesomate-n8n/SKILL.md

Awesomate MCP server — lets Claude manage your Awesomate WordPress hosting, plan, limits, n8n automations, and build Node/static apps + databases

---
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: <slug>` — 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 `<bundle>: <template> fails after install`, and a message that
carries the bundle and template slugs, the execution id and failing node from the last
test, what you tried, and their sentence verbatim. Never paste workflow JSON into a ticket.
7. `rollback` removes what their install created (never a reused workflow), with their OK.
8. A 403 whose `missingScopes` contains `n8n:deploy` means Essentials. Show the catalog,
   say installing needs Support Plus, link `https://hub.awesomate.ai/billing`, and stop.

`installs` lists what is on the instance grouped by bundle; rows marked `installed_by:
agency` were pushed by Awesomate and are read-only here.

`redeem` takes a token Awesomate handed over and installs what it unlocks, no visibility
check; use it when the member has a token, otherwise use the catalog.

## 4. Changing a LIVE workflow

Never edit a live workflow directly, and never "activate the copy" — the
copy has different webhook URLs and every external caller breaks. Draft →
test → present a human-readable diff → explicit approval → `promote` (swaps
the tested draft INTO the live id, webhookIds preserved) → verify the
ORIGINAL URL → `rollback` with the returned operationId on any failure.
Full procedure: [upgrade-loop.md](references/upgrade-loop.md).

## 5. Diagnosing a failure

Executions list → detail → walk the item data BACKWARDS (the cause is
usually upstream) → `debug: true` for node-level output → check against
[troubleshooting.md](references/troubleshooting.md) → explain in the user's
terms with the exact fix. Trust `errorSummary` only on `confident: true`
(§0a). While you're there, check whether the workflow has an error plan at
all — [error-handling.md](references/error-handling.md). Self-built workflows: fix via update_draft or the
upgrade loop. Agency-managed (`agency_managed` error): read and explain
freely, and switch it off or on if the user asks (say what it does first);
any other change goes through Awesomate support.

## 6. "What could I automate?"

`awesomate_n8n_inspect {what:'possibilities'}` returns facts; YOU make the
suggestions — grounded, ≤8, honestly labelled with what each needs. Rules:
[possibilities.md](references/possibilities.md). Offer it once, in one
sentence, after the first inventory pass when the user's ask is vague. One
standing recipe worth offering: the weekly business pulse —
[recurring-reports.md](references/recurring-reports.md).

## 7. Hard rules

- **Never ask for their n8n API key.** Unreachable = consent/scope/plan —
  route to settings or reconnect.
- **Explicit approval gates:** before create_draft (design confirmation),
  activate, promote, rollback, delete (draft or rows), and any test with
  non-email side effects (CRM writes, payments: STOP and ask).
- **Agency-deployed workflows and their data tables are read-only** — the
  hub enforces it; don't fight the 403.
- **Never activate a copy of a live workflow.** Promote exists for this.
- **Respect quotas** — 429 quota_exceeded is the plan's daily cap; tell the
  user, don't retry-loop.
- **`saveExecutionProgress` stays false.** The hub enforces it; don't work
  around it.
- **Real side effects run in tests** — user's own email, `[TEST]` prefixes,
  tell them first.
- **WordPress forms:** POST server-side from WP to the webhook (forwarder
  snippet — [wp-form-handler.md](references/wp-form-handler.md)), never
  from the browser.