Home / All Skills / Workflow & Core Tools / n8n-workflow-skills
English (EN)简体中文 (ZH)日本語 (JA)
Workflow & Core Tools · czlonkowski/n8n-skills

n8n-workflow-skills

Use when building, editing, validating, testing, or debugging an n8n workflow through the n8n-mcp MCP server — designing a flow, configuring a node, writing an expression or Code node, wiring credentials, or fixing one that misbehaves. The entry-point skill for the n8n-mcp-skills pack: it routes you to the right specialist skill, gives working knowledge of every n8n-mcp tool from turn one, and states the rules that keep workflows from breaking in production. Always consult it first on any n8n, workflow, node, or automation task — even a quick one-off, and even when the user names no skill — because n8n's surface drifts between versions and the specialist skills prevent silent failures.

L4 High-Privilege · Graded auth & full auditV1 Commit-PinnedExecute CommandNetwork AccessWrite FileDual-pass Audit
Author czlonkowskiGitHub czlonkowski/n8n-skills ↗Stars 6233License MIT（仓库根 LICENSE：L1 'MIT License'、L3 'Copyright (c) 2025 Romuald Członkowski'）；另 NOTICES 声明 hooks/ 下 11 个文件改编自 n8n-io/skills（Apache-2.0）并附 NOTICES-APACHE-2.0.txtCommit 2df0f18cb5
Control levels describe skill capabilities and suggested control measures; they do not represent quality or safety certifications, nor do they dictate usability. Usage decisions rest entirely with users and administrators. Different agent hosts apply varying constraints; do not assume hosts provide automatic protection. Third-party skill copyrights belong to their original authors. Use at your own risk.

1How It Works & Mechanism

All tool capabilities originate from the external n8n-mcp MCP server, with this repository serving solely as the skill layer; the managed mode is declared via a streamable-http endpoint, with tool names formatted as `mcp__n8n-mcp__*`.

