chore: sync skills pack review fixes (n8n-skills 1.34.0) (#1039)

Ports the n8n-skills 1.34.0 release (czlonkowski/n8n-skills#49) into
data/skills via `npm run sync:skills`. These are the fixes from a review
of the 1.32.0/1.33.0 official-MCP documentation against this repo's live
tool surface:

- using-n8n-mcp-skills, the always-on router, gains n8n_manage_agents,
  n8n_explore_node_resources and n8n_list_catalog, plus the routed
  operations on n8n_test_workflow / n8n_workflow_versions /
  n8n_manage_datatable. It had none of them.
- n8n_explore_node_resources had been documented with three of its six
  required parameters — nodeType, version and credentialType were
  missing, so following the skill produced INVALID_ARGS.
- n8n_health_check's officialMcp block is documented as the preflight
  for every N8N_MCP_ACCESS_TOKEN-gated capability.
- The agent config hash round-trips as configHash out /
  args.baseConfigHash in; args are forwarded verbatim, so the near-miss
  was a real failure path.
- Native workflow versions gain the WORKFLOW_NOT_EXPOSED / exposeToMcp
  consent flow already documented for n8n_test_workflow.
- deleteColumn is flagged as destroying the column's values, which
  matters because a column type cannot be changed after creation.
- Persisted-agent custom tools are TypeScript with @n8n/agents and zod
  only — distinct from the Code node and from the toolCode Custom Code
  Tool that n8n-code-tool covers.
- n8n-subworkflows and SUBWORKFLOW_AS_TOOL now name prepare/pinned for
  the pinned-input testing they already promised.

data/skills is byte-identical to n8n-skills v1.34.0 again.


Claude-Session: https://claude.ai/code/session_017Ui5Ca4eGJh4Ka6F7AhUye

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

Author: czlonkowski

data/skills/n8n-agents/SKILL.md

@@ -197,16 +197,20 @@ A **persisted n8n Agent** is a different artifact from the AI Agent node covered
 
 **Build sequence:**
 1. `action: "reference"` — read the config schema and the exact mutate operations before anything else.
-2. `action: "discover_assets"` — list available models, integrations, workflows, subagents, MCP servers for the target project.
+2. `action: "discover_assets"` — list what the agent can actually be wired to. Takes `projectId` (from `n8n_list_catalog({kind: "projects"})`) and `kind`: `models` (with a `provider`), `integrations`, `workflows`, `subagents` or `mcpServers`. One call per kind.
 3. `action: "create"` — `projectId`, `name`, `config`.
-4. `action: "mutate"` — one resource per call (`config.patch`, `skill.upsert`/`delete`, `task.upsert`/`delete`, `customTool.upsert`/`delete`), always with the **latest** `configHash` from the previous response. A stale hash comes back as `STALE_CONFIG` — re-`get` and retry with the fresh one.
+4. `action: "mutate"` — one resource per call (`config.patch`, `skill.upsert`/`delete`, `task.upsert`/`delete`, `customTool.upsert`/`delete`), always carrying the **latest** hash forward. Mind the two names: n8n returns it as `configHash` and expects it back as `args.baseConfigHash`. `args` are forwarded to n8n verbatim, so a near-miss on any field name comes back as `INVALID_ARGS`, not a helpful correction — which is why step 1 reads the schema first. A stale hash comes back as `STALE_CONFIG` — re-`get` and retry with the fresh one.
 5. `action: "validate"` — before offering to `call` or `publish`.
 6. `action: "publish"` — **only on the user's explicit request**, never proactively.
 
 `action: "call"` runs the agent with real credentials and real tools — a live execution, not a dry run. A result can carry `approvals[]` for tool calls that need a human decision; **never approve on the user's behalf** — surface them and resume only after the user decides.
 
+**Custom tools are a third code runtime — don't reuse either of the others.** A `customTool.upsert` body is **TypeScript**, and the only imports it may use are `@n8n/agents` and `zod`. This is not the Code node (JavaScript/Python, returns `[{json: …}]`) and not the AI-agent Custom Code Tool covered by **n8n-code-tool** (`@n8n/n8n-nodes-langchain.toolCode`, returns a string, no `$fromAI()`). Reaching for the wrong contract is the easy mistake here, because all three are "write code the agent calls". Read the shape from `action: "reference"` before writing one; a compile failure or an unknown `agentId` surfaces as `AGENT_TOOL_ERROR`.
+
 **Credential caveat:** on n8n 2.36.x the agents runtime rejects `azureOpenAiApi` and `aws` credentials (reported as `missing: ["credential"]`); the response's `hint` names the accepted types instead.
 
+**Testing without leaving debris:** name throwaway agents `[TEST] …` and `delete` them when you're done — a persisted Agent outlives the conversation that made it, unlike a workflow you can leave inactive.
+
 → **n8n-mcp-tools-expert** `## Agents` for the tool's full action list and error codes.
 
 ---

data/skills/n8n-agents/SUBWORKFLOW_AS_TOOL.md

@@ -174,9 +174,12 @@ Name them with a standard prefix (`Subworkflow:` or domain-specific). The Tool W
 
 A sub-workflow tool can be tested without the agent:
 
-1. Pin representative input on the Execute Workflow Trigger.
-2. `n8n_test_workflow` runs it with that pinned data.
-3. Verify the output shape matches what the agent will receive.
+1. `n8n_test_workflow({workflowId, method: "prepare"})` — which nodes need pinned data.
+2. Build one sample item per node, keyed by node **name**, each wrapped as `{json: {...}}`.
+3. `n8n_test_workflow({workflowId, method: "pinned", pinData})` runs it with that data and waits.
+4. Verify the output shape matches what the agent will receive.
+
+The routed methods need `N8N_MCP_ACCESS_TOKEN` and the workflow's "Available in MCP" setting; the default `method: "auto"` cannot run a sub-workflow, which has no HTTP trigger.
 
 ---
 

data/skills/n8n-mcp-tools-expert/OPERATIONS_GUIDE.md

@@ -148,13 +148,18 @@ n8n_manage_datatable({
   name: "state"
 })
 
+// deleteColumn drops the column's VALUES with it, and there is no undo.
+// A column's type cannot be changed after creation, so "make this column a number"
+// means drop-and-re-add — read the values out with getRows first if they matter.
 n8n_manage_datatable({
   action: "deleteColumn",
   tableId: "dt-123",
   columnId: "col-456"
 })
 ```
 
+Column types are `string`, `number`, `boolean` and `date`. The column actions also accept `timeoutMs` (5000-600000, default 30000).
+
 **Filter conditions**: `eq`, `neq`, `like`, `ilike`, `gt`, `gte`, `lt`, `lte`
 
 **Best practices**:

data/skills/n8n-mcp-tools-expert/SKILL.md

@@ -259,7 +259,7 @@ See [OPERATIONS_GUIDE.md](OPERATIONS_GUIDE.md) for full search/get/deploy exampl
 
 | `method` | Backend | What it does |
 |---|---|---|
-| `auto` (default) | Public API | Detects a webhook/form/chat trigger and fires it over HTTP. No such trigger → it reports that the workflow cannot be triggered and names the methods below. **`auto` never runs anything through n8n's MCP server.** |
+| `auto` (default) | Public API | Detects a webhook/form/chat trigger and fires it over HTTP — the workflow must be **active**. No such trigger → it reports that the workflow cannot be triggered and names the methods below. **`auto` never runs anything through n8n's MCP server.** |
 | `trigger` | Public API | Same HTTP path, requested explicitly. |
 | `prepare` | n8n's MCP server | Read-only: lists the nodes that need pinned data. |
 | `pinned` | n8n's MCP server | Runs the workflow with `pinData` standing in for trigger, credentialed and HTTP Request nodes, and waits. Every other node still runs. A run that finishes in `error`/`crashed`/`canceled` comes back as `EXECUTION_FAILED` with the `executionId`. |
@@ -272,9 +272,12 @@ See [OPERATIONS_GUIDE.md](OPERATIONS_GUIDE.md) for full search/get/deploy exampl
 - `executionMode` applies to `direct`: `manual` (default) or `production`. It changes the execution context, not whether the run has side effects — a production run goes through the production execution path and is recorded as one. Only pass it when the user asked for one.
 - `timeoutMs` is the client deadline for the official call (5000-600000; default 30000 for `prepare`, 300000 for `pinned`/`direct`).
 - `direct` returns as soon as the run starts, so it reports success with an `executionId` regardless of how the run ends — poll `n8n_executions({action: "get", id: executionId})` for the outcome. A dispatch n8n refuses outright comes back as `OFFICIAL_MCP_ERROR`, not `EXECUTION_FAILED`.
+- A workflow whose "Available in MCP" setting is off answers `WORKFLOW_NOT_EXPOSED`; `exposeToMcp: true` turns the setting on and retries once. That is a visible, persistent change — ask the user first, and note that enabling it is itself a workflow update, so it can overwrite a concurrent UI edit.
 
 Successful and routed responses state `method` and `backend` (`public-api` or `official-mcp`); an envelope rejected on argument validation may carry neither.
 
+See [WORKFLOW_GUIDE.md](WORKFLOW_GUIDE.md#n8n_test_workflow-running-workflows) for runnable examples of each method.
+
 ---
 
 ## Version History
@@ -284,15 +287,21 @@ Successful and routed responses state `method` and `backend` (`public-api` or `o
 - `source: "local"` (default) — the snapshots n8n-mcp takes before it changes a workflow. Any n8n version, no token, ids are numbers. Blind to edits made in the n8n UI. The only source that supports `delete` and `prune`.
 - `source: "native"` — n8n's own workflow history, the same list the UI shows, including edits made by people. Needs `N8N_MCP_ACCESS_TOKEN` (n8n 2.34+; the native `diff` needs 2.36, where `get_workflow_versions_diff` shipped) and the workflow's "Available in MCP" setting; ids are opaque strings; `list` is capped at 50 with an `offset`; `delete` and `prune` are refused with `MODE_NOT_SUPPORTED_FOR_SOURCE` (n8n owns that retention). Native rollback is not pre-validated — `validateBefore` is accepted and ignored.
 
-`mode: "diff"` compares two versions (`versionId` + `toVersionId`, both from the same source and workflow). A local diff (`data.format: "n8n-mcp"`) reports added/removed/modified nodes as node **IDs**; a native diff (`data.format: "n8n"`) is n8n's own payload with field-level before/after values.
+`mode: "diff"` compares two versions (`versionId` + `toVersionId`, both from the same source and workflow). A local diff (`data.format: "n8n-mcp"`) reports added/removed/modified nodes as node **IDs**; a native diff (`data.format: "n8n"`) is n8n's own payload with field-level before/after values. Branch on `data.format` rather than assuming field names.
+
+Native modes hit the same consent gate as the routed run methods: a workflow whose "Available in MCP" setting is off answers `WORKFLOW_NOT_EXPOSED`, and re-running with `exposeToMcp: true` turns that setting on and retries once (the response then carries `exposedToMcp: true`). It is a visible, persistent change to the workflow — ask the user before passing it. `timeoutMs` (5000-600000) is the client deadline for the native call.
+
+See [WORKFLOW_GUIDE.md](WORKFLOW_GUIDE.md#n8n_workflow_versions-version-control) for every mode with runnable examples of both sources.
 
 ---
 
 ## Data Table Management
 
 `n8n_manage_datatable` is the MCP tool for managing data tables and rows from *outside* a workflow (table actions `createTable`/`listTables`/`getTable`/`updateTable`/`deleteTable`; row actions `getRows`/`insertRows`/`updateRows`/`upsertRows`/`deleteRows`, with filtering, pagination, and `dryRun`). Don't confuse it with the in-workflow `nodes-base.dataTable` node, which reads/writes rows *during execution* (see [n8n-node-configuration → OPERATION_PATTERNS.md](../n8n-node-configuration/OPERATION_PATTERNS.md#data-table-nodes-basedatatable)). Rule of thumb: MCP tool to set up a table once, workflow node to read/write on every execution. `deleteRows` requires a filter; use `dryRun: true` before bulk changes.
 
-**Column actions** — `addColumn`, `deleteColumn`, `renameColumn` — change an existing table's columns, which the Public API cannot do; they run through n8n's MCP server and need `N8N_MCP_ACCESS_TOKEN` (n8n 2.34+). `addColumn` takes `column: {name, type}` (name starts with a letter, letters/digits/underscores only, at most 63 chars); `deleteColumn`/`renameColumn` take the `columnId` from `getTable`, and `renameColumn` puts the new column name in `name`. They address the table by project: `projectId` is resolved automatically when exactly one project is accessible, otherwise the call returns `PROJECT_REQUIRED` and lists the candidates — pass `projectId` (from `n8n_list_catalog({kind: "projects"})`) to skip resolution. Renaming the *table* is not a column action: use `updateTable` on the Public API.
+**Column actions** — `addColumn`, `deleteColumn`, `renameColumn` — change an existing table's columns, which the Public API cannot do; they run through n8n's MCP server and need `N8N_MCP_ACCESS_TOKEN` (n8n 2.34+). `addColumn` takes `column: {name, type}` (name starts with a letter, letters/digits/underscores only, at most 63 chars; type is `string`, `number`, `boolean` or `date`); `deleteColumn`/`renameColumn` take the `columnId` from `getTable`, and `renameColumn` puts the new column name in `name`. They address the table by project: `projectId` is resolved automatically when exactly one project is accessible, otherwise the call returns `PROJECT_REQUIRED` and lists the candidates — pass `projectId` (from `n8n_list_catalog({kind: "projects"})`) to skip resolution. Renaming the *table* is not a column action: use `updateTable` on the Public API.
+
+**`deleteColumn` drops the column's values along with the column, and there is no undo.** That bites hardest where you'd least expect it: a column's type cannot be changed after creation, so "make this column a number" really means drop-and-re-add, which throws away everything in it. Read the values out with `getRows` first if they matter, and confirm with the user before dropping a populated column.
 
 See [OPERATIONS_GUIDE.md](OPERATIONS_GUIDE.md) for all actions, filter conditions, and examples.
 
@@ -318,8 +327,8 @@ See [WORKFLOW_GUIDE.md](WORKFLOW_GUIDE.md) for all actions, the includeUsage sha
 
 The three tools in this section exist only for n8n's instance-level MCP server (a separate endpoint from the Public API). `n8n_manage_agents` and `n8n_explore_node_resources` need `N8N_MCP_ACCESS_TOKEN`; `n8n_list_catalog` works without it and uses the token only for its team-project fallback. Other tools route individual operations through the same server — `n8n_test_workflow` `prepare`/`pinned`/`direct`, `n8n_workflow_versions` `source: "native"`, the `n8n_manage_datatable` column actions — as described in their own sections; see "Tool Availability" below.
 
-- `n8n_manage_agents` — create, configure, validate, run and publish persisted n8n Agents (a standalone assistant artifact: model, instructions, tools, skills, tasks, memory, channels — not the AI Agent workflow node). Actions: `reference`, `search`, `get`, `create`, `mutate`, `validate`, `call`, `publish`, `unpublish`, `revert`, `versions`, `delete`, `discover_assets`, `verify_mcp_server`, `update_integration`. Start with `action: "reference"`, then `discover_assets` → `create` → `mutate` (one resource at a time, always the latest `configHash` — a stale one comes back as `STALE_CONFIG`) → `validate`. `publish` only on explicit request; `call` runs the agent with real credentials and tools and may return `approvals[]` for the human to decide. `timeoutMs` is a top-level parameter (default 30000, 180000 for `call`), not part of `args`. Needs n8n **2.34+** with the agents module; on 2.36.x the agents runtime rejects `azureOpenAiApi`/`aws` credentials. See **n8n-agents** skill's "Persisted n8n Agents" section for the full workflow.
-- `n8n_explore_node_resources` — resolve the real values behind a node's `loadOptions` dropdown or resource-locator `listSearch` (Slack channels, Google Sheets tabs, model lists) using a live credential, instead of guessing an ID. Use it when `get_node` (`standard` detail) shows `dynamicOptions: {methodName, methodType, dependsOn}` on a property — pass that `methodName`/`methodType` plus a `credentialId` from `n8n_manage_credentials({action: "list"})`.
+- `n8n_manage_agents` — create, configure, validate, run and publish persisted n8n Agents (a standalone assistant artifact: model, instructions, tools, skills, tasks, memory, channels — not the AI Agent workflow node). Actions: `reference`, `search`, `get`, `create`, `mutate`, `validate`, `call`, `publish`, `unpublish`, `revert`, `versions`, `delete`, `discover_assets`, `verify_mcp_server`, `update_integration`. Start with `action: "reference"`, then `discover_assets` → `create` → `mutate` (one resource at a time, always the latest hash — n8n returns it as `configHash` and expects it back as `args.baseConfigHash`; a stale one comes back as `STALE_CONFIG`) → `validate`. `publish` only on explicit request; `call` runs the agent with real credentials and tools and may return `approvals[]` for the human to decide. `timeoutMs` is a top-level parameter (default 30000, 180000 for `call`), not part of `args`. Needs n8n **2.34+** with the agents module; on 2.36.x the agents runtime rejects `azureOpenAiApi`/`aws` credentials. Envelope error codes: `NOT_CONFIGURED`, `INVALID_ARGS`, `STALE_CONFIG`, `AGENT_NOT_RUNNABLE`, `AGENT_TOOL_ERROR` (a custom tool that failed to compile, or an unknown `agentId`), plus the shared `OFFICIAL_MCP_*` family (`AUTH_FAILED`, `NOT_ENABLED`, `RATE_LIMITED`, `TOOL_UNAVAILABLE`, `URL_REJECTED`, `TIMEOUT`, `TRANSPORT_ERROR`, `ERROR`). See **n8n-agents** skill's "Persisted n8n Agents" section for the full workflow.
+- `n8n_explore_node_resources` — resolve the real values behind a node's `loadOptions` dropdown or resource-locator `listSearch` (Slack channels, Google Sheets tabs, model lists) using a live credential, instead of guessing an ID. Use it when `get_node` (`standard` detail) shows `dynamicOptions: {methodName, methodType, dependsOn}` on a property. **Six parameters are required and none of them are inferred:** `nodeType` (LONG form), `version` (the node `typeVersion` the method belongs to), `methodName` and `methodType` copied verbatim from `dynamicOptions`, and `credentialType` plus a `credentialId` of that type from `n8n_manage_credentials({action: "list"})`. Whatever the method `dependsOn` goes in `currentNodeParameters`, resource-locator values keeping their `{__rl: true, mode: "id", value: "…"}` shape. Each result's `value` is what belongs in the workflow parameter; `name` is display text only.
 - `n8n_list_catalog` — list instance-level `projects` (personal project marked, gives `projectId` for `n8n_manage_agents`/`n8n_manage_datatable`) or `tags`. Works without the token via the Public API; with it configured, falls back to the official MCP server for team projects when the Public API's licence gate refuses (`teamProjectsEnabled` reports which).
 
 ---
@@ -336,7 +345,7 @@ See [WORKFLOW_GUIDE.md](WORKFLOW_GUIDE.md) for the two scanning approaches, exam
 
 - `tools_documentation()` — overview of all tools; `tools_documentation({topic, depth: "full"})` for a specific tool. Code node guides via topics `javascript_code_node_guide` / `python_code_node_guide`.
 - **AI agent guide** — `tools_documentation({topic: "ai_agents_guide", depth: "full"})` (no standalone tool); returns architecture, connections, tools, validation, best practices.
-- `n8n_health_check()` — quick check; `n8n_health_check({mode: "diagnostic"})` returns status, env vars, tool status, API connectivity.
+- `n8n_health_check()` — quick check; `n8n_health_check({mode: "diagnostic"})` returns status, env vars, tool status, API connectivity. Both modes also return an **`officialMcp`** block — `{configured, endpoint, reachable, toolCount, agentTools}` — the preflight for everything gated on `N8N_MCP_ACCESS_TOKEN`: the agent tools, `n8n_test_workflow`'s routed methods, native version history, the data-table column actions. Read it once before reaching for any of them, rather than discovering the gap through a `NOT_CONFIGURED` envelope mid-task.
 
 See [OPERATIONS_GUIDE.md](OPERATIONS_GUIDE.md) for examples.