n8n-skills 实战指南：用 Claude Code 与 n8n-mcp 构建生产级 n8n 工作流

导读

n8n-skills 是一套面向 Claude Code 等 AI 编程助手的专家技能包（skillset），其目标是用 n8n-mcp MCP 服务器构建"零缺陷"（flawless）的 n8n 工作流。本指南以仓库根 README.md 为主线，完整剖析其中 14 个互补技能的能力边界、始终在线的 Router 技能与 hooks 强制执行层的工作原理，并给出从安装、自动激活到跨技能协同构建工作流的完整实操路径。读完本文，你将掌握如何让 AI 助手正确书写 n8n 表达式、高效调用 n8n-mcp 工具、解读校验错误、规避节点配置陷阱，并亲手部署运行这些工作流的自托管 n8n。

---

一、为什么需要这套技能：程序化构建 n8n 工作流的四大痛点

用程序化方式构建 n8n 工作流并不容易。仓库 README 明确总结了常见的四大失败原因：

• MCP 工具使用错误或低效：工具名、参数形态、节点 typeVersion 随版本漂移，凭记忆调用极易踩坑；
• 陷入校验错误循环：校验报错看不懂、修了又报，无法收敛；
• 不知道该用哪种工作流模式：面对需求时在架构选型上反复横跳；
• 节点及其依赖配置错误：忽略 displayOptions 驱动的属性依赖，配置了看不见的字段或漏配必填字段。

n8n-skills 通过给 AI 助手注入"专家知识"来解决这些问题：教会它正确的 {{ }} 表达式语法、n8n-mcp 工具的高效用法、来自真实世界的工作流模式、校验错误的解读与修复方法，以及**面向操作（operation-aware）**的节点配置规则。

从架构上看（详见 CLAUDE.md 的项目概述），这套方案由三层组成：

层次	组件	职责
数据层	n8n-mcp MCP 服务器	提供 800+ 节点数据、校验、模板、工作流管理能力
知识层	Claude Skills	提供"如何使用 MCP 工具"的专家指引
组合	两者协同	实现带渐进式披露（progressive disclosure）的专家级工作流构建

---

二、技能包的构成：14 个互补技能 + 路由技能 + hooks 强制执行层

仓库包含 14 个互补的 Claude Code 技能、一个始终在线的路由技能（Router skill）以及一个 hooks 强制执行层。每个技能是一个自包含目录，入口是 SKILL.md，可附带若干参考文档。技能目录分布在 skills/ 下，例如 n8n-expression-syntax/、n8n-mcp-tools-expert/、n8n-workflow-patterns/ 等。

下面逐一说明每个技能的适用场景与核心知识。

1. n8n Expression Syntax（表达式语法）

何时激活：书写表达式、使用 {{ }} 语法、访问 $json/$node 变量、排查表达式错误时。

核心内容：

• 核心变量：$json、$node、$now、$env；
• 关键陷阱（Critical gotcha）：Webhook 数据位于 $json.body 之下，而不是 $json 顶层——这是最常见的表达式错误来源；
• 常见错误目录（common mistakes catalog）及其修复方法；
• 什么时候不该用表达式：Code 节点内应使用直接访问（如 const email = $json.body.email;），而不是 {{ }} 包裹。

从 docs/USAGE.md 的示例响应看，正确写法是 {{$json.body.email}}，而裸写 $json.body.email 是错误的。仓库中的 Router 技能还补充了更细的规则：分支较多的工作流中，$('Node').item.json.x 优于裸用 $json.x；日期计算优先用 Luxon 内联表达式（如 {{ DateTime.fromISO($('Source').item.json.created_at).toFormat('yyyy-MM-dd') }}），而不是单独引入 DateTime 节点。

2. n8n MCP Tools Expert（MCP 工具专家，最高优先级）

何时激活：搜索节点、校验配置、访问模板、管理工作流时。

核心内容：

• 工具选择指南：明确"哪个任务用哪个工具"；
• nodeType 格式差异：nodes-base.*（短格式）与 n8n-nodes-base.*（长格式）的使用场景不同；
• 校验画像（Validation profiles）：minimal / runtime / ai-friendly / strict；
• 智能参数：例如 IF 节点用 branch="true"；
• **自动净化系统（Auto-sanitization）**的原理说明。

