@ericrisco/rsc 0.1.37 → 0.1.39

package/skills/make/references/api-v2-cheatsheet.md

@@ -0,0 +1,114 @@
+# Make API v2 — cheat-sheet
+
+Current as of July 2026. Endpoints and query keys are **case-sensitive** and
+every call is **zoned**. Verify anything you depend on at
+[developers.make.com](https://developers.make.com/api-documentation) at author time.
+
+## Base URL & auth
+
+```
+https://{zone}.make.com/api/v2
+```
+
+- `{zone}` ∈ `eu1 | eu2 | us1 | us2` (plus `celonis` for that deployment). The
+  wrong zone returns an **authentication error** even with a valid token — this
+  is the single most common Make API mistake.
+- Header: `Authorization: Token {MAKE_API_TOKEN}` — literal `Token`, a space,
+  the token. OAuth2 exists for multi-user apps.
+- Content type for writes: `Content-Type: application/json`.
+
+## Token scopes (frozen at creation)
+
+Mint the token in **Profile → API/SDK**. You pick scopes **once**; they cannot
+be widened afterward — a too-narrow token means minting a new one. Grant only
+what you use, e.g. `scenarios:read scenarios:write connections:read
+connections:write hooks:read hooks:write datastores:read datastores:write
+teams:read organizations:read`.
+
+## Response envelope
+
+Most responses wrap the payload under a root key named for the resource, e.g.
+`{ "scenario": {...} }`, `{ "scenarios": [...] }`, `{ "response": { "blueprint": {...} } }`.
+Extract with `jq '.scenario'` etc. **Confirm the exact wrapper per endpoint at
+author time** — a few endpoints differ.
+
+## Endpoint map
+
+### Scenarios (the core)
+
+| Method | Path | Notes |
+|---|---|---|
+| GET | `/scenarios?teamId={id}` | list; paginate with `pg[limit]` / `pg[offset]` |
+| POST | `/scenarios` | body: `teamId` (int), `blueprint` (**string**), `scheduling` (**string**); optional `folderId`, `basedon` |
+| GET | `/scenarios/{id}` | metadata (not the blueprint) |
+| PATCH | `/scenarios/{id}` | update — send `blueprint`/`scheduling`/`name` as strings |
+| DELETE | `/scenarios/{id}` | **permanent, no trash** — export blueprint first |
+| GET | `/scenarios/{id}/blueprint` | the editable JSON (round-trip source) |
+| POST | `/scenarios/{id}/start` | activate scheduled execution |
+| POST | `/scenarios/{id}/stop` | deactivate |
+| POST | `/scenarios/{id}/run` | one manual run; `{"responsive":true}` waits for result |
+| POST | `/scenarios/{id}/clone` | body `{teamId, name}` — copy into a team |
+
+### Connections
+
+`GET/POST /connections`, `GET/DELETE /connections/{id}`,
+`POST /connections/{id}/test`. Modules reference a connection **by id** for app
+auth — the blueprint holds the id, never the secret.
+
+### Hooks (Make's inbound webhooks/mailhooks)
+
+`GET/POST /hooks`, `GET/DELETE /hooks/{id}`, `POST /hooks/{id}/ping`,
+`POST /hooks/{id}/learn-start` / `learn-stop` (structure learning). This is
+Make's *own* webhook receiver; building an inbound endpoint in **your** app is
+the `webhooks` skill.
+
+### Data stores
+
+`GET/POST /data-stores`, `GET/DELETE /data-stores/{id}`,
+`GET/POST/DELETE /data-stores/{id}/data`. The idiomatic place for dedup keys and
+cross-run state (see `automation-flows` for the dedup pattern).
+
+### Templates
+
+`GET /templates`, `GET /templates/{id}/blueprint`. A published template's
+blueprint is the cleanest round-trip starting point.
+
+### Teams & organizations
+
+`GET /teams?organizationId={id}`, `GET /organizations/{id}`. Read your real
+rate ceiling: `GET /organizations/{id}` → `license.apiLimit`.
+
+## Rate limits (req/min, per plan)
+
+| Plan | Limit |
+|---|---|
+| Core | 60 |
+| Pro | 120 |
+| Teams | 240 |
+| Enterprise | 1000 |
+
+Don't hard-code it — read `license.apiLimit` from your own org. On `429`, back
+off and retry (generic retry/backoff engineering: `api-connector-builder`).
+
+## Scheduling string
+
+`scheduling` is a JSON **string**. Common shapes (verify fields at author time):
+
+```json
+{"type":"on-demand"}
+{"type":"indefinitely","interval":900}   // interval in seconds
+```
+
+`on-demand` scenarios run only via `/run` or a webhook trigger; `indefinitely`
+runs on the interval once `/start`ed.
+
+## Errors you will actually hit
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| Auth error with a valid token | wrong `{zone}` | match the org's zone |
+| 400 on create | `blueprint`/`scheduling` sent as objects | stringify them |
+| 400 naming a module/field | malformed blueprint | fix that node, re-POST |
+| 403 on a valid endpoint | token missing that scope | re-mint with the scope |
+| 404 on a path that should exist | wrong case in the path | fix casing |
+| 429 | over plan rate limit | back off; read `apiLimit` |

package/skills/make/references/blueprint-round-trip.md

@@ -0,0 +1,128 @@
+# The blueprint round-trip
+
+You almost never author a Make blueprint by hand. You **export** one, **mutate**
+the JSON, and **send it back as a string**. This file is that recipe in depth.
+
+## Why round-trip
+
+A blueprint is a large, only-partially-documented JSON structure. Writing one
+from scratch means guessing internal module parameter keys and metadata that the
+create endpoint will reject. Exporting a working scenario (or a published
+template) gives you a guaranteed-valid skeleton to edit — the diff you make is
+small and reviewable.
+
+## Blueprint anatomy (top level)
+
+```jsonc
+{
+  "name": "My scenario",
+  "flow": [                     // ordered modules — index 1, 2, 3…
+    {
+      "id": 1,
+      "module": "gateway:CustomWebHook",   // module type
+      "version": 1,
+      "parameters": { "hook": 123456 },    // references a hook by id
+      "mapper": {},                        // inbound mapping for this module
+      "metadata": { "designer": { "x": 0, "y": 0 } }
+    },
+    {
+      "id": 2,
+      "module": "notion:createDatabaseItem",
+      "version": 2,
+      "parameters": { "__IMTCONN__": 78910 }, // connection id — NOT a secret
+      "mapper": { "title": "{{1.body.name}}" } // maps module 1's output
+    }
+  ],
+  "metadata": {
+    "instant": true,
+    "scenario": { "roundtrips": 1, "maxErrors": 3, "autoCommit": true },
+    "designer": { "orphans": [] }
+  }
+}
+```
+
+Key ideas:
+
+- **`flow`** is the ordered module list. Each module has an integer `id`; a
+  trigger sits at index 1.
+- **Mapping** is `{{sourceId.path}}` — `{{1.body.name}}` = module 1's
+  `body.name`. This is the same mapping `automation-flows` designs; here you are
+  only serializing it.
+- **Connections and hooks are referenced by id** (`__IMTCONN__`, `parameters.hook`).
+  Create the connection/hook first (or reuse one), put its id here. Never inline
+  an API key or token.
+- **Routers/branches** appear as nested `routes` arrays inside a router module.
+- `metadata.scenario` carries run settings (max errors, sequential processing,
+  auto-commit) — design decisions from `automation-flows`, encoded here.
+
+## Step 1 — export
+
+```bash
+curl -s -H "Authorization: Token $MAKE_API_TOKEN" \
+  "https://$MAKE_ZONE/api/v2/scenarios/$SRC_ID/blueprint" \
+  | jq '.response.blueprint' > bp.json     # verify the .response.blueprint wrapper at author time
+```
+
+Or from a template: `GET /templates/{id}/blueprint`.
+
+## Step 2 — mutate
+
+Edit `bp.json`: rename it, repoint `parameters.__IMTCONN__` /
+`parameters.hook` at *your* connection/hook ids, adjust `mapper` expressions,
+add/remove modules in `flow`. If you add a module, give it a fresh integer `id`
+and wire downstream mappers to it.
+
+Validate it is still JSON before sending:
+
+```bash
+jq empty bp.json && echo "valid json"
+```
+
+## Step 3 — send back as a STRING
+
+The create/update endpoints want `blueprint` (and `scheduling`) as JSON
+**strings**, not objects. Build the body with `jq` so the stringify is correct:
+
+```bash
+# CREATE
+curl -s -X POST -H "Authorization: Token $MAKE_API_TOKEN" \
+  -H "Content-Type: application/json" \
+  "https://$MAKE_ZONE/api/v2/scenarios" \
+  -d "$(jq -n \
+        --argjson team "$MAKE_TEAM_ID" \
+        --arg bp "$(jq -c . bp.json)" \
+        --arg sched '{"type":"on-demand"}' \
+        '{teamId:$team, blueprint:$bp, scheduling:$sched}')"
+
+# UPDATE (same scenario)
+curl -s -X PATCH -H "Authorization: Token $MAKE_API_TOKEN" \
+  -H "Content-Type: application/json" \
+  "https://$MAKE_ZONE/api/v2/scenarios/$ID" \
+  -d "$(jq -n --arg bp "$(jq -c . bp.json)" '{blueprint:$bp}')"
+```
+
+`jq -c . bp.json` compacts the blueprint to one line; passing it via `--arg`
+makes it a **string** field. `--argjson team` keeps `teamId` a number.
+
+## The stringify gotcha
+
+The most common failure is sending `blueprint` as a nested object:
+
+```jsonc
+// WRONG — object, 400
+{ "teamId": 123, "blueprint": { "flow": [ ... ] }, "scheduling": {"type":"on-demand"} }
+
+// RIGHT — string
+{ "teamId": 123, "blueprint": "{\"flow\":[...]}", "scheduling": "{\"type\":\"on-demand\"}" }
+```
+
+If you build the request in Python/JS, `json.dumps()` / `JSON.stringify()` the
+blueprint value itself and assign the resulting string.
+
+## Verify, then activate
+
+The create/PATCH call is the validator — a bad blueprint returns a 400 naming
+the offending module. On success, dry-run with `POST /scenarios/{id}/run`
+(`{"responsive":true}` to get the output inline), inspect the bundle, then
+`POST /scenarios/{id}/start`. Before any `DELETE`, re-export the blueprint to a
+file — deletion is permanent.

package/skills/make/references/make-mcp-and-auth.md

@@ -0,0 +1,101 @@
+# Make MCP server & auth setup
+
+The Make MCP server exposes your Make account to an MCP client (Claude, Cursor,
+ChatGPT, or any MCP-capable agent) so it can run — and, on paid plans, manage —
+scenarios as tools. It is **GA and free on every plan**; you pay only the normal
+scenario **credits** each run consumes. Verify specifics at
+[developers.make.com/mcp-server](https://developers.make.com/mcp-server) at
+author time — tool names and transports move.
+
+## Transports
+
+Two ways to authenticate the connection:
+
+### OAuth (remote, recommended for end users)
+
+Point the client at the hosted endpoint:
+
+```
+https://mcp.make.com            # stateless (default)
+https://mcp.make.com/stream     # streamable HTTP
+https://mcp.make.com/sse        # server-sent events
+```
+
+The client runs an OAuth consent flow; the **scopes you grant at consent decide
+which tools appear**. No token to manage by hand.
+
+### MCP token (per-zone URL)
+
+Generate an **MCP token** in Make (Profile → API/SDK) and embed it in a zoned URL:
+
+```
+https://{zone}.make.com/mcp/u/{MCP_TOKEN}/stateless
+https://{zone}.make.com/mcp/u/{MCP_TOKEN}/stream
+https://{zone}.make.com/mcp/u/{MCP_TOKEN}/sse
+```
+
+- `{zone}` is your org's zone (`eu1|eu2|us1|us2`, + `celonis`) — same **zone
+  trap** as the REST API: wrong zone = auth failure.
+- The MCP token is **separate** from the REST API token.
+
+### Timeout — pick the transport by run length
+
+| Transport | Timeout | Use for |
+|---|---|---|
+| `/stateless` | ~60 s | quick scenarios, simple clients |
+| `/stream` | ~5 min 20 s | long-running scenarios |
+| `/sse` | ~5 min 20 s | streaming clients |
+
+A scenario that takes longer than 60 s on `/stateless` will time out — use
+`/stream` or `/sse`.
+
+## Tool tiers
+
+Exact tool names change; confirm in the client's tool list. The **tiers** are
+stable:
+
+- **Run tools — all plans.** List the account's on-demand scenarios and execute
+  a chosen one with inputs, returning its output bundle. This is what lets an
+  agent *use* an automation you built.
+- **Management tools — paid plans only.** View and modify scenarios,
+  connections, hooks, data stores, teams, and organizations — effectively the
+  REST CRUD surfaced as MCP tools. On a free plan these do not appear.
+
+On the OAuth transport, missing scopes (not just plan tier) can also hide tools.
+
+## Client config sketches
+
+Token transport (generic `mcpServers` block; adapt to your client):
+
+```json
+{
+  "mcpServers": {
+    "make": {
+      "url": "https://eu2.make.com/mcp/u/${MAKE_MCP_TOKEN}/stream"
+    }
+  }
+}
+```
+
+For stdio-only clients, bridge a streamable-HTTP URL to stdio with a proxy such
+as `mcp-proxy`.
+
+## Legacy local server
+
+`integromat/make-mcp-server` is the **older local stdio** server. It runs as a
+local process and exposes your on-demand scenarios as tools over stdio. It
+predates the cloud server; prefer the cloud MCP unless you specifically need a
+local, offline-ish process (e.g. an air-gapped client that cannot reach
+`mcp.make.com`).
+
+## Credits, not a free lunch
+
+The MCP *server* is free, but every scenario an MCP call runs burns the same
+**credits** as any other run. An agent that loops over a run tool can quietly
+drain credits — cap it the way you would any autonomous consumer.
+
+## When NOT to use MCP
+
+If the operator is your own deterministic script/CI, the REST API v2 is simpler
+and fully controllable — MCP earns its keep only when an **agent** is the one
+driving Make.

package/skills/n8n/SKILL.md

@@ -0,0 +1,205 @@
+---
+name: n8n
+description: "Use when operating a live n8n instance programmatically — driving its public REST API (`{host}/api/v1`, `X-N8N-API-KEY`) or the n8n-mcp server to create, validate, test, activate/deactivate, list, update, or delete workflows and read executions, on self-host or `*.app.n8n.cloud`. Triggers: 'deploy this workflow to my n8n over the API', 'push my workflow JSON to n8n with curl', 'I set active:true in the create call but it stays inactive', 'connect n8n-mcp / n8n_create_workflow to Claude', 'validate and autofix my n8n workflow', 'run an n8n workflow by id from a script', 'delete a workflow via the API', 'automatiza n8n por API', 'desplega el workflow a n8n.cloud'. NOT designing the flow's trigger-step-error logic or hand-building the importable workflow JSON (that is automation-flows), NOT operating Make / Zapier / Power Automate (their own skills), NOT a typed API client with auth+pagination+retry (api-connector-builder), NOT the inbound webhook receiver in your own app (webhooks)."
+tags: [n8n, automation, workflows, mcp, rest-api, no-code, integrations]
+recommends: [automation-flows, automation-strategy, api-connector-builder, webhooks]
+profiles: [full]
+origin: risco
+---
+
+# n8n — operate a live instance over its REST API and MCP
+
+You already have a workflow *design* (the trigger→steps→error shape and the importable JSON).
+This skill is the **operate** half: push that JSON into a running n8n, validate it, test it, flip it
+live, watch its executions, and tear it down safely — all without touching the UI. n8n has the
+richest programmatic story of the no-code platforms: a first-party REST API **plus** a mature MCP
+server, both hitting the same instance.
+
+Designing the flow itself (what fires it, how errors are handled, dedup) is **automation-flows** —
+this skill *consumes* that skill's `references/n8n-workflow-json.md` payload; it does not re-teach
+design.
+
+## Connect first — REST API vs MCP
+
+Two ways to drive the same instance. Pick by who is at the wheel.
+
+| | **Public REST API** | **n8n-mcp** (czlonkowski, de-facto standard) |
+|---|---|---|
+| What it is | n8n's own HTTP API at `{host}/api/v1` | MCP server wrapping that API **+** offline node/expression knowledge |
+| Best for | scripts, CI/CD, deterministic deploys, no extra dependency | an agent (Claude) building/fixing workflows in the loop — it can look up node schemas, then validate/autofix before it writes |
+| Auth | API key in header `X-N8N-API-KEY` | management tools need `N8N_API_URL` + `N8N_API_KEY`; **node-knowledge tools need no auth** |
+| Surface | identical on self-host **and** `*.app.n8n.cloud` | same underlying API; hosted trial at `dashboard.n8n-mcp.com` |
+
+**Version reality (verify at author time — n8n moves fast):**
+- API base is `{host}/api/v1`. Self-host ships interactive Swagger at `/api/v1/docs`; **cloud does not**.
+- `POST /workflows/{id}/execute` (run-by-id) is **recent** (n8n PR #20234). Older instances lack it —
+  there, the only programmatic run is POSTing to a Webhook node's URL. It also takes **no custom input**.
+- The API surface is the SAME whether you self-host or run on `*.app.n8n.cloud`; only the host differs.
+
+### `.env`
+
+```bash
+# host root only — you append /api/v1 for REST; n8n-mcp reads it whole
+N8N_API_URL=https://your-instance.app.n8n.cloud   # or N8N_HOST for self-host, e.g. http://localhost:5678
+N8N_API_KEY=n8n_api_...                            # Settings → n8n API → Create an API key
+```
+
+Never inline the key in a command that gets logged, and never put a *node* credential (Slack token,
+etc.) in the workflow payload — reference it by the n8n **credential store** id/name (see
+automation-flows' JSON schema). Full key-creation + self-host vs cloud + MCP install:
+`references/auth-and-selfhost.md`.
+
+## The payload you POST
+
+The create/update body is exactly the automation-flows workflow JSON. Required top-level keys on
+**create**: `name`, `nodes`, `connections`, `settings`. Build it per
+`../automation-flows/references/n8n-workflow-json.md` — non-empty `nodes` with one trigger, a wired
+`connections` map, `settings.errorWorkflow`, credentials referenced by store (never inlined).
+
+**Node/expression essentials** (pointer, not a tutorial): node `type` is namespaced
+(`n8n-nodes-base.webhook`), `typeVersion` must match a node version installed on the target instance
+or activation/execution fails; field values use expressions like `={{ $json.email }}` or
+`={{ $node["Webhook"].json.body.id }}`. If you are hand-authoring nodes, let n8n-mcp's node-knowledge
+tools (`search_nodes`, `get_node_essentials`, `validate_node_operation`) fill in the exact property
+shapes rather than guessing — that is the single biggest reason to drive via MCP.
+
+## Dynamic lifecycle
+
+create → **validate** → test → **activate** → manage → delete. A concrete sketch per step, curl and
+n8n-mcp side by side.
+
+### 1. Validate (do this BEFORE create)
+
+REST has no validation endpoint — n8n only tells you at create/activate time. MCP does, so validate
+first when it is available:
+
+```
+n8n_validate_workflow   { "workflow": { …the full JSON… } }
+n8n_autofix_workflow    { "workflow": { … } }   # repairs common structural errors, returns fixed JSON
+```
+
+### 2. Create
+
+```bash
+curl -sS -X POST "$N8N_API_URL/api/v1/workflows" \
+  -H "X-N8N-API-KEY: $N8N_API_KEY" -H "Content-Type: application/json" \
+  -d @workflow.json          # body = { name, nodes, connections, settings }
+# → returns the created workflow WITH its "id" — capture it for every step below
+```
+```
+n8n_create_workflow     { "name": "...", "nodes": [ … ], "connections": { … }, "settings": { … } }
+```
+
+### 3. Test / dry-run
+
+- **No input needed** → run by id (recent instances only): `POST /workflows/{id}/execute`.
+- **Needs input** → the execute endpoint accepts none. Make the trigger a **Webhook node** and POST to
+  its URL (test URL `/webhook-test/<path>` while "Listen for test event" is armed; production
+  `/webhook/<path>` once active).
+
+```bash
+curl -sS -X POST "$N8N_API_URL/api/v1/workflows/$ID/execute" -H "X-N8N-API-KEY: $N8N_API_KEY"
+curl -sS -X POST "$N8N_API_URL/webhook-test/my-path" -H "Content-Type: application/json" -d '{"foo":"bar"}'
+```
+```
+n8n_test_workflow       { "id": "$ID" }
+```
+
+### 4. Activate — the step people miss
+
+`active` in the create/update body is **read-only and silently ignored**. Setting `"active": true`
+does nothing. You MUST call the separate endpoint:
+
+```bash
+curl -sS -X POST "$N8N_API_URL/api/v1/workflows/$ID/activate"   -H "X-N8N-API-KEY: $N8N_API_KEY"
+curl -sS -X POST "$N8N_API_URL/api/v1/workflows/$ID/deactivate" -H "X-N8N-API-KEY: $N8N_API_KEY"
+```
+n8n-mcp deliberately does not expose activate/deactivate as tools (activation has live side effects).
+Check the current tool list; if absent, call the REST `/activate` endpoint as above.
+
+### 5. Manage
+
+```bash
+curl -sS "$N8N_API_URL/api/v1/workflows?limit=50"      -H "X-N8N-API-KEY: $N8N_API_KEY"  # list (paginate via nextCursor)
+curl -sS "$N8N_API_URL/api/v1/workflows/$ID"           -H "X-N8N-API-KEY: $N8N_API_KEY"  # get
+curl -sS -X PUT "$N8N_API_URL/api/v1/workflows/$ID"    -H "X-N8N-API-KEY: $N8N_API_KEY" \
+  -H "Content-Type: application/json" -d @workflow.json                                  # FULL replace
+curl -sS "$N8N_API_URL/api/v1/executions?workflowId=$ID&limit=20" -H "X-N8N-API-KEY: $N8N_API_KEY"
+```
+```
+n8n_list_workflows {}        n8n_get_workflow { "id": "$ID" }        n8n_executions { "workflowId": "$ID" }
+n8n_update_full_workflow    { "id": "$ID", "nodes": [ … ], "connections": { … } }   # replace everything
+n8n_update_partial_workflow { "id": "$ID", "operations": [ … ] }                    # atomic diff — preferred
+n8n_health_check {}          # confirm API reachable + which features the instance supports
+```
+`PUT` is a **full replace** — GET, mutate the whole object, PUT it back, or you drop the nodes you
+omitted. n8n-mcp's `n8n_update_partial_workflow` applies a targeted, atomic batch instead (safer).
+
+### 6. Delete — irreversible
+
+`DELETE` is a **hard delete: no trash, no undo.** Export the current JSON first, every time.
+
+```bash
+curl -sS "$N8N_API_URL/api/v1/workflows/$ID" -H "X-N8N-API-KEY: $N8N_API_KEY" > backup-$ID.json  # export FIRST
+curl -sS -X DELETE "$N8N_API_URL/api/v1/workflows/$ID" -H "X-N8N-API-KEY: $N8N_API_KEY"
+```
+```
+n8n_get_workflow { "id": "$ID" }   →  save output  →  n8n_delete_workflow { "id": "$ID" }
+```
+
+**Irreversibility rule:** never DELETE (or full-replace) a live workflow without exporting it first.
+
+## Governance
+
+If you expose n8n-mcp to an agent, lock down destructive tools with the `DISABLED_TOOLS` env var
+(comma-separated), e.g. `DISABLED_TOOLS=n8n_delete_workflow,n8n_update_full_workflow`. Scope the API
+key itself too — n8n supports scoped keys (e.g. grant `workflow:read` without `workflow:execute`).
+Details in `references/n8n-mcp-tools.md`.
+
+## Honesty / gotchas
+
+- **`active` and `tags` are read-only on create/update** — ignored in the body; activate/tag via the
+  dedicated endpoints. This is the #1 "why is my workflow inactive" bug.
+- **`/workflows/{id}/execute` takes no custom input** — for runtime params, trigger a Webhook workflow
+  by POSTing to its URL. Also, it is a newer endpoint; older instances 404 it.
+- **`DELETE` and `PUT` are destructive** — hard delete (no trash) and full replace. Export first; prefer
+  `n8n_update_partial_workflow` for edits.
+- **`typeVersion` must exist on the target** — a node version the instance doesn't have fails only at
+  activate/execute time, not at create. Validate (MCP) or test before activating.
+- **Credential secrets are not fully manageable over the public API** — you can reference existing
+  credentials by id/name and create some, but you cannot read secrets back; provision credentials in
+  the UI / n8n-mcp `n8n_manage_credentials` and reference them.
+- **Cloud has no Swagger** — `/api/v1/docs` is self-host only; on cloud, work from the docs.
+- **Activation can succeed via API where the UI would block it** — the public API historically skips a
+  few UI-side activation validations, so a workflow can be "active" yet non-functional. Test it live.
+
+## Related skills
+
+- **automation-flows** — *design* the flow and produce the importable JSON this skill deploys. Design
+  vs operate boundary: they decide the trigger/steps/error path; you push it live. Start there if the
+  flow's logic isn't settled yet.
+- **automation-strategy** — whether n8n is even the right platform (cost model, self-host vs cloud) vs
+  Make/Zapier/Power Automate.
+- **make / zapier / power-automate** — the other platforms' operate stories (Zapier and Power Automate
+  can't create flows via API — n8n's edge).
+- **api-connector-builder** — a generic typed HTTP client with auth/pagination/backoff, when the answer
+  is real code, not a workflow.
+- **webhooks** — building the inbound receiver *in your own app*; here webhooks are just n8n triggers.
+
+## Checklist
+
+- [ ] `.env` has `N8N_API_URL`/`N8N_HOST` + `N8N_API_KEY` (key from Settings → n8n API); key not logged.
+- [ ] Payload has `name`, `nodes` (one trigger), `connections`, `settings` per automation-flows' schema;
+      node credentials referenced by store, never inlined.
+- [ ] Validated (`n8n_validate_workflow` / `n8n_autofix_workflow`) before create when MCP is available.
+- [ ] Created via `POST /workflows` or `n8n_create_workflow`; captured the returned `id`.
+- [ ] Tested — `execute`-by-id (no input) or POST to the webhook URL (with input) — and the run succeeded.
+- [ ] Activated via `POST /workflows/{id}/activate` (NOT `active:true` in the body).
+- [ ] Before any DELETE or full-replace: exported the current JSON (hard delete, no trash).
+- [ ] If MCP is exposed to an agent: `DISABLED_TOOLS` set and/or the API key scoped.
+
+## References
+
+- `references/rest-api-cheatsheet.md` — every workflow/execution endpoint with curl, pagination, scopes.
+- `references/n8n-mcp-tools.md` — the management + node-knowledge tool list, the auth split, `DISABLED_TOOLS`.
+- `references/auth-and-selfhost.md` — API-key creation, self-host vs cloud, Swagger, installing/pointing n8n-mcp.

package/skills/n8n/evals/README.md

@@ -0,0 +1,14 @@
+# Evals — n8n
+
+`cases.yaml` has three groups. `should_trigger` covers the operate tasks this skill owns: deploying a
+workflow JSON over the REST API, the read-only-`active` gotcha, wiring n8n-mcp management tools,
+running a workflow by id, hard-delete safety, and validate/autofix — with a Spanish phrasing. Each
+`should_not_trigger` names a real sibling: flow design + importable JSON → automation-flows,
+platform/cost choice → automation-strategy, another platform → make, a typed code client →
+api-connector-builder, an in-app inbound receiver → webhooks. `capability` is one end-to-end deploy
+scenario whose `must_include` rubric pins the current API/MCP calls, the honesty limits (read-only
+`active`, no-input `execute`), and the irreversibility rule (export before hard delete).
+
+No automated runner. Score by judgement: feed each `should_trigger`/`should_not_trigger` prompt to the
+routing layer and confirm it activates or routes to the listed sibling; for `capability`, have the
+skill produce the deploy plan/commands and check every `must_include` bullet by hand.

package/skills/n8n/evals/cases.yaml

@@ -0,0 +1,45 @@
+skill: n8n
+
+should_trigger:
+  - prompt: "Push my workflow JSON to n8n over the API with curl and turn it on."
+    why: Canonical operate task — POST /workflows then the separate /activate endpoint. Core deliverable.
+  - prompt: "I set active:true in my POST to /api/v1/workflows but the workflow stays inactive. Why?"
+    why: The read-only-active gotcha — active/tags are ignored on create; must call /workflows/{id}/activate.
+  - prompt: "Wire n8n-mcp into Claude Code so it can call n8n_create_workflow and n8n_update_partial_workflow against my instance."
+    why: MCP operate path — configuring the management tier with N8N_API_URL + N8N_API_KEY.
+  - prompt: "How do I run an n8n workflow by its id from a shell script, and can I pass it input data?"
+    why: POST /workflows/{id}/execute (recent) plus the no-custom-input limit → webhook trigger for params.
+  - prompt: "Delete this workflow from my n8n via the API — is there an undo?"
+    why: Hard-delete irreversibility; must export (GET) first, no trash.
+  - prompt: "desplega este workflow a mi n8n.cloud por la API y valídalo antes de activarlo"
+    why: Spanish; programmatic deploy + validate + activate against cloud — same REST surface.
+  - prompt: "Validate and autofix my n8n workflow before I create it, then list its executions."
+    why: n8n_validate_workflow / n8n_autofix_workflow then n8n_executions — MCP management lifecycle.
+
+should_not_trigger:
+  - prompt: "Design an n8n flow: Stripe payment → Notion row → Slack, with an error path and dedup. Give me the importable JSON."
+    route_to: automation-flows
+    why: Designing the trigger/steps/error shape and producing the JSON is automation-flows; this skill only deploys/operates that JSON.
+  - prompt: "Should I use n8n, Make, or Zapier for 50k runs a month, and self-host or cloud?"
+    route_to: automation-strategy
+    why: Platform/cost-model selection, not operating a specific live n8n instance.
+  - prompt: "Create this scenario in my Make account programmatically."
+    route_to: make
+    why: Operating a different platform (Make) — its own skill; Make also has no create-via-API story like n8n's.
+  - prompt: "Write a TypeScript client for the Acme REST API with API-key auth, cursor pagination, and exponential backoff."
+    route_to: api-connector-builder
+    why: A typed HTTP client in code, not driving n8n's API or MCP.
+  - prompt: "Build the endpoint in my Express app that receives and verifies inbound webhook signatures."
+    route_to: webhooks
+    why: An inbound receiver in the user's own app; here webhooks are only n8n triggers, not something this skill builds.
+
+capability:
+  - scenario: "User has an importable n8n workflow JSON (webhook trigger → HTTP node → Slack) and wants it deployed to their n8n.cloud instance: created, tested, activated, and later safely removed — via the REST API and/or n8n-mcp."
+    must_include:
+      - "Reads N8N_API_URL/N8N_HOST + N8N_API_KEY from env; key from Settings → n8n API; sends it as the X-N8N-API-KEY header (not a bearer token)."
+      - "Builds the create body per automation-flows' n8n-workflow-json schema (name, nodes, connections, settings); node credentials referenced by the credential store, never inlined."
+      - "Creates with POST /workflows (or n8n_create_workflow) and captures the returned id for subsequent calls."
+      - "States that active (and tags) are read-only on create/update and activates with a separate POST /workflows/{id}/activate."
+      - "Notes POST /workflows/{id}/execute takes no custom input (and is a recent endpoint), so runtime params require POSTing to a Webhook node URL."
+      - "Exports the workflow (GET /workflows/{id}) before any DELETE, and states DELETE is a hard delete with no trash."
+      - "When driving via MCP, validates/autofixes (n8n_validate_workflow / n8n_autofix_workflow) before create; notes management tools need the two env vars while node-knowledge tools do not."