{
  "markdown": "# n8n-skills\n\n**Expert Claude Code skills for building flawless n8n workflows using the n8n-mcp MCP server**\n\n[![skills.sh](https://skills.sh/b/czlonkowski/n8n-skills)](https://skills.sh/czlonkowski/n8n-skills)\n[![GitHub stars](https://img.shields.io/github/stars/czlonkowski/n8n-skills?style=social)](https://github.com/czlonkowski/n8n-skills)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![n8n-mcp](https://img.shields.io/badge/n8n--mcp-compatible-green.svg)](https://github.com/czlonkowski/n8n-mcp)\n\n## Watch the Introduction Video\n\n[![n8n Skills Introduction](skills.png)](https://youtu.be/e6VvRqmUY2Y?si=6Igply3cadjO6Xx0)\n\n> 💼 **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.\n\n---\n\n## 🎯 What is this?\n\nThis 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.\n\n### Why These Skills Exist\n\nBuilding n8n workflows programmatically can be challenging. Common issues include:\n- Using MCP tools incorrectly or inefficiently\n- Getting stuck in validation error loops\n- Not knowing which workflow patterns to use\n- Misconfiguring nodes and their dependencies\n\nThese skills solve these problems by teaching Claude:\n- ✅ Correct n8n expression syntax ({{}} patterns)\n- ✅ How to use n8n-mcp tools effectively\n- ✅ Proven workflow patterns from real-world usage\n- ✅ Validation error interpretation and fixing\n- ✅ Operation-aware node configuration\n\n---\n\n## 📚 The 14 Skills\n\n### 1. **n8n Expression Syntax**\nTeaches correct n8n expression syntax and common patterns.\n\n**Activates when**: Writing expressions, using {{}} syntax, accessing $json/$node variables, troubleshooting expression errors.\n\n**Key Features**:\n- Core variables ($json, $node, $now, $env)\n- **Critical gotcha**: Webhook data is under `$json.body`\n- Common mistakes catalog with fixes\n- When NOT to use expressions (Code nodes!)\n\n### 2. **n8n MCP Tools Expert** (HIGHEST PRIORITY)\nExpert guide for using n8n-mcp MCP tools effectively.\n\n**Activates when**: Searching for nodes, validating configurations, accessing templates, managing workflows.\n\n**Key Features**:\n- Tool selection guide (which tool for which task)\n- nodeType format differences (nodes-base.* vs n8n-nodes-base.*)\n- Validation profiles (minimal/runtime/ai-friendly/strict)\n- Smart parameters (branch=\"true\" for IF nodes)\n- Auto-sanitization system explained\n\n**Most Important**: Teaches correct MCP tool usage patterns and parameter formats\n\n### 3. **n8n Workflow Patterns**\nBuild workflows using 5 proven architectural patterns.\n\n**Activates when**: Creating workflows, connecting nodes, designing automation.\n\n**Key Features**:\n- 5 proven patterns (webhook processing, HTTP API, database, AI, scheduled)\n- Workflow creation checklist\n- Real examples from 2,653+ n8n templates\n- Connection best practices\n- Pattern selection guide\n\n### 4. **n8n Validation Expert**\nInterpret validation errors and guide fixing.\n\n**Activates when**: Validation fails, debugging workflow errors, handling false positives.\n\n**Key Features**:\n- Validation loop workflow\n- Real error catalog\n- Auto-sanitization behavior explained\n- False positives guide\n- Profile selection for different stages\n\n### 5. **n8n Node Configuration**\nOperation-aware node configuration guidance.\n\n**Activates when**: Configuring nodes, understanding property dependencies, setting up AI workflows.\n\n**Key Features**:\n- Property dependency rules (e.g., sendBody → contentType)\n- Operation-specific requirements\n- AI connection types (8 types for AI Agent workflows)\n- Common configuration patterns\n\n### 6. **n8n Code JavaScript**\nWrite effective JavaScript code in n8n Code nodes.\n\n**Activates when**: Writing JavaScript in Code nodes, troubleshooting Code node errors, making HTTP requests with `this.helpers` (the `$helpers` global), working with dates.\n\n**Key Features**:\n- Data access patterns ($input.all(), $input.first(), $input.item)\n- **Critical gotcha**: Webhook data under `$json.body`\n- Correct return format: `[{json: {...}}]`\n- 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())\n- Top 5 error patterns with solutions (covering 62%+ of failures)\n- 10 production-tested patterns\n\n### 7. **n8n Code Python**\nWrite Python code in n8n Code nodes with proper limitations awareness.\n\n**Activates when**: Writing Python in Code nodes, need to know Python limitations, working with standard library.\n\n**Key Features**:\n- **Important**: Use JavaScript for 95% of use cases\n- Python data access (_input, _json, _node)\n- **Critical limitation**: No external libraries (requests, pandas, numpy)\n- Standard library reference (json, datetime, re, etc.)\n- Workarounds for missing libraries\n- Common Python patterns for n8n\n\n### 8. **n8n Code Tool**\nWrite 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.\n\n**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`.\n\n**Key Features**:\n- **Critical distinction**: Code Tool ≠ Code node (different node type, different return format, different sandbox)\n- **Return format**: a **string** (use `JSON.stringify()` for structured output) — NOT `[{json:{...}}]`\n- **Input binding**: `query` (JS) / `_query` (Python) — `$fromAI()` does NOT work here\n- Unstructured vs structured input modes (`specifyInputSchema` → DynamicStructuredTool)\n- Sandbox limits: no `$input`, `$helpers`, `$json`, `$getWorkflowStaticData`, no state across calls\n- Three signature error strings with causes and fixes\n- When to use Code Tool vs `toolWorkflow` vs HTTP Request Tool\n\n### 9. **n8n Error Handling**\nMake failures loud, structured, and recoverable.\n\n**Activates when**: Building webhook/API or unattended workflows, wiring error outputs, setting retries, designing 4xx/5xx responses, or chasing silent failures.\n\n**Key Features**:\n- Per-node error output: the two-step `onError: continueErrorOutput` + wire `main[1]` trap\n- `retryOnFail` self-healing for flaky network calls\n- 4xx/5xx response-shape mapping (and the `responseCode`-defaults-to-200 gotcha)\n- Error Trigger workflows for unattended runs\n\n### 10. **n8n Binary & Data**\nHandle files, images, and binary data correctly.\n\n**Activates when**: Working with files, images, PDFs, attachments, uploads/downloads, vision input, or passing a file to/from an AI agent tool.\n\n**Key Features**:\n- `$binary` vs `$json` — file contents never live in `$json`\n- Keeping binary alive across JSON transforms with Merge\n- The agent-tool binary boundary (pre-stage to storage, pass keys/URLs)\n- CDN/URL requirement for showing images in chat surfaces\n\n### 11. **n8n Sub-workflows**\nBuild reusable, composable sub-workflows.\n\n**Activates when**: Extracting shared logic, building multi-step or reused workflows, or any workflow over ~10 nodes.\n\n**Key Features**:\n- Execute Workflow Trigger with \"Define Below\" typed inputs (not passthrough)\n- `mode: all` vs `each` and `waitForSubWorkflow` (the only true parallelization)\n- Verb-first prefix naming for discovery (MCP can't filter by tags)\n- Stateless vs stateful design; N+1 split-by-input-shape\n\n### 12. **n8n AI Agents**\nDesign n8n AI agents the right way.\n\n**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.\n\n**Key Features**:\n- Agent vs LLM Chain vs Text Classifier; the model/memory/tools/outputParser slots\n- Tool names & descriptions ARE the prompt; `$fromAI` parameter anatomy\n- Structured output with autoFix; memory + sessionId; human-in-the-loop review\n- Chat shell+core+sub-agent topology with anti-loop filtering\n\n### 13. **n8n Multi-Instance**\nTarget the right n8n instance when an account has more than one.\n\n**Activates when**: The `n8n_instances` tool is available, the user mentions multiple instances/environments (prod vs staging, several clients), or a call returns an unexpected `NOT_FOUND` or wrong/empty data.\n\n**Key Features**:\n- `n8n_instances` `list`/`switch` shapes and the real error envelope (`UNKNOWN_INSTANCE`, `MULTI_INSTANCE_DISABLED`, …)\n- Switching in its own turn; the per-session binding that persists across reconnects/deploys\n- Verifying `current` before credential writes — the server fail-closes only the *ambiguous* case (`INSTANCE_AMBIGUOUS`); an explicit wrong switch still writes the secret silently\n- Recovering from a misroute (NOT_FOUND ≈ wrong instance, not a deletion) and copying objects between instances\n\n### 14. **n8n Self-Hosting** (deployment/ops)\nDeploy a production self-hosted n8n end-to-end to a fresh Linux VM.\n\n**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.\n\n**Key Features**:\n- Docker Compose behind **Caddy** with automatic HTTPS; asks **single vs queue mode** first\n- Single (SQLite) and queue (main + Redis + Postgres + workers) templates, secret-free and domain-free\n- Generates fresh secrets on the box; secure defaults (explicit encryption key, no published internal ports, telemetry off, env-access blocked, execution pruning)\n- DNS/ports preflight, end-to-end verify (cert + reachability), and Day-2 (update / backup / restore)\n\n> 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.\n\n---\n\n## 🪝 Enforcement Layer (hooks + router)\n\nBeyond 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.\n\n- **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.\n- **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, DateTime, 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). Calls to `n8n_instances` and `n8n_manage_credentials` fire one-shot reminders pointing at the multi-instance and credential-discipline skills.\n- **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*.\n\nHooks 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.\n\n---\n\n## 🚀 Installation\n\n### Prerequisites\n\n1. **n8n-mcp MCP server** installed and configured ([Installation Guide](https://github.com/czlonkowski/n8n-mcp))\n2. **Claude Code**, Claude.ai, or Claude API access\n3. `.mcp.json` configured with n8n-mcp server\n\n### Claude Code\n\n**Method 1: Plugin Installation** (Recommended)\n```bash\n# Install directly as a Claude Code plugin\n/plugin install czlonkowski/n8n-skills\n```\n\n**Method 2: Via Marketplace**\n```bash\n# Add as marketplace, then browse and install\n/plugin marketplace add czlonkowski/n8n-skills\n\n# Then browse available plugins\n/plugin install\n# Select \"n8n-mcp-skills\" from the list\n```\n\n**Method 3: Manual Installation**\n```bash\n# 1. Clone this repository\ngit clone https://github.com/czlonkowski/n8n-skills.git\n\n# 2. Copy skills to your Claude Code skills directory\ncp -r n8n-skills/skills/* ~/.claude/skills/\n\n# 3. Reload Claude Code\n# Skills will activate automatically\n```\n\n### Claude.ai\n\n1. Download individual skill folders from `skills/`\n2. Zip each skill folder (or grab prebuilt zips from the [latest release](https://github.com/czlonkowski/n8n-skills/releases/latest))\n3. Upload via Settings → Capabilities → Skills\n\n### API / SDK\n\nSee [docs/INSTALLATION.md](docs/INSTALLATION.md) for detailed instructions.\n\n---\n\n## 💡 Usage\n\nSkills activate **automatically** when relevant queries are detected:\n\n```\n\"How do I write n8n expressions?\"\n→ Activates: n8n Expression Syntax\n\n\"Find me a Slack node\"\n→ Activates: n8n MCP Tools Expert\n\n\"Build a webhook workflow\"\n→ Activates: n8n Workflow Patterns\n\n\"Why is validation failing?\"\n→ Activates: n8n Validation Expert\n\n\"How do I configure the HTTP Request node?\"\n→ Activates: n8n Node Configuration\n\n\"How do I access webhook data in a Code node?\"\n→ Activates: n8n Code JavaScript\n\n\"Can I use pandas in Python Code node?\"\n→ Activates: n8n Code Python\n\n\"Why does my Code Tool throw 'Wrong output type returned'?\"\n→ Activates: n8n Code Tool\n```\n\n### Skills Work Together\n\nWhen you ask: **\"Build and validate a webhook to Slack workflow\"**\n\n1. **n8n Workflow Patterns** identifies webhook processing pattern\n2. **n8n MCP Tools Expert** searches for webhook and Slack nodes\n3. **n8n Node Configuration** guides node setup\n4. **n8n Code JavaScript** helps process webhook data with proper .body access\n5. **n8n Expression Syntax** helps with data mapping in other nodes\n6. **n8n Validation Expert** validates the final workflow\n\nAll skills compose seamlessly!\n\n---\n\n## 📖 Documentation\n\n- [Installation Guide](docs/INSTALLATION.md) - Detailed installation for all platforms\n- [Usage Guide](docs/USAGE.md) - How to use skills effectively\n- [Development Guide](docs/DEVELOPMENT.md) - Contributing and testing\n- [MCP Testing Log](docs/MCP_TESTING_LOG.md) - Real tool responses used in skills\n\n---\n\n\n## 🧪 Testing\n\nEach skill includes 3+ evaluations for quality assurance:\n\n```bash\n# Run evaluations (if testing framework available)\nnpm test\n\n# Or manually test with Claude\nclaude-code --skill n8n-expression-syntax \"Test webhook data access\"\n```\n\n---\n\n## 🤝 Contributing\n\nContributions welcome! Please see [DEVELOPMENT.md](docs/DEVELOPMENT.md) for guidelines.\n\n### Development Approach\n\n1. **Evaluation-First**: Write test scenarios before implementation\n2. **MCP-Informed**: Test tools, document real responses\n3. **Iterative**: Test against evaluations, iterate until 100% pass\n4. **Concise**: Keep SKILL.md under 500 lines\n5. **Real Examples**: All examples from real templates/tools\n\n---\n\n## 📝 License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n---\n\n## 🙏 Credits\n\n**Conceived by Romuald Członkowski**\n- Website: [aiadvisors.pl/en](https://aiadvisors.pl/en)\n- Part of the [n8n-mcp project](https://github.com/czlonkowski/n8n-mcp)\n\nThe 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).\n\n---\n\n## 🔗 Related Projects\n\n- [n8n-mcp](https://github.com/czlonkowski/n8n-mcp) - MCP server for n8n\n- [n8n](https://n8n.io/) - Workflow automation platform\n\n---\n\n## 📊 What's Included\n\n- **14** complementary skills that work together\n- **525+** n8n nodes supported\n- **2,653+** workflow templates for examples\n- **10** production-tested Code node patterns\n- **Comprehensive** error catalogs and troubleshooting guides\n\n---\n\n**Ready to build flawless n8n workflows? Get started now!** 🚀\n\n---\n\n## 💼 Need it built for you?\n\nWork with **[AiAdvisors — n8n automation audits, builds, and operations](https://aiadvisors.pl/en)**, run by the author of n8n-mcp and n8n-skills.\n",
  "bytes": 16258,
  "sha": "fa20d16b7dd2b0bb04873c01cdd38039aebe919d2c498f573d2597526c4c440f",
  "repo_slug": "czlonkowski/n8n-skills",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/skl_czlonkowski_n8n_skills_n8n_error_handlin_a0522424/readme"
}