Router 技能 skills/using-n8n-mcp-skills/SKILL.md 把 nodeType 格式陷阱称为"常见且静默的错误"：get_node/validate_node 接受短格式（nodes-base.set），而 validate_workflow/n8n_create_workflow 中的工作流 JSON 必须用长格式（n8n-nodes-base.set），混用即错。

3. n8n Workflow Patterns（工作流模式）

何时激活：创建工作流、连接节点、设计自动化时。

核心内容：

• 5 种经过验证的架构模式：webhook 处理、HTTP API、数据库、AI、定时任务（scheduled）；
• 工作流创建清单（checklist）：搜索节点 → 获取节点配置 → 创建工作流结构 → 添加数据映射（表达式）→ 校验工作流 → 用样本数据测试；
• 来自 2,653+ 个真实 n8n 模板的实战示例；
• 节点连接最佳实践；
• 模式选择指南。

4. n8n Validation Expert（校验专家）

何时激活：校验失败、调试工作流错误、处理误报（false positives）时。

核心内容：

• 校验循环工作流（validation loop workflow）；
• 真实错误目录（real error catalog）；
• 自动净化行为说明——可以修复二元/一元运算符结构、IF/Switch 节点缺失的元数据，但无法修复断开的连接、分支数量不匹配；
• 误报处理指南；
• 针对不同阶段选择校验画像（profile）。

5. n8n Node Configuration（节点配置）

何时激活：配置节点、理解属性依赖、搭建 AI 工作流时。

核心内容：

• 属性依赖规则：例如 sendBody → contentType 的级联——设置 sendBody=true 后才显示 contentType，设 contentType="json" 后才显示 specifyBody，设 specifyBody="json" 后才显示 jsonBody；
• 操作特定要求（operation-specific requirements）；
• AI 连接类型：AI Agent 工作流需要 8 种连接类型（ai_languageModel、ai_tool、ai_memory、ai_outputParser、ai_embedding、ai_vectorStore 等）；
• 常见配置模式。

6. n8n Code JavaScript（JavaScript 代码节点）

何时激活：在 Code 节点中写 JavaScript、排查 Code 节点错误、用 this.helpers（即 $helpers 全局对象）发 HTTP 请求、处理日期时。

核心内容：

• 数据访问模式：$input.all()、$input.first()、$input.item；
• 关键陷阱：Webhook 数据在 $json.body 下；
• 正确的返回格式：[{json: {...}}]；
• 内置函数说明：this.helpers.httpRequest()（裸 $helpers 全局对象在 task-runner 沙箱中未定义；非平凡或需认证的调用应优先用 HTTP Request 节点）、DateTime、$jmespath()；
• Top 5 错误模式及解决方案，覆盖 62%+ 的失败场景；
• 10 个经生产验证的模式。

7. n8n Code Python（Python 代码节点）

何时激活：在 Code 节点中写 Python、需要了解 Python 能力边界、使用标准库时。

核心内容：

• 重要提醒：95% 的用例请使用 JavaScript；
• 原生 Python（n8n 2.x）只提供 _items / _item 与 dict 访问——旧的 Pyodide 辅助变量（_input、_json、_node、_now）已不存在；
• 关键限制：除非实例在允许清单（allowlist）中放行，否则每次 import 都会被拦截（n8n Cloud 上默认全拦截）；
• 沙箱限制：不能用 class、type()、getattr、dunder 方法；作用域用 nonlocal 而非 global；返回形态需验证；
• 12 个免 import 模式，均已在真实实例上验证。

8. n8n Code Tool（AI Agent 可调用的自定义代码工具）

何时激活：构建挂载在 AI Agent 上的自定义代码工具（@n8n/n8n-nodes-langchain.toolCode）、排查 "Wrong output type returned" 或 "No execution data available" 错误、在非结构化 query 解析与 specifyInputSchema 之间做选择时。

核心内容：

