agentleFS
pabloirracionalpabloirracional/claude-skills/skills/n8n-automation/SKILL.md

n8n-automation

Skill0 starsChanged 4 months agoMITView on GitHub

Use this skill when the user asks to create, edit, debug, or export n8n workflows/automations ("create an n8n automation", "build a workflow that...", "export the workflows", "why is this workflow failing"). Requires the n8n-mcp Docker MCP server connected (tools like search_nodes, validate_workflow) and, for live-instance actions, an n8n API key configured for the target instance.

3 other projects use a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

8 rules. About 0 are common, 5 are distinctive, and 3 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈5

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    If the n8n_* tools aren't available and the task requires acting on a real instance:

    line 57
  2. Distinctive:

    Ask the user for: the instance's base URL + an API key (n8n → Settings → n8n API → Create API Key).

    line 60
  3. Very specific:

    Never paste the key directly into a visible Bash command, and never echo it back.

    line 62
  4. Distinctive:

    Delete that env file at the end of the task.

    line 66
  5. Distinctive:

    Always in this order — skipping a step produces a workflow that passes syntactic validation but breaks in production:

    line 75
  6. Very specific:

    Never write a credential secret into the workflow JSON — n8n already separates this (credentials: { googleSheetsOAuth2Api: { id, name } } …

    line 99
  7. Distinctive:

    If the workflow needs a credential that doesn't exist on the instance, tell the user — you can't create an OAuth credential via the API, …

    line 102
  8. Distinctive:

    When the request is "save/export the workflows to GitHub":

    line 108

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

n8n Automation (via Docker MCP + n8n API)

Prerequisites (one-time setup)

This skill does nothing on its own — it needs the n8n-mcp toolkit actually connected to Claude Code first. If search_nodes/validate_workflow/etc. aren't in the tool list, none of the steps below will work. Set up, in order:

  1. Docker Desktop — installed and running. This is what actually hosts the n8n-mcp server; Claude Code doesn't run it directly.
  2. VS Code + Claude Code — the Claude Code extension (or CLI) installed in VS Code, signed in, in the project you want to automate.
  3. Connect the MCP server to Claude Code — in Docker Desktop's MCP Toolkit/Catalog, find and enable n8n-mcp, then connect it to your Claude Code client (Docker Desktop's MCP Toolkit has a "Clients" section for this). Once connected, its tools surface in Claude Code as a single aggregated connection, usually named MCP_DOCKER.
  4. Verify the connection — ask Claude to list available tools, or just try search_nodes. If it's not available, the MCP server isn't connected yet — fix that before attempting anything below, rather than troubleshooting workflow logic that was never the actual problem.
  5. For live-instance actions only (creating/listing/updating real workflows, not just looking up node info) — the MCP server additionally needs N8N_API_URL (and an API key) configured for the target n8n instance. See "Credential setup" below for how to get and use that key safely.

Exact menu labels in Docker Desktop's MCP Toolkit change between versions — if steps 3-4 don't match what's on screen, check Docker Desktop's own MCP Toolkit docs rather than assuming this skill's wording is current.

What this skill covers

Creating, editing, validating, and deploying n8n workflows using the n8n-mcp toolkit (running in Docker, exposed as an MCP server — usually shows up as MCP_DOCKER in the tool list) combined with n8n's public REST API for specific instances.

These are two separate capabilities — don't conflate them:

  1. Node knowledge (always available via MCP_DOCKER): search nodes, inspect properties, validate configuration, look up templates. Requires no credentials at all.
  2. Actions on a real instance (n8n_list_workflows, n8n_create_workflow, n8n_update_partial_workflow, n8n_trigger_webhook_workflow): only appear once N8N_API_URL is configured for the MCP server. If they don't show up, the instance isn't connected — don't claim you can create/list workflows without it.

Credential setup (per instance)

If the n8n_* tools aren't available and the task requires acting on a real instance:

  1. Ask the user for: the instance's base URL + an API key (n8n → Settings → n8n API → Create API Key).
  2. Never paste the key directly into a visible Bash command, and never echo it back. Save it to an env file outside the repo (e.g. in the session scratchpad) and reference it via source file && curl -H "X-N8N-API-KEY: $KEY" ....
  3. Delete that env file at the end of the task.
  4. Known limitation: n8n's public API doesn't expose folders/projects (folderId) or project endpoints on instances without an enterprise license — you can only list/filter by workflow. If the user asks for "just the workflows in folder X," flag this limitation before attempting to filter.

Standard creation/editing workflow

Always in this order — skipping a step produces a workflow that passes syntactic validation but breaks in production:

  1. Find the right node search_nodes({query}) or list_nodes({category}) — never assume a node name from memory, packages change between versions.
  2. Configure with essentials first get_node_essentials(nodeType) before get_node_info (which returns 100KB+ and blows up context for no reason). Only escalate to get_node_info if essentials doesn't have the field you need.
  3. Validate before deploying validate_node_minimal → required fields. validate_node_operation → full validation with suggested fixes. validate_workflow → the whole graph (connections, expressions, cycles).
  4. Deploy n8n_create_workflow (new) or n8n_update_partial_workflow (edit via diff — prefer this over recreating the whole workflow for small tweaks).
  5. Confirm Report back to the user: name, ID, status (active/inactive), and whether any trigger needs to be manually activated (webhook, cron) before it actually starts working.

Credentials inside the workflow (nodes using OAuth/API keys)

  • Never write a credential secret into the workflow JSON — n8n already separates this (credentials: { googleSheetsOAuth2Api: { id, name } } is just the reference, the actual value lives in n8n's credential vault).
  • If the workflow needs a credential that doesn't exist on the instance, tell the user — you can't create an OAuth credential via the API, that requires the login flow in the n8n UI.

Exporting / version-controlling workflows (backup to git)

When the request is "save/export the workflows to GitHub":

  • Pull the full JSON via GET /api/v1/workflows (the listing already returns complete nodes/connections — no need for one call per workflow).
  • Export clean, re-importable fields: id, name, active, nodes, connections, settings, staticData, pinData, tags. Drop runtime metadata (activeVersion, versionCounter, shared, publish history) — that's instance-specific noise, not part of the workflow itself.
  • Organize into folders by category inferred from the name (simple regex rules are enough — the user can reorganize later). Generate a manifest.json (category, file, id, status) to allow programmatic reorganization afterward.
  • Private repo by default, unless the user asks for public — workflows almost always have client/internal-process names in the text.

Common mistakes to avoid

  • Treating MCP_DOCKER as if it's already connected to an instance — it's generic until N8N_API_URL is configured.
  • Skipping validate_workflow on the assumption that each node's individual config already guarantees the workflow works — broken connections and malformed expressions only surface in full-graph validation.
  • Generating a workflow with n8n_create_workflow without asking whether it should start active or inactive — workflows with a webhook/cron trigger start running immediately if active: true.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.