mcp.json
"url": "https://api.n8n-mcp.com/mcp"
The preceding line is `"type": "streamable-http",`; the same file also provides an npx self-hosted variant (.mcp.json.example requires N8N_API_URL / N8N_API_KEY placed in the MCP server's environment; repository scripts themselves do not read these two variables).

The entry-point skill achieves 'always loaded' behavior by having a SessionStart hook read the entire SKILL.md and inject it into additionalContext across every session (including resume/clear/compact).

hooks/session-start.sh
META_SKILL="${PLUGIN_ROOT}/skills/using-n8n-mcp-skills/SKILL.md"
Subsequently, `SKILL_BODY="$(cat "${META_SKILL}")"` reads the full text and uses jq to generate hookSpecificOutput.additionalContext; when source=clear/compact, it also deletes the session's reminder deduplication marker to re-enable alerts.

'Just-in-time decision hints' are implemented via a hook registry: anchored regexes match full MCP tool names, executing bash scripts in the same directory upon a match.

hooks/hooks.json
"matcher": "^mcp__.*__get_node$",
The matcher's command targets `${CLAUDE_PLUGIN_ROOT}/hooks/pre-tool-use/get-node.sh`; the same file registers 1 SessionStart + 7 PreToolUse hooks (create/update/validate/test/instances/manage_credentials/get_node) + 1 PostToolUse hook.

General reminders use one-time deduplication: creating a .loaded marker named session_id + marker in a temp directory ensures no repeated interruptions within the same session.

hooks/pre-tool-use/_emit.sh
MARKER="${STATE_DIR}/${SESSION_ID}-${MARKER_NAME}.loaded"
STATE_DIR = ${TMPDIR:-/tmp}/n8n-mcp-skills-state; falls back to python3 to parse session_id from stdin if jq is missing, and exits 0 immediately if neither is available.

Node-level high-risk reminders are deliberately not deduplicated: alerts are reinjected every time Set/Code/Merge/Loop/DateTime/DataTable/Agent nodes are queried, on the premise that repeated queries often signify reconsidering the same anti-pattern.

hooks/pre-tool-use/get-node.sh
# High-risk-node warnings: NOT deduped. Each lookup fires the warning fresh.
The node type's short name (e.g., nodes-base.set) is extracted from `.tool_input.nodeType`, evaluated sequentially against regex patterns, and assembled into WARNINGS for a single output.

PostToolUse parses the workflow JSON's node types after validate_workflow, routing remaining risks back to corresponding specialist skills while emphasizing that 'validation passed ≠ correct'.

hooks/post-tool-use/validate-workflow.sh
(.tool_input.workflow.nodes // .tool_input.nodes // [])
Script comments note that extracting LONG-form types (e.g., n8n-nodes-base.set) is more reliable than grepping source code; when no node JSON is present (by-id validation), it outputs a generic hint prompting manual invocation of the validation + workflow-patterns skills.

Skill content employs progressive disclosure: SKILL.md retains only the core instructions and index, placing detailed guides in neighboring reference .md files loaded on-demand via relative links in the body.

skills/n8n-code-javascript/SKILL.md
**See**: [DATA_ACCESS.md](DATA_ACCESS.md) → "Mode Performance" for the corollaries, hop costs, and scale check.
Related Files at the end of each skill document lists its reference files; the self-hosting skill externalizes deployment specifics into SECURITY.md / QUEUE_MODE.md.

The self-hosting skill places deployment templates in assets/, directing the agent to copy them to the target machine via SSH and launch with docker compose—the only skill in the pack that 'instructs the agent to execute commands on a remote host'.

skills/n8n-self-hosting/SKILL.md
`ssh <target> 'cat > <DATA_FOLDER>/docker-compose.yml' < assets/docker-compose.single.yml`.
Templates contain no secrets (enforcing 'Secrets live only in `.env`', mode 600); pre-deployment also mandates preflight checks for DNS/public IP using `curl -s ifconfig.me` and dig.

The packaging script enforces version consistency via hard assertions: any version mismatch between the two manifests results in exit 1, followed by auto-discovering skill directories to build zip archives.

build.sh
VERSION=$(read_version .claude-plugin/plugin.json)
The next line runs `AGENT_PLUGIN_VERSION=$(read_version plugin.json)`; prints 'Version mismatch' and exits upon mismatch. Outputs individual skill zips and an all-in-one zip under dist/ (which is ignored by .gitignore).

2Core Capabilities

01Entry routing: Determines which specialist skill to load first rather than jumping directly into execution
02Three non-negotiable rules (load skills first / validate and verify connections / no secrets in text fields)
03Tool surface as knowledge: Uses qualified names `mcp__<server>__<tool>` to clarify available tools, bridging gaps where tool descriptions are not loaded
04Red flag table: Maps thoughts like 'I am about to...' directly to mandatory specialist skills
05Hook enforcement layer: Injects 'which skill to load right now' at session start and around key MCP tool calls
06Credential discipline and multi-instance safety: Enforces verification of the active instance before credential write operations to avoid misplacing secrets
07End-to-end self-hosted deployment (SSH + Docker Compose + Caddy automatic TLS)

3External Dependencies

KindDependency / Endpoint
apin8n-mcp 托管 MCP 端点（streamable-http，OAuth 登录）
network托管端点的接入说明（OAuth 后于 dashboard 连接自己的 n8n 实例）
packagenpm 包 n8n-mcp（经 npx 从 registry 拉取，自托管模式）
clinpx（启动 stdio 模式 MCP server 的示例配置）
clidocker / docker compose（自托管技能在目标机上执行）
package容器镜像：Caddy（自动 TLS）与 n8n 本体
network部署前公网 IP / DNS 预检（curl 与 dig）
clihook 运行时依赖 jq，缺失时回退 python3，都没有则静默放弃

4Recommended Governance & Evidence

Suggested Controls for Safe Operation
For Agent Runtime
Graded/per-use authorization, sandbox recommended
For Administrators
Approval workflow, rollback support, full audit
Evidence & Triggers (File Paths & Excerpts)
  • scripts/: Executes local scripts or commands: The host calls repository scripts via hooks.json: SessionStart→hooks/session-start.sh (`"command": "${C
  • 网络端点: Declares external network access: Zero network calls in hook scripts: no curl/wget/nc/dev-tcp/eval calls throughout hooks/; only reads stdin, writes /tmp markers, and outputs
  • 本地工作目录: File read/write and artifact output: Deduplication marker files: `MARKER="${STATE_DIR}/${SESSION_ID}-${MARKER_NAME}.loaded"` + `touch
Audit Notes: 🔵 Blue: Informational only. The repository's executable surface consists solely of 9 bash scripts under hooks/ and build.sh. Hooks are executed by the plugin host at SessionStart and around MCP tool invocations to read stdin, write deduplication markers under ${TMPDIR}/n8n-mcp-skills-state, create an empty cache directory, and output static reminder JSON—without network access, credential reads, or touching ~/.claude files, and all fail open (exit 0 on error). Tool functionality relies on the external n8n-mcp MCP server (hosted endpoint https://api.n8n-mcp.com/mcp), and credentials (N8N_API_URL/N8N_API_KEY) are maintained by the MCP server; repository scripts never access them, falling within the trust boundary between host and MCP server rather than this skill. Classified as Blue based on 'local tools/CLI and local filesystem operations only, no outbound network access, no credentials'. Two points to note: installing the plugin injects router markdown into every session (intended design, though without integrity verification); the self-hosting skill instructs the agent to run deployment commands on remote hosts via ssh/docker (requires explicit user intent).

5Second-Pass Verification

  • [ok] skill.path = skills/using-n8n-mcp-skills — 重读 skills/ 目录：15 个子目录、该层无 SKILL.md；glob **/SKILL.md 得 15 个且全部位于 skills/<name>/SKILL.md。重读 hooks/session-start.sh 确认 META_SKILL 指向 using-n8n-mcp-skills，重读 .claude-plugin/marketplace.json 确认同一 bundle 枚举 15 条路径——router 即入口，选它作路径。
  • [ok] official_desc 逐字 — 重读 skills/using-n8n-mcp-skills/SKILL.md L2-4：description 为单行长文本，正文 L6 才是标题，说明未使用 YAML 折行，逐字转录无拼接误差。
  • [ok] external_deps：MCP 端点与两种接入方式 — 重读 mcp.json 全 9 行（streamable-http + https://api.n8n-mcp.com/mcp）、.mcp.json.example（npx + MCP_MODE=stdio + N8N_API_URL/N8N_API_KEY 占位）、SKILL.md 的 Hosted/Self-hosted 两段。端点、命令、变量名逐字一致。
  • [ok] security：hooks 是否联网 — 对 hooks/ 全目录独立 grep（curl|wget|nc |/dev/tcp|eval |base64|N8N_API|API_KEY|TOKEN|\.env）：仅命中提醒文本里的 tokens 字样。逐行重读 _emit.sh 与 session-start.sh 确认无子进程下载、无网络命令。结论不变：hooks 不联网。
  • [ok] security：hooks 读取的环境变量集合 — 重读 session-start.sh（CLAUDE_PLUGIN_ROOT、HOME、TMPDIR、stdin）与 _emit.sh（TMPDIR、stdin，无 jq 时 python3 兜底）；全仓 grep keychain 零命中，`\.claude` 仅命中 .gitignore 与文档安装指令。
  • [ok] security：写文件路径 — 重读 _emit.sh 的 STATE_DIR/MARKER/touch、get-node.sh 的同名目录、session-start.sh 的 CACHE_DIR + mkdir 与 rm -f 清理：写路径只有 ${TMPDIR:-/tmp}/n8n-mcp-skills-state/*.loaded（约定前缀）与 ~/.cache/n8n-mcp-skills（仅建目录），另有 build.sh 的 dist/。
  • [ok] 去重策略：通用一次 vs 节点级每次 — 重读 _emit.sh（有 marker 即 exit 0）与 get-node.sh（通用提醒走 has_marker 去重，高危节点分支无 marker 检查）。题面所述『节点级提醒不去重』在源码注释与逻辑上均成立。
  • [discrepancy] 披露 vs 实际：评估套件能否运行 — README 写 `npm test` 与 `claude-code --skill n8n-expression-syntax "Test webhook data access"`，但全仓无 package.json、无测试框架配置、无 CI workflow；evaluations/ 下 57 个 JSON 只有 id/skills/query/expected_behavior 字段，无 runner；docs/DEVELOPMENT.md 自述 `*Coming soon: Evaluation framework*`。README 的注释行也写着 `# Run evaluations (if testing framework available)`——即该命令在仓内无法兑现，评估实为人工对照流程。

6Verdict & Scenarios

  • Engineers a solution for the common agent problem of 'forgotten skills': uses hooks to inject routing prompts at session start and tool invocation rather than relying solely on descriptions
  • Security discipline is integrated into workflows rather than mere prompts: secrets must use the n8n credential system, passing validation ≠ correctness, and current instance confirmation is required before writing credentials in multi-instance setups
  • Well-structured progressive disclosure: short primary files with externalized details allow on-demand loading by models, keeping token costs contained
  • High supply-chain transparency: explicitly declares hook code origins, scope of modifications, and licenses
  • Restrained reliability engineering: all hooks fail open, silently allowing tool calls to proceed if dependencies are missing or errors occur, never blocking user workflow
    • Best for: Ideal for individuals and teams currently using (or adopting) n8n + n8n-mcp, especially in workflows slowed down by subtle pitfalls like n8n node configuration nuances, expression syntax, and Merge node multi-input wiring. Also valuable for skill authors exploring how to use hooks for timely automatic skill loading—the SessionStart + PreToolUse enforcement layer here serves as a rare and complete reference implementation. For users running self-hosted n8n, the self-hosting skill provides an executable deployment playbook covering SSH + Compose + Caddy.
    Not for: Not suitable for environments not using n8n-mcp (or an equivalent MCP server)—without underlying tools, the skill layer reduces to static advice, significantly diminishing its value. Not suitable for users expecting skills alone to guarantee security: write-operation safeguards rely on prompt discipline, whereas true enforcement depends on the MCP server and n8n-side permissions. Not suitable for procurement or audit processes requiring reproducible evaluation benchmarks (the repo includes no test runner, CI, or pass-rate metrics). Also not suitable for users expecting automatic loading outside Claude Code or Codex clients, where the hook layer is unsupported.
    Install Agent-Ready
    ① Verified Mirror 2026-09-15
    Option A · Direct DownloadDownload n8n-workflow-skills.tar.gz
    sha256: 9b92af0c1951282e…
    Option B · Copy Guide for Agent
    install.json
    Agents automatically download and verify mirrors from this JSON guide.
    ② Upstream GitHub
    GitHub Repo ↗
    Pinned to commit 2df0f18cb5.