• 关键区分：Code Tool ≠ Code 节点（不同节点类型、不同返回格式、不同沙箱）；
• 返回格式是一个字符串（结构化输出请用 JSON.stringify()），而不是 [{json:{...}}]；
• 输入绑定：query（JS）/ _query（Python）——$fromAI() 在这里不可用；
• 非结构化 vs 结构化输入模式（specifyInputSchema → DynamicStructuredTool）；
• 沙箱限制：无 $input、$helpers、$json、$getWorkflowStaticData，且调用之间无状态保持；
• 三个签名错误字符串的成因与修复；
• Code Tool vs toolWorkflow vs HTTP Request Tool 的选型时机。

9. n8n Error Handling（错误处理）

何时激活：构建 webhook/API 或无人值守工作流、接线错误输出、设置重试、设计 4xx/5xx 响应、排查静默失败时。

核心内容：

• 逐节点错误输出：两步走——设置 onError: continueErrorOutput + 接线 main[1] 错误分支；
• retryOnFail 自愈机制，应对不稳定的网络调用；
• 4xx/5xx 响应形态映射（以及 responseCode 默认值为 200 的陷阱）；
• 面向无人值守运行的 Error Trigger 工作流。

10. n8n Binary & Data（二进制与数据）

何时激活：处理文件、图片、PDF、附件、上传/下载、视觉输入，或将文件传入/传出 AI Agent 工具时。

核心内容：

• $binary vs $json——文件内容永远不放在 $json 中；
• 用 Merge 节点在 JSON 变换中保持二进制数据存活；
• Agent 工具二进制边界：先预置到存储，只传 key/URL；
• 在聊天界面展示图片需要 CDN/URL 要求。

11. n8n Sub-workflows（子工作流）

何时激活：抽取共享逻辑、构建多步或复用工作流、任何超过约 10 个节点的工作流时。

核心内容：

• Execute Workflow Trigger 的 "Define Below" 类型化输入（非 passthrough）；
• mode: all vs each，以及 waitForSubWorkflow（唯一的真正并行化手段）；
• 动词前缀命名利于发现（MCP 无法按 tag 过滤）；
• 无状态 vs 有状态设计；按输入形态拆分的 N+1 模式。

12. n8n AI Agents（AI Agent 设计）

何时激活：构建任何 @n8n/n8n-nodes-langchain.* 节点——AI Agent、LLM Chain、Text Classifier——或处理工具调用、$fromAI、记忆、结构化输出、RAG、聊天机器人时。

核心内容：

• Agent vs LLM Chain vs Text Classifier 的区别；model / memory / tools / outputParser 四个插槽；
• 工具名与描述本身就是提示词；$fromAI 参数解剖；
• 结构化输出 + autoFix；memory + sessionId；人工审批（human-in-the-loop）；
• 聊天机器人"壳 + 核心 + 子 Agent"拓扑与防循环过滤。

13. n8n Multi-Instance（多实例定位）

何时激活：n8n_instances 工具可用、用户提到多个实例/环境（生产 vs 预发、多个客户），或某次调用返回意外的 NOT_FOUND 或错误/空数据时。

核心内容：

• n8n_instances 的 list/switch 形态与真实错误信封（UNKNOWN_INSTANCE、MULTI_INSTANCE_DISABLED 等）；
• 独立回合中切换；每次会话的目标绑定在重连/部署后依然有效；
• 写入凭证前先确认 current——服务器只在歧义情况（INSTANCE_AMBIGUOUS）下 fail-close；显式但错误的 switch 仍会静默写入密钥；
• 从误路由中恢复（NOT_FOUND 更可能是"切错了实例"而非"被删除"），以及在实例间复制对象。

14. n8n Self-Hosting（自托管部署 / 运维）

何时激活：在自己的服务器/VPS（Hetzner、DigitalOcean、EC2、裸机）上自托管、安装或部署 n8n——单机或队列模式——或更新、备份、加固它时。不适用于 n8n Cloud，也不用于构建工作流。

核心内容：

• Docker Compose 置于 Caddy 之后，自动 HTTPS；第一步先询问 single vs queue 模式；
• 单机（SQLite）与队列（main + Redis + Postgres + workers）两种模板，模板本身不含密钥、不含域名；
• 在机器上现场生成全新密钥；安全默认值（显式加密密钥、不发布内部端口、关闭遥测、封锁 env 访问、执行记录修剪）；
• DNS/端口预检、端到端验证（证书 + 可达性）、Day-2 运维（更新 / 备份 / 恢复）。

