n8n-mcp-skills
Expert skills for building n8n workflows
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Check it deeper on your machine
It has changed since its scan on 11 Nov 2026.
As a Claude Code plugin, install it and then ask Claude Code:
/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/czlonkowski/n8n-skills with scanskillsafety
Or from a terminal, clone it and run it:
git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/czlonkowski/n8n-skills'
It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.
Badge for your README
Markdown
[](/listings/czlonkowski-n8n-skills)HTML
<a href="/listings/czlonkowski-n8n-skills"><img src="/api/listings/czlonkowski-n8n-skills/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
Prerequisites
1. **n8n-mcp MCP server** installed and configured ([Installation Guide](https://github.com/czlonkowski/n8n-mcp)). Version 2.97.0+ adds what the native-first guidance builds on: `get_node` standard detail lists each node's `options`, `search_nodes` ranks the core node first for phrases like "group by" or "deduplicate", and `tools_documentation({topic: "expression_helpers"})` documents the expression helpers. Older servers still work; the skills then carry that guidance alone. 2. **Claude Code**, Claude.ai, or Claude API access 3. `.mcp.json` configured with n8n-mcp server
Claude Code
**Method 1: Plugin Installation** (Recommended)
# Install directly as a Claude Code plugin /plugin install czlonkowski/n8n-skills
**Method 2: Via Marketplace**
# Add as marketplace, then browse and install /plugin marketplace add czlonkowski/n8n-skills # Then browse available plugins /plugin install # Select "n8n-mcp-skills" from the list
**Method 3: Manual Installation**
# 1. Clone this repository git clone https://github.com/czlonkowski/n8n-skills.git # 2. Copy skills to your Claude Code skills directory cp -r n8n-skills/skills/* ~/.claude/skills/ # 3. Reload Claude Code # Skills will activate automatically
Claude.ai
1. Download individual skill folders from `skills/` 2. Zip each skill folder (or grab prebuilt zips from the [latest release](https://github.com/czlonkowski/n8n-skills/releases/latest)) 3. Upload via Settings → Capabilities → Skills
ChatGPT and other SKILL.md hosts
1. Download `n8n-skills-all-vX.Y.Z.zip` from the [latest release](https://github.com/czlonkowski/n8n-skills/releases/latest) 2. Unzip it — it holds one `.skill` file per skill (e.g. `n8n-expression-syntax.skill`). Don't upload the bundle itself; it is a container, not a skill 3. In the host's skill upload dialog, select all the `.skill` files at once
API / SDK
See [docs/INSTALLATION.md](docs/INSTALLATION.md) for detailed instructions.
---
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
.claude-plugin/marketplace.json · Manifest · 53 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- {
- "name": "n8n-mcp-skills",
- "description": "Expert skills for building n8n workflows",
- "owner": {
- "name": "Romuald Członkowski",
- "url": "https://aiadvisors.pl/en"
- },
- "plugins": [
- {
- "name": "n8n-mcp-skills",
- "source": "./",
- "skills": [
- "./skills/n8n-expression-syntax",
- "./skills/n8n-mcp-tools-expert",
- "./skills/n8n-workflow-patterns",
- "./skills/n8n-validation-expert",
- "./skills/n8n-node-configuration",
- "./skills/n8n-code-javascript",
- "./skills/n8n-code-python",
- "./skills/n8n-code-tool",
- "./skills/n8n-error-handling",
- "./skills/n8n-binary-and-data",
- "./skills/n8n-subworkflows",
- "./skills/n8n-agents",
- "./skills/n8n-multi-instance",
- "./skills/n8n-self-hosting",
- "./skills/using-n8n-mcp-skills"
- ],
- "description": "Complete bundle: 14 expert skills for building flawless n8n workflows with the n8n-mcp MCP server — and deploying the self-hosted n8n that runs them (expression syntax, MCP tools usage, workflow patterns, validation, node configuration, JavaScript code, Python code, the AI-agent Custom Code Tool, production error handling, binary/file handling, reusable sub-workflows, AI agents, multi-instance targeting, and end-to-end self-hosted deployment), plus an always-on router skill and a hooks enforcement layer that surfaces the right skill at the moment of decision.",
- "version": "1.38.0",
- "author": {
- "name": "Romuald Członkowski",
- "url": "https://aiadvisors.pl/en"
- },
- "category": "automation",
- "keywords": [
- "n8n",
- "workflow",
- "mcp",
- "automation",
- "validation",
- "expressions",
- "code",
- "javascript",
- "python",
- "skills"
- ],
- "homepage": "https://github.com/czlonkowski/n8n-skills",
- "repository": "https://github.com/czlonkowski/n8n-skills",
- "license": "MIT"
- }
- ]
- }
README.md · README · 404 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- # n8n-skills
- **Expert Claude Code skills for building flawless n8n workflows using the n8n-mcp MCP server**
- [](https://skills.sh/czlonkowski/n8n-skills)
- [](https://github.com/czlonkowski/n8n-skills)
- [](LICENSE)
- [](https://github.com/czlonkowski/n8n-mcp)
- ## Watch the Introduction Video
- [](https://youtu.be/e6VvRqmUY2Y?si=6Igply3cadjO6Xx0)
- > 💼 **Need it built for you?** Work with [AiAdvisors — n8n automation audits, builds, and operations](https://aiadvisors.pl/en), run by the author of n8n-mcp and n8n-skills.
- ---
- ## 🎯 What is this?
- This repository contains **14 complementary Claude Code skills** — plus an always-on router skill and a hooks enforcement layer — that teach AI assistants how to build production-ready n8n workflows using the [n8n-mcp](https://github.com/czlonkowski/n8n-mcp) MCP server, and how to deploy the self-hosted n8n that runs them.
- ### Why These Skills Exist
- Building n8n workflows programmatically can be challenging. Common issues include:
- - Using MCP tools incorrectly or inefficiently
- - Getting stuck in validation error loops
- - Not knowing which workflow patterns to use
- - Misconfiguring nodes and their dependencies
- These skills solve these problems by teaching Claude:
- - ✅ Correct n8n expression syntax ({{}} patterns)
- - ✅ How to use n8n-mcp tools effectively
- - ✅ Proven workflow patterns from real-world usage
- - ✅ Validation error interpretation and fixing
- - ✅ Operation-aware node configuration
- ---
- ## 📚 The 14 Skills
- ### 1. **n8n Expression Syntax**
- Teaches correct n8n expression syntax and common patterns.
- **Activates when**: Writing expressions, using {{}} syntax, accessing $json/$node variables, troubleshooting expression errors.
- **Key Features**:
- - Core variables ($json, $node, $now, $env)
- - **Critical gotcha**: Webhook data is under `$json.body`
- - Common mistakes catalog with fixes
- - The transform gatekeeper: service node → native node → short expression → Code; a function body in `{{ }}` is code
- - Built-in helpers (`.pluck()`, `.sum()`, `$ifEmpty()`, `.diffTo()`), expression-only
- ### 2. **n8n MCP Tools Expert** (HIGHEST PRIORITY)
- Expert guide for using n8n-mcp MCP tools effectively.
- **Activates when**: Searching for nodes, validating configurations, accessing templates, managing workflows.
- **Key Features**:
- - Tool selection guide (which tool for which task)
- - nodeType format differences (nodes-base.* vs n8n-nodes-base.*)
- - Validation profiles (minimal/runtime/ai-friendly/strict)
- - Smart parameters (branch="true" for IF nodes)
- - Auto-sanitization system explained
- **Most Important**: Teaches correct MCP tool usage patterns and parameter formats
- ### 3. **n8n Workflow Patterns**
- Build workflows using 5 proven architectural patterns.
- **Activates when**: Creating workflows, connecting nodes, designing automation.
- **Key Features**:
- - 5 proven patterns (webhook processing, HTTP API, database, AI, scheduled)
- - Workflow creation checklist
- - Real examples from 2,653+ n8n templates
- - Connection best practices
- - Pattern selection guide
- ### 4. **n8n Validation Expert**
- Interpret validation errors and guide fixing.
- **Activates when**: Validation fails, debugging workflow errors, handling false positives.
- **Key Features**:
- - Validation loop workflow
- - Real error catalog
- - Auto-sanitization behavior explained
- - False positives guide
- - Profile selection for different stages
- ### 5. **n8n Node Configuration**
- Operation-aware node configuration guidance.
- **Activates when**: Configuring nodes, understanding property dependencies, setting up AI workflows.
- **Key Features**:
- - Property dependency rules (e.g., sendBody → contentType)
- - Operation-specific requirements
- - AI connection types (8 types for AI Agent workflows)
- - Common configuration patterns
- - Configs for the native nodes that replace Code (Summarize, Aggregate, Split Out, Merge, Compare Datasets, Remove Duplicates, Sort/Limit, Date & Time, HTTP Request pagination, Webhook raw body + Crypto) — NATIVE_NODES.md
- ### 6. **n8n Code JavaScript**
- Write effective JavaScript code in n8n Code nodes.
- **Activates when**: Editing or debugging a Code node, or writing a new one after native nodes and expressions are ruled out (the closed list: loops or recursion, state across runs, custom parsing, libraries, heavy all-items work).
- **Key Features**:
- - Data access patterns ($input.all(), $input.first(), $input.item)
- - **Critical gotcha**: Webhook data under `$json.body`
- - Correct return format: `[{json: {...}}]`
- - Built-in functions (`this.helpers.httpRequest()` — the bare `$helpers` global is undefined in the task-runner sandbox; prefer the HTTP Request node for non-trivial/authenticated calls — DateTime, $jmespath())
- - Top 5 error patterns with solutions (covering 62%+ of failures)
- - 10 production-tested patterns, each opening with its native-node alternative
- - The `Why Code:` note every kept Code node carries
- ### 7. **n8n Code Python**
- Write Python code in n8n Code nodes with proper limitations awareness.
- **Activates when**: Writing Python in Code nodes, need to know Python limitations, working with standard library.
- **Key Features**:
- - **Important**: Use JavaScript for 95% of use cases
- - Native Python (n8n 2.x): only `_items` / `_item`, dict access — the Pyodide helpers (`_input`, `_json`, `_node`, `_now`) are gone
- - **Critical limitation**: every import is blocked unless the instance allowlists it (none on n8n Cloud)
- - Sandbox limits (no classes, `type()`, `getattr`, dunders; `nonlocal` not `global`) and verified return shapes
- - 12 import-free patterns, each verified on a live instance
- ### 8. **n8n Code Tool**
- Write code for the AI-agent-callable Custom Code Tool (`@n8n/n8n-nodes-langchain.toolCode`) — a different node from the regular Code node with a different contract.
- **Activates when**: Building a Code Tool attached to an AI Agent, troubleshooting "Wrong output type returned" or "No execution data available" errors, deciding between unstructured `query` parsing and `specifyInputSchema`.
- **Key Features**:
- - **Critical distinction**: Code Tool ≠ Code node (different node type, different return format, different sandbox)
- - **Return format**: a **string** (use `JSON.stringify()` for structured output) — NOT `[{json:{...}}]`
- - **Input binding**: `query` (JS) / `_query` (Python) — `$fromAI()` does NOT work here
- - Unstructured vs structured input modes (`specifyInputSchema` → DynamicStructuredTool)
- - Sandbox limits: no `$input`, `$helpers`, `$json`, `$getWorkflowStaticData`, no state across calls
- - Three signature error strings with causes and fixes
- - When to use Code Tool vs `toolWorkflow` vs HTTP Request Tool
- ### 9. **n8n Error Handling**
- Make failures loud, structured, and recoverable.
- **Activates when**: Building webhook/API or unattended workflows, wiring error outputs, setting retries, designing 4xx/5xx responses, or chasing silent failures.
- **Key Features**:
- - Per-node error output: the two-step `onError: continueErrorOutput` + wire `main[1]` trap
- - `retryOnFail` self-healing for flaky network calls
- - 4xx/5xx response-shape mapping (and the `responseCode`-defaults-to-200 gotcha)
- - Error Trigger workflows for unattended runs
- ### 10. **n8n Binary & Data**
- Handle files, images, and binary data correctly.
- **Activates when**: Working with files, images, PDFs, attachments, uploads/downloads, vision input, or passing a file to/from an AI agent tool.
- **Key Features**:
- - `$binary` vs `$json` — file contents never live in `$json`
- - Keeping binary alive across JSON transforms with Merge
- - The agent-tool binary boundary (pre-stage to storage, pass keys/URLs)
- - CDN/URL requirement for showing images in chat surfaces
- ### 11. **n8n Sub-workflows**
- Build reusable, composable sub-workflows.
- **Activates when**: Extracting shared logic, building multi-step or reused workflows, or any workflow over ~10 nodes.
- **Key Features**:
- - Execute Workflow Trigger with "Define Below" typed inputs (not passthrough)
- - `mode: all` vs `each` and `waitForSubWorkflow` (the only true parallelization)
- - Verb-first prefix naming for discovery (MCP can't filter by tags)
- - Stateless vs stateful design; N+1 split-by-input-shape
- ### 12. **n8n AI Agents**
- Design n8n AI agents the right way.
- **Activates when**: Building any `@n8n/n8n-nodes-langchain.*` node — AI Agent, LLM chain, Text Classifier — or working with tool calling, `$fromAI`, memory, structured output, RAG, or chat bots.
- **Key Features**:
- - Agent vs LLM Chain vs Text Classifier; the model/memory/tools/outputParser slots
- - Tool names & descriptions ARE the prompt; `$fromAI` parameter anatomy
- - Structured output with autoFix; memory + sessionId; human-in-the-loop review
- - Chat shell+core+sub-agent topology with anti-loop filtering
- ### 13. **n8n Multi-Instance**
- Target the right n8n instance when an account has more than one.
- **Activates when**: The `n8n_instances` tool is available, the user mentions multiple instances/environments (prod vs staging, several clients) or several agents working at once, or a call returns an unexpected `NOT_FOUND` or wrong/empty data.
- **Key Features**:
- - The per-call `instance` argument: name the target on each call, so parallel agents on one connection can work on different instances at once
- - `n8n_instances` `list`/`switch` shapes and the real error envelopes (`INSTANCE_NOT_FOUND`, `INSTANCE_AMBIGUOUS`, `UNKNOWN_INSTANCE`, …)
- - `switch` as the shared default for unnamed calls, and why it moves every chat on a hosted connection
- - Naming the instance on credential writes — a named write is never ambiguous
- - Recovering from a misroute (NOT_FOUND ≈ wrong instance, not a deletion) and copying objects between instances
- ### 14. **n8n Self-Hosting** (deployment/ops)
- Deploy a production self-hosted n8n end-to-end to a fresh Linux VM.
- **Activates when**: Self-hosting, installing, or deploying n8n on your own server/VPS (Hetzner, DigitalOcean, EC2, bare metal) — single or queue mode — or updating/backing-up/hardening it. Not for n8n Cloud, and not for building workflows.
- **Key Features**:
- - Docker Compose behind **Caddy** with automatic HTTPS; asks **single vs queue mode** first
- - Single (SQLite) and queue (main + Redis + Postgres + workers) templates, secret-free and domain-free
- - Generates fresh secrets on the box; secure defaults (explicit encryption key, no published internal ports, telemetry off, env-access blocked, execution pruning)
- - DNS/ports preflight, end-to-end verify (cert + reachability), and Day-2 (update / backup / restore)
- > This is the pack's one **deployment** skill; it triggers on its own description and is not part of the workflow-building router/hooks flow.
- ---
- ## 🪝 Enforcement Layer (hooks + router)
- Beyond the capability skills, the plugin ships an **always-on enforcement layer** so the right guidance surfaces at the moment of decision — not only when a query happens to match a skill description.
- - **Router skill (`using-n8n-mcp-skills`)** — loaded into every session by a `SessionStart` hook. It routes you to the right skill, summarizes every n8n-mcp tool, and states the cross-cutting rules. It re-fires on resume/clear/compact so it survives context compaction.
- - **PreToolUse hooks** — before high-impact n8n-mcp calls, a short reminder points at the relevant skill. Looking up a Set, Code, Merge, Loop Over Items, Date & Time, Data Table, or AI Agent node via `get_node` fires a node-specific reminder (and re-fires each time, because a re-lookup usually means you're reconsidering the same decision). Create and update calls are scanned for Code / HTTP Request nodes without a `Why Code:` / `Why HTTP:` note and for function bodies inside `{{ }}`, with one short reminder per node. Calls to `n8n_instances` and `n8n_manage_credentials` fire one-shot reminders pointing at the multi-instance and credential-discipline skills.
- - **PostToolUse hook** — after `validate_workflow`, it inspects the workflow's node types and routes you to the skills that own the remaining risks, with the reminder that *validation passing is necessary, not sufficient*.
- Hooks run only in the **Claude Code / Codex plugin** install. On Claude.ai (individual skill uploads) the skills still activate by description — the pack degrades gracefully, just without the proactive nudges. Every hook fails open and never blocks a tool call.
- ---
- ## 🚀 Installation
- ### Prerequisites
- 1. **n8n-mcp MCP server** installed and configured ([Installation Guide](https://github.com/czlonkowski/n8n-mcp)). Version 2.97.0+ adds what the native-first guidance builds on: `get_node` standard detail lists each node's `options`, `search_nodes` ranks the core node first for phrases like "group by" or "deduplicate", and `tools_documentation({topic: "expression_helpers"})` documents the expression helpers. Older servers still work; the skills then carry that guidance alone.
- 2. **Claude Code**, Claude.ai, or Claude API access
- 3. `.mcp.json` configured with n8n-mcp server
- ### Claude Code
- **Method 1: Plugin Installation** (Recommended)
- ```bash
- # Install directly as a Claude Code plugin
- /plugin install czlonkowski/n8n-skills
- ```
- **Method 2: Via Marketplace**
- ```bash
- # Add as marketplace, then browse and install
- /plugin marketplace add czlonkowski/n8n-skills
- # Then browse available plugins
- /plugin install
- # Select "n8n-mcp-skills" from the list
- ```
- **Method 3: Manual Installation**
- ```bash
- # 1. Clone this repository
- git clone https://github.com/czlonkowski/n8n-skills.git
- # 2. Copy skills to your Claude Code skills directory
- cp -r n8n-skills/skills/* ~/.claude/skills/
- # 3. Reload Claude Code
- # Skills will activate automatically
- ```
- ### Claude.ai
- 1. Download individual skill folders from `skills/`
- 2. Zip each skill folder (or grab prebuilt zips from the [latest release](https://github.com/czlonkowski/n8n-skills/releases/latest))
- 3. Upload via Settings → Capabilities → Skills
- ### ChatGPT and other SKILL.md hosts
- 1. Download `n8n-skills-all-vX.Y.Z.zip` from the [latest release](https://github.com/czlonkowski/n8n-skills/releases/latest)
- 2. Unzip it — it holds one `.skill` file per skill (e.g. `n8n-expression-syntax.skill`). Don't upload the bundle itself; it is a container, not a skill
- 3. In the host's skill upload dialog, select all the `.skill` files at once
- ### API / SDK
- See [docs/INSTALLATION.md](docs/INSTALLATION.md) for detailed instructions.
- ---
- ## 💡 Usage
- Skills activate **automatically** when relevant queries are detected:
- ```
- "How do I write n8n expressions?"
- → Activates: n8n Expression Syntax
- "Find me a Slack node"
- → Activates: n8n MCP Tools Expert
- "Build a webhook workflow"
- → Activates: n8n Workflow Patterns
- "Why is validation failing?"
- → Activates: n8n Validation Expert
- "How do I configure the HTTP Request node?"
- → Activates: n8n Node Configuration
- "How do I access webhook data in a Code node?"
- → Activates: n8n Code JavaScript
- "Can I use pandas in Python Code node?"
- → Activates: n8n Code Python
- "Why does my Code Tool throw 'Wrong output type returned'?"
- → Activates: n8n Code Tool
- ```
- ### Skills Work Together
- When you ask: **"Build and validate a webhook to Slack workflow"**
- 1. **n8n Workflow Patterns** identifies webhook processing pattern
- 2. **n8n MCP Tools Expert** searches for webhook and Slack nodes
- 3. **n8n Node Configuration** guides node setup
- 4. **n8n Code JavaScript** helps process webhook data with proper .body access
- 5. **n8n Expression Syntax** helps with data mapping in other nodes
- 6. **n8n Validation Expert** validates the final workflow
- All skills compose seamlessly!
- ---
- ## 📖 Documentation
- - [Installation Guide](docs/INSTALLATION.md) - Detailed installation for all platforms
- - [Usage Guide](docs/USAGE.md) - How to use skills effectively
- - [Development Guide](docs/DEVELOPMENT.md) - Contributing and testing
- - [MCP Testing Log](docs/MCP_TESTING_LOG.md) - Real tool responses used in skills
- ---
- ## 🧪 Testing
- Each skill includes 3+ evaluations for quality assurance:
- ```bash
- # Run evaluations (if testing framework available)
- npm test
- # Or manually test with Claude
- claude-code --skill n8n-expression-syntax "Test webhook data access"
- ```
- ---
- ## 🤝 Contributing
- Contributions welcome! Please see [DEVELOPMENT.md](docs/DEVELOPMENT.md) for guidelines.
- ### Development Approach
- 1. **Evaluation-First**: Write test scenarios before implementation
- 2. **MCP-Informed**: Test tools, document real responses
- 3. **Iterative**: Test against evaluations, iterate until 100% pass
- 4. **Concise**: Keep SKILL.md under 500 lines
- 5. **Real Examples**: All examples from real templates/tools
- ---
- ## 📝 License
- MIT License - see [LICENSE](LICENSE) file for details.
- ---
- ## 🙏 Credits
- **Conceived by Romuald Członkowski**
- - Website: [aiadvisors.pl/en](https://aiadvisors.pl/en)
- - Part of the [n8n-mcp project](https://github.com/czlonkowski/n8n-mcp)
- The hooks enforcement layer adapts patterns from the official [n8n Skills](https://github.com/n8n-io/skills) project (Apache-2.0), retargeted for n8n-mcp and rewritten in our own voice. See [NOTICES](NOTICES).
- ---
- ## 🔗 Related Projects
- - [n8n-mcp](https://github.com/czlonkowski/n8n-mcp) - MCP server for n8n
- - [n8n](https://n8n.io/) - Workflow automation platform
- ---
- ## 📊 What's Included
- - **14** complementary skills that work together
- - **525+** n8n nodes supported
- - **2,653+** workflow templates for examples
- - **10** production-tested Code node patterns
- - **Comprehensive** error catalogs and troubleshooting guides
- ---
- **Ready to build flawless n8n workflows? Get started now!** 🚀
- ---
- ## 💼 Need it built for you?
- Work with **[AiAdvisors — n8n automation audits, builds, and operations](https://aiadvisors.pl/en)**, run by the author of n8n-mcp and n8n-skills.
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.