这是本包唯一一个部署类技能；它由自身描述触发，不属于工作流构建的 Router/hooks 流程。部署模板可直接在 skills/n8n-self-hosting/assets/ 下查看（含 docker-compose.single.yml、docker-compose.queue.yml、Caddyfile、init-data.sh）。

---

三、强制执行层：hooks + router 如何在决策时刻推送正确指导

仅仅提供技能还不够——仓库还内置了一个始终在线（always-on）的强制执行层，确保正确的指导在决策时刻出现，而不是等用户碰巧问到。这部分配置在 hooks/hooks.json 中，由三类 hook 组成。

Router 技能（using-n8n-mcp-skills）

由 SessionStart hook（startup|resume|clear|compact 四种匹配）在每次会话启动时把 skills/using-n8n-mcp-skills/SKILL.md 注入上下文（additionalContext）。其实现细节见 hooks/session-start.sh：

• 它把 Router 技能正文整体注入，并给出 hookSpecificOutput.hookEventName = "SessionStart"；
• 在 clear/compact 时重新触发，从而在上下文压缩后依然存活；
• 同时在 clear/compact 时清空本会话的 PreToolUse 标记文件（${TMPDIR:-/tmp}/n8n-mcp-skills-state/${SESSION_ID}-*.loaded），确保被压缩后节点级警告能再次触发；
• 静默失败、永不阻塞会话启动。

Router 技能本身"不是参考手册，而是路由表"：它列出每个技能负责的规则、给出 n8n-mcp 全部工具的速查知识，并声明三条无条件遵守（non-negotiables）的规则：

1. 任何 n8n 动作前先调用相关技能——不只是 MCP 调用前；PreToolUse hooks 只在 Claude Code 插件安装中生效，其他客户端（Claude.ai 上传、Codex、Cursor、Copilot 等）没有任何提醒，责任完全在模型自身；
2. 激活前必须"校验 + 验证"——激活前运行 validate_workflow（或按 id 用 n8n_validate_workflow），每次创建/更新后用 n8n_get_workflow 检查 connections 对象。校验通过只代表 JSON 结构良好，不代表工作流正确；绿色测试运行同样不能证明正确性（{{ }} 内的 JS 错误会静默解析为 null，Filter 条件坏了会丢弃所有条目却显示成功）；
3. 密钥永不进入文本字段——token、API key、密码一律走 n8n 凭证系统；无原生节点时用 HTTP Request 节点配官方凭证类型；用 Set 节点持有 token 再以 {{ $json.token }} 引用，是"加了步骤的泄露"。

Router 还给出了"强默认值"（strong defaults）：Code 节点是最后手段（表达式 → Edit Fields 内的箭头函数 → Code 节点）；只喂 0–1 个下游消费者的 Set 节点几乎总是错的；逐条目迭代是自动的，别为"让它循环"而加 Loop Over Items 节点；永远从实时 schema 配置（get_node）而非记忆。

PreToolUse hooks：调用前拦截提醒

按 hooks/hooks.json 的 matcher 正则，hook 在以下工具调用前触发：

MCP 工具（正则匹配）	触发脚本
get_node	hooks/pre-tool-use/get-node.sh
n8n_create_workflow	hooks/pre-tool-use/create-workflow.sh
n8n_update_partial_workflow / n8n_update_full_workflow	hooks/pre-tool-use/update-workflow.sh
validate_workflow / n8n_validate_workflow	hooks/pre-tool-use/validate-workflow.sh
n8n_test_workflow	hooks/pre-tool-use/test-workflow.sh
n8n_instances	hooks/pre-tool-use/instances.sh
n8n_manage_credentials	hooks/pre-tool-use/manage-credentials.sh

其中 get-node.sh 最具代表性，它做两件事：

• 通用节点配置提醒：每个会话首次 get_node 时触发一次（用 marker 文件去重），提醒先调用 n8n-node-configuration 技能、配置是 operation-aware 的、别凭记忆假设参数名；
• 高风险节点专属提醒（每次查询都触发，不去重）：对 Set、Code、Merge、Loop Over Items（splitInBatches）、DateTime、Data Table、AI Agent 七类节点注入针对性警告。理由是"重复查询同一节点类型，几乎总是模型在重新考虑另一个反模式实例"，一次会话去重会漏掉后续所有决策。典型警告内容：
  • Set 节点：若它唯一作用是给下一个节点映射字段，请删掉并把表达式直接写进下游节点的参数槽；只有 2+ 下游消费者引用同一派生值、或作为子工作流最终返回形态节点时才值得保留；
  • Merge 节点：默认只有 2 个输入，3+ 源汇聚时必须显式设置 numberOfInputs，否则第三路会在运行时被静默丢弃；输入索引配对易接反，off-by-one 会把错误分支的数据无报错地传下去；
  • Loop Over Items：先问是否真需要（默认逐条目迭代即可）；输出 0 是 DONE（结束时触发一次），输出 1 是 LOOP（每批触发）——极易接反；
  • DateTime 节点：日期运算/格式化/解析通常用 Luxon 内联即可（{{ DateTime.now().minus({ days: 7 }).toISO() }}），只有内联表达式确实表达不了时才用节点；
  • Data Table 节点：id/createdAt/updatedAt 是系统管理列，别声明；列类型只有 string/number/boolean/date 四类，嵌套数据用 string 列 + JSON.stringify()/JSON.parse()；直接在 Insert 节点的列槽中映射字段，不要在前面加 Set 节点"整形"；
  • AI Agent 节点：工具名和描述是模型路由所依据的提示词的一部分，通用描述会劣化工具选择。

一次性的生命周期/多实例/凭证提醒（create、update、validate、test、n8n_instances、n8n_manage_credentials）则由共享助手 hooks/pre-tool-use/_emit.sh 实现：读入 session_id、用 <session>-<marker>.loaded 标记文件做 per-session 去重、先 touch 再编码（防止下游 JSON 编码失败导致重复触发）、始终退出 0 静默失败。

PostToolUse hook：校验之后的路由

validate_workflow 调用结束后，hooks/post-tool-use/validate-workflow.sh 从工具入参的 workflow JSON 中解析节点类型（长格式，如 n8n-nodes-base.set），据此路由到"拥有剩余风险"的技能，并反复强调：校验通过是必要条件，不是充分条件。

该脚本可检测 Set、Code、Merge、Loop、DateTime、Data Table、Execute Workflow Trigger、Webhook、HTTP Request、Respond to Webhook、Schedule、LangChain Agent、Chat Trigger 以及 $json. 引用，组合出针对性的技能建议（例如：检测到 Webhook/HTTP/Respond 会建议认证表面用凭证系统；节点数 > 6 会建议架构评审；检测到 Agent 会建议 n8n-agents）。若无节点 JSON 可用（按 id 校验或空载荷），则退化为通用门控：非平凡工作流激活前运行反模式扫描。

优雅降级与 fail-open 设计

hooks 只在 Claude Code / Codex 插件安装中运行。在 Claude.ai（单个技能上传）上，技能仍按描述自动激活——技能包优雅降级，只是缺少了主动提醒。每个 hook 都 fail-open，绝不阻塞任何工具调用；没有 jq 时直接跳过注入而不是输出畸形 JSON。

---

四、安装指南

前置条件

1. n8n-mcp MCP 服务器已安装并配置。仓库根目录 mcp.json 给出了托管版配置（streamable-http，https://api.n8n-mcp.com/mcp）；自托管场景需要在 .mcp.json 中配置 N8N_API_URL 与 N8N_API_KEY，完整示例见 docs/INSTALLATION.md：

{
  "mcpServers": {
    "n8n-mcp": {
      "command": "npx",
      "args": ["n8n-mcp"],
      "env": {
        "MCP_MODE": "stdio",
        "LOG_LEVEL": "error",
        "DISABLE_CONSOLE_OUTPUT": "true",
        "N8N_API_URL": "https://your-n8n-instance.com",
        "N8N_API_KEY": "your-api-key-here"
      }
    }
  }
}

2. Claude Code、Claude.ai 或 Claude API 访问权限；
3. .mcp.json 已配置 n8n-mcp 服务器。

说明：Router 技能对两种部署形态做了区分——托管版（首次使用通过客户端的 OAuth 提示登录，再在 dashboard 中连接 n8n 实例，无需环境变量和粘贴 API key）与自托管版（npx n8n-mcp 或 Docker，服务器环境需导出 N8N_API_URL 和 N8N_API_KEY）。n8n_health_check 可确认连接并返回解析到的实例。

Claude Code 的三种安装方式

方式一：插件安装（推荐）

# 直接作为 Claude Code 插件安装
/plugin install czlonkowski/n8n-skills

方式二：通过 Marketplace

# 添加为 marketplace，然后浏览并安装
/plugin marketplace add czlonkowski/n8n-skills

# 然后浏览可用插件
/plugin install
# 从列表中选择 "n8n-mcp-skills"

方式三：手动安装

# 1. 克隆本仓库
git clone https://gitcode.com/gh_mirrors/n8/n8n-skills.git

# 2. 将技能复制到 Claude Code 技能目录
cp -r n8n-skills/skills/* ~/.claude/skills/

# 3. 重载 Claude Code，技能将自动激活

插件元数据见 plugin.json：插件名为 n8n-mcp-skills，版本 1.35.0，遵循 Agent Plugins schema（agent-plugins.org/schemas/1.0.0），MIT 许可。

Claude.ai 与 API / SDK

• Claude.ai：从 skills/ 下载单个技能文件夹，逐个打包 zip（也可直接使用最新 release 中附带的预构建 zip），然后通过 Settings → Capabilities → Skills 上传。打包命令示例：

cd skills
zip -r n8n-expression-syntax.zip n8n-expression-syntax/
zip -r n8n-mcp-tools-expert.zip n8n-mcp-tools-expert/
zip -r n8n-workflow-patterns.zip n8n-workflow-patterns/

• API / SDK：若通过 Claude API 构建应用，可编写 loadSkillsFromDirectory 函数读取每个技能目录下的 SKILL.md 并作为 skills 参数传入请求；由于 Agent Skills 是开放标准，任何支持 SKILL.md 格式的 Agent（如 Google Antigravity 等）都可以直接复用这些技能目录，无需转换。

完整安装、验证与故障排查（技能不激活、MCP 工具不可用、API 工具缺失、权限问题、卸载与更新、自定义技能目录、选择性安装）请参阅 docs/INSTALLATION.md。

---

五、使用方式：技能如何自动激活与协同

技能在检测到相关查询时自动激活，无需手动调用。典型触发示例：

"How do I write n8n expressions?"
→ 激活: n8n Expression Syntax

"Find me a Slack node"
→ 激活: n8n MCP Tools Expert

"Build a webhook workflow"
→ 激活: n8n Workflow Patterns

"Why is validation failing?"
→ 激活: n8n Validation Expert

"How do I configure the HTTP Request node?"
→ 激活: n8n Node Configuration

"How do I access webhook data in a Code node?"
→ 激活: n8n Code JavaScript

"Can I use pandas in Python Code node?"
→ 激活: n8n Code Python

"Why does my Code Tool throw 'Wrong output type returned'?"
→ 激活: n8n Code Tool

技能如何协同工作

以一句查询为例："Build and validate a webhook to Slack workflow"（构建并校验一个 webhook 到 Slack 的工作流）。六个技能将按序自动接力：

1. n8n Workflow Patterns 识别出 webhook 处理模式；
2. n8n MCP Tools Expert 用 search_nodes 搜索 webhook 与 Slack 节点，再 get_node 取细节；
3. n8n Node Configuration 指导节点设置（Webhook 的 path、httpMethod；Slack 的 resource、operation、channel）；
4. n8n Code JavaScript 帮助用正确的 .body 访问处理 webhook 数据；
5. n8n Expression Syntax 提供其他节点中的数据映射写法（{{$json.body.message}}），并提醒 webhook 数据在 .body 之下；
6. n8n Validation Expert 校验最终工作流。

关于工具的两层结构（Router 技能原话）：文档与校验工具离线可用、始终存在（tools_documentation、search_nodes、get_node、validate_node、search_templates/get_template）；而 n8n_* 管理工具需要连接在线 n8n 实例才会出现。如果它们缺失，不是坏了、也不需要重试——应直接说明，并引导用户修正其安装方式。

推荐的标准化协议顺序（protocol in order）为：

1. 从技能索引中识别匹配技能，并在首次 MCP 调用前调用它；
2. 不确定时每会话快速浏览一次 tools_documentation 刷新工具面；
3. 配置任何节点前先 get_node——读实时 schema，不要假设；
4. 构建/编辑后，激活前 validate_workflow，之后 n8n_get_workflow 检查 connections；
5. 主动上报发现的漂移（缺失的工具、变化的参数、偏离的行为）。

更多使用细节、常见用例（快速搜索节点、修复表达式错误、解读校验错误、构建 AI 工作流）、最佳实践（描述更具体、追问后续问题、主动要求校验、利用跨技能知识、参考真实模板）与工具可用性清单见 docs/USAGE.md。

---

六、测试与质量保障

每个技能都附带 3+ 条评测用例（evaluations） 用于质量保障，评测场景存放在 evaluations/ 下，按技能主题分类（如 expression-syntax/、code-javascript/、code-python/、validation-expert/、multi-instance/、self-hosting/ 等），每个主题含 4–6 条 JSON 格式的评测样本，覆盖真实使用中会踩到的坑（如 webhook body 陷阱、返回格式错误、module 导入错误、表达式缺失花括号、密钥卫生等）。

运行评测：

# 运行评测（若测试框架可用）
npm test

# 或手动用 Claude 测试
claude-code --skill n8n-expression-syntax "Test webhook data access"

在非插件/无测试框架环境下，也可直接用 Claude 以自然语言驱动技能验证（如向 Claude.ai 提问 "How do I access webhook data in n8n expressions?"，期望触发 Expression Syntax 技能并给出 $json.body 的答案）。

---

七、贡献与开发方法

欢迎贡献，规范见 docs/DEVELOPMENT.md。README 明确了五项开发原则：

1. Evaluation-First（评测优先）：先写测试场景，再实现技能；
2. MCP-Informed（以 MCP 为准）：真实测试工具，记录真实响应（可参考 docs/MCP_TESTING_LOG.md 中的真实工具响应记录）；
3. Iterative（迭代）：对照评测反复测试，直到 100% 通过；
4. Concise（简洁）：每个 SKILL.md 保持在 500 行以内；
5. Real Examples（真实示例）：所有示例来自真实模板/工具。

新增技能的流程：在 skills/ 下创建目录 → 写带 frontmatter 的 SKILL.md → 按需补充参考文件 → 在 evaluations/ 下创建 3+ 条评测 → 提交前充分测试。

---

八、许可、致谢与相关项目

本仓库采用 MIT 许可，详见 LICENSE。hooks 强制执行层改编自官方 n8n Skills 项目（Apache-2.0），并针对 n8n-mcp 重新定向、用自己的语言重写，归属声明见 NOTICES（同时保留在脚本文件头部注释与 CLAUDE.md 中，且明确要求不写入面向 Agent 的 SKILL.md 内容）。技能包由 Romuald Członkowski 构思，属于 n8n-mcp 项目的一部分。

仓库包含能力速览：

• 14 个协同工作的互补技能；
• 525+ 个受支持的 n8n 节点；
• 2,653+ 个可供参考的工作流模板；
• 10 个经生产验证的 Code 节点模式；
• 完整的错误目录与故障排查指南。

---

九、结语：从"会写工作流"到"写对工作流"

n8n-skills 的价值不在于让 AI 助手"能写出 n8n 工作流"，而在于让它写出在激活后不静默出错的工作流。表达式用对 $json.body、Code 节点返回 [{json:{...}}]、Code Tool 返回字符串、Merge 显式声明输入数、激活前校验并核查 connections、密钥永远走凭证系统——这些正是 README 与 Router 技能反复强调的"必要但不充分"的门控。配合 hooks 强制执行层，正确指导会在每次 get_node、每次 validate_workflow 的决策瞬间自动浮现。对希望在 Claude Code 生态中稳定构建 n8n 自动化的开发者而言，这套技能包提供了从表达式语法到自托管部署的完整知识闭环。