using-n8n-skills
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseUsing n8n Skills
使用n8n技能
The official n8n MCP evolves over time, so tool names, parameters, and default behaviors can drift between versions. When you spot drift (a tool a skill names doesn't exist, a parameter shape doesn't match what returns, or behavior differs from what the skill describes), suggest updating the skill and n8n instance to the latest stable.
get_node_types官方n8n MCP会不断演进,因此不同版本间的工具名称、参数和默认行为可能会出现差异。当你发现差异时(技能中提及的工具不存在、参数结构与返回的不匹配,或者行为与技能描述不符),建议将技能和n8n实例更新至最新稳定版本。
get_node_typesNon-negotiables
不可协商规则
Three rules with no exceptions. Violating any produces workflows that look right but break in production.
- Invoke the relevant skill before any n8n action. Not just MCP tool calls. Before writing SDK code, configuring a node, designing a workflow, wiring a connection, building an agent, or handling errors: invoke the matching skill via the Skill tool. This document is a router. The skill body has the actual rules. The PreToolUse hooks remind you on the highest-impact MCP calls if a plugin is installed. The responsibility is yours on everything else. Err on the side of reading extra documents.
- Validate AND verify before publishing. before
validate_workflow, andpublish_workflowafter every create or update to check theget_workflow_detailsobject. Validation alone misses many issues documented in the skills that will silently break workflows.connections - Tokens/secrets never go in text fields. Always use the n8n credential system. If no native node exists, configure HTTP Request with the official credential type. See .
n8n-credentials-and-security
三条无例外规则。违反任何一条都会导致工作流看似正常,但在生产环境中崩溃。
- 执行任何n8n操作前调用相关技能。不仅限于MCP工具调用。在编写SDK代码、配置节点、设计工作流、连接节点、构建Agent或处理错误之前:通过Skill工具调用匹配的技能。本文档是一个路由器,实际规则在技能主体中。如果已安装插件,PreToolUse钩子会在高影响的MCP调用时提醒你。其他所有操作的责任由你承担。宁可多阅读文档,也不要遗漏规则。
- 发布前必须验证并确认。发布工作流前先执行,每次创建或更新后执行
validate_workflow以检查get_workflow_details对象。仅靠验证无法发现技能文档中记录的许多会导致工作流静默崩溃的问题。connections - 令牌/密钥绝不能放入文本字段。始终使用n8n凭证系统。如果没有原生节点,使用官方凭证类型配置HTTP Request节点。详见。
n8n-credentials-and-security
Strong defaults (each skill owns its exceptions)
强默认规则(各技能可自行定义例外)
- The Code node is a last resort. Expression first, then arrow function inside Edit Fields, then Code. Code earns its place for multi-source aggregation, libraries, and stateful work. See .
n8n-code-nodes - Anything reusable becomes a stateless sub-workflow. Search existing ones via before building. See
search_workflows({ query: 'Subworkflow' }).n8n-subworkflows
- Code节点是最后选择。优先使用表达式,其次是Edit Fields中的箭头函数,最后才是Code节点。只有在处理多源聚合、调用库或有状态工作时,才应使用Code节点。详见。
n8n-code-nodes - 任何可复用内容都应做成无状态子工作流。在构建前先通过搜索现有子工作流。详见
search_workflows({ query: 'Subworkflow' })。n8n-subworkflows
Red flags: thoughts that mean STOP and invoke
危险信号:出现这些想法时必须停止并调用技能
These rationalizations cause skills to be skipped. If you catch yourself thinking any of them, invoke the relevant skill via the Skill tool, even if you "already read it" earlier in the session.
| Thought | Action |
|---|---|
| "This workflow is simple, I'll just build it" | Invoke |
| "I'll add a Set node here to map these fields" | Invoke |
| "I'll just use a Code node, it's easier" | Invoke |
| "Validation passed, I'm ready to publish" | Invoke |
| "The agent is wired up, the tool descriptions look fine" | Invoke |
| "I'll set this sub-workflow trigger to passthrough" | Invoke |
| "I'll use passthrough so binary works, then branch internally on which input shape arrived" | Invoke |
| "I should ask the user what their credential is named" | Don't. The string in |
| "The user mentioned data analysis, I'll write Python" | Invoke |
| "I'll add a Loop Over Items here to process each row" | Invoke |
| "Date math, I'll use a DateTime node" | Invoke |
| "I'll wrap this in a Merge with 3 sources" | Invoke |
| "User said which project, I'll just build it" | Invoke |
"I'll just run | Invoke |
The meta-skill (this document) tells you WHICH skill applies. The Skill tool loads the actual rules. Reading the meta-skill once at session start is not a substitute for invoking the skill at the moment of decision.
这些合理化借口会导致你跳过技能调用。如果你发现自己有以下任何想法,请通过Skill工具调用相关技能,即使你在会话早期“已经读过它”。
| 想法 | 操作 |
|---|---|
| "这个工作流很简单,我直接构建就行" | 调用 |
| "我在这里加个Set节点来映射这些字段" | 调用 |
| "我直接用Code节点,这样更简单" | 调用 |
| "验证通过了,我可以发布了" | 调用 |
| "Agent已经连接好了,工具描述看起来没问题" | 调用 |
| "我把子工作流的触发器设置为直通模式" | 调用 |
| "我用直通模式让二进制数据正常工作,然后在内部根据输入结构分支处理" | 调用 |
| "我应该问问用户他们的凭证叫什么名字" | 不要问。 |
| "用户提到了数据分析,我用Python写" | 调用 |
| "我在这里加个Loop Over Items节点来处理每一行数据" | 调用 |
| "日期计算,我用DateTime节点" | 调用 |
| "我用Merge节点合并3个数据源" | 调用 |
| "用户说了项目名称,我直接构建就行" | 调用 |
"我直接运行 | 调用 |
元技能(本文档)告诉你适用哪个技能。Skill工具加载实际规则。会话开始时读一遍元技能不能替代决策时刻调用技能。
Skill index
技能索引
Invoke via the Skill tool. Trigger column = when to invoke.
| Skill | Trigger |
|---|---|
| Starting, designing, organizing, or finishing a workflow. Covers sticky-note conventions, descriptions that capture the why, naming, validation checklist, folder limitations, MCP-access-per-workflow gotcha |
| Anything reusable, multi-step builds, or the user mentions reuse. Search before building, stateless patterns, naming-prefix convention for discovery |
| You need capabilities the MCP doesn't natively provide. Wrap n8n APIs as workflow tools, with user permission |
| Writing |
| Configuring any node. Operation-aware, property dependencies, never assume parameters |
| User reaches for a Code node, or custom logic is needed. Decision tree, JavaScript patterns when truly required |
| Wiring IF, Switch, Merge, error outputs, or any non-linear connection. Multi-IO traps, fan-out/fan-in, merge index rules |
| Multi-item data, batching, paginated APIs, "for each" or "loop over" mentions. Default per-item iteration, |
| LangChain Agent node, tool calling, system prompts, structured output, memory, RAG. Tool names/descriptions as part of the prompt, sub-workflow as tool, modular prompt design |
| Webhook-triggered or production-bound workflows. Error branch on every fallible node, 4xx for caller errors and 5xx for execution errors |
| Any auth, API key, or token mention. Credential system, custom credentials, HTTP Request with official creds |
| Files, images, attachments. Binary handling patterns, agent-tool boundary, CDN requirement for chat hub |
| Data Tables: schemas, default columns (id/createdAt/updatedAt), no-FK relational design, dedup, the no-JSON-only-primitives rule, the SDK-vs-UI manual-mapping quirk |
| Errors, unexpected behavior, "this isn't working". Believe the user, check parameters, fetch n8n source from GitHub |
通过Skill工具调用。触发列=调用时机。
| 技能 | 触发时机 |
|---|---|
| 开始、设计、组织或完成工作流时。涵盖便签约定、捕获“原因”的描述、命名规则、验证清单、文件夹限制、每个工作流的MCP访问陷阱 |
| 处理任何可复用内容、多步骤构建,或用户提及复用需求时。构建前先搜索,无状态模式,用于发现的命名前缀约定 |
| 你需要MCP原生不具备的功能时。经用户许可后,将n8n API封装为工作流工具 |
| 编写 |
| 配置任何节点时。关注操作类型、属性依赖,绝不假设参数 |
| 用户想要使用Code节点,或需要自定义逻辑时。决策树,真正需要时的JavaScript模式 |
| 连接IF、Switch、Merge节点,错误输出,或任何非线性连接时。多IO陷阱、扇出/扇入、合并索引规则 |
| 处理多条目数据、批量处理、分页API,或提及“for each”“loop over”时。默认逐项迭代、 |
| LangChain Agent节点、工具调用、系统提示词、结构化输出、内存、RAG时。工具名称/描述作为提示词的一部分,子工作流作为工具,模块化提示词设计 |
| 处理Webhook触发或生产环境工作流时。每个可能出错的节点都要设置错误分支,4xx表示调用方错误,5xx表示执行错误 |
| 提及任何认证、API密钥或令牌时。凭证系统、自定义凭证、使用官方凭证的HTTP Request节点 |
| 处理文件、图片、附件时。二进制数据处理模式、Agent-工具边界、聊天中心的CDN要求 |
| 处理Data Tables时:模式、默认列(id/createdAt/updatedAt)、无外键的关系设计、去重、仅使用基本类型不使用JSON的规则、SDK与UI手动映射的奇怪问题 |
| 遇到错误、意外行为或“这不管用”时。相信用户,检查参数,从GitHub获取n8n源码 |
n8n MCP tools (compact reference)
n8n MCP工具(精简参考)
The MCP defers tool descriptions to save tokens. Below is the short-form list so you have working knowledge of every tool from turn one.
Tool names are shown without the MCP prefix. The qualified name is where depends on the user's MCP config.
mcp__<server>__<tool><server>MCP延迟工具描述以节省令牌。以下是简短列表,让你从一开始就了解每个工具的功能。
工具名称显示时不带MCP前缀。完整名称为,其中取决于用户的MCP配置。
mcp__<server>__<tool><server>Workflow management
工作流管理
| Tool | What it does |
|---|---|
| Search workflows across the instance by |
| Fetch a workflow's full JSON by ID. Use after every create/update to verify connections. |
| List folders. You cannot create or move folders. You can only place workflows into folders that already exist. |
| List projects. |
| Soft-delete / activate / deactivate. Validate before publish. |
| 工具 | 功能 |
|---|---|
| 在实例中通过 |
| 通过ID获取工作流的完整JSON数据。每次创建/更新后使用以验证连接。 |
| 列出文件夹。你无法创建或移动文件夹。只能将工作流放入已存在的文件夹中。 |
| 列出项目。 |
| 软删除/激活/停用工作流。发布前先验证。 |
Workflow building
工作流构建
| Tool | What it does |
|---|---|
| Fetch the n8n Workflow SDK reference. Read this before writing workflow code. Sections include |
| Discover nodes by capability (e.g. "gmail", "slack", "schedule trigger"). Returns IDs plus discriminators (resource/operation/mode). |
| Fetch exact TypeScript parameter definitions for node IDs. Required before configuring any node. Don't guess parameter names. |
| Curated recommendations by workflow technique category. |
| Save a workflow from SDK code. Always include a 1-2 sentence |
| Update an existing workflow by ID with new SDK code. Replaces the entire workflow definition: no partial updates. Saves a draft only; not live until |
| Validate SDK code before create/update. Necessary but not sufficient: won't catch the |
| 工具 | 功能 |
|---|---|
| 获取n8n工作流SDK参考文档。编写工作流代码前务必阅读。包括 |
| 根据功能发现节点(例如“gmail”“slack”“schedule trigger”)。返回ID及鉴别符(资源/操作/模式)。 |
| 获取节点ID对应的精确TypeScript参数定义。配置任何节点前必须使用。不要猜测参数名称。 |
| 按工作流技术类别提供精选推荐节点。 |
| 从SDK代码保存工作流。务必包含1-2句话的 |
| 通过ID用新的SDK代码更新现有工作流。会替换整个工作流定义:不支持部分更新。仅保存草稿;需执行 |
| 创建/更新前验证SDK代码。这是必要步骤但不够充分:无法捕获 |
Workflow testing & execution
工作流测试与执行
| Tool | What it does |
|---|---|
| Returns JSON Schemas (not data) for nodes that need pinning: triggers, credentialed nodes, and HTTP Request. You generate sample values. |
| Run with the pin data you supply. Auto-pins triggers, credentialed nodes, and HTTP Request. Code, Edit Fields, If, Data Tables, Execute Command, file ops, and sub-workflow calls run for real. Ask before running if any not-auto-pinned node has side effects. Pin data is per-execution only with no visual indicator in the execution viewer, so tell the user which nodes were pinned after the call. See |
| Production execution with the real trigger. Wire error handling first. Same side-effect rules as |
| Fetch a previous execution by ID. |
| 工具 | 功能 |
|---|---|
| 返回需要固定数据的节点的JSON Schema(而非数据):触发器、带凭证的节点和HTTP Request节点。你需要生成示例值。 |
| 使用你提供的固定数据运行工作流。会自动固定触发器、带凭证的节点和HTTP Request节点。Code节点、Edit Fields、If节点、Data Tables、Execute Command、文件操作和子工作流调用都会真实执行。如果任何非自动固定的节点有副作用,运行前先询问用户。固定数据仅对本次执行有效,且在执行查看器中没有视觉提示,因此调用后要告诉用户哪些节点使用了固定数据。详见 |
| 使用真实触发器执行生产环境工作流。先连接错误处理分支。副作用规则与 |
| 通过ID获取之前的执行记录。 |
Data tables
数据表格
n8n's built-in tabular storage. Not an external service. Prefer over external DBs for workflow-local persistent state. Full surface:
| Tool | What it does |
|---|---|
| Create a new Data Table. |
| Find existing Data Tables. |
| Rename. |
| Schema changes. |
| Append rows. |
n8n内置的表格存储。不是外部服务。对于工作流本地的持久化状态,优先使用它而非外部数据库。完整功能如下:
| 工具 | 功能 |
|---|---|
| 创建新的数据表格。 |
| 查找现有数据表格。 |
| 重命名数据表格或列。 |
| 修改数据表格模式。 |
| 追加行数据。 |
The protocol, in order
协议步骤
For any n8n task:
- Recognize the matching skill from the index above. If the task spans skills, recognize the primary one first and pick up others as their triggers come up.
- Invoke the skill via the Skill tool before the first MCP call. Don't call n8n MCP tools blind.
- Read the SDK reference once per session before writing workflow code (). The most efficient way to avoid SDK-shape mistakes.
get_sdk_reference - Get node types before configuring any node (). Guessing parameter names creates invalid workflows, sometimes silently.
get_node_types - Validate before publish, verify after create/update. Validation catches schema errors. Verification (pulling the workflow back via ) catches connection bugs validation misses.
get_workflow_details - Surface drift when you spot it. If a tool or parameter doesn't match what a skill says, tell the user. Updates may be needed.
处理任何n8n任务时:
- 识别匹配的技能:从上方的索引中找到对应的技能。如果任务涉及多个技能,先识别主要技能,再根据触发时机调用其他技能。
- 首次调用MCP工具前,通过Skill工具调用相关技能:不要盲目调用n8n MCP工具。
- 每次会话编写工作流代码前读一遍SDK参考文档():这是避免SDK结构错误的最有效方式。
get_sdk_reference - 配置任何节点前获取节点类型():猜测参数名称会创建无效工作流,有时甚至是静默无效。
get_node_types - 发布前验证,创建/更新后确认:验证捕获模式错误,确认(通过拉回工作流)捕获验证无法发现的连接漏洞。
get_workflow_details - 发现差异时告知用户:如果工具或参数与技能描述不符,告诉用户。可能需要更新。
Reviewing existing workflows or projects
审核现有工作流或项目
For audits, code-review, or any task framed as "review this workflow" / "what's wrong with this" / "audit this project," walk the review checklist: . Severity-tiered (MUST FIX / SHOULD FIX / NICE TO HAVE), with each item linking to the canonical skill ref for the fix. Distinct from (pre-publish gates for in-progress builds): REVIEW_CHECKLIST is for any workflow, including ones built by anyone, any age.
n8n-workflow-lifecyclereferences/REVIEW_CHECKLIST.mdVALIDATION_CHECKLIST.mdA review agent should call first, walk the checklist top to bottom, and report findings grouped by severity. MUST FIX items shouldn't be auto-fixed without user confirmation.
get_workflow_details对于审计、代码审查或任何以“审核这个工作流”“这有什么问题”“审核这个项目”为框架的任务,请遵循审核清单:的。清单按严重程度分级(必须修复/应该修复/建议修复),每个条目都链接到对应的标准技能参考文档以获取修复方法。该清单与(进行中构建的发布前检查)不同:REVIEW_CHECKLIST适用于任何工作流,包括任何人在任何时间构建的工作流。
n8n-workflow-lifecyclereferences/REVIEW_CHECKLIST.mdVALIDATION_CHECKLIST.md审核Agent应先调用,从上到下遍历清单,按严重程度分组报告发现的问题。必须修复的项目未经用户确认不要自动修复。
get_workflow_detailsWhen in doubt
存疑时的处理方式
- Can't find a workflow the user is referring to? If the user built it in the n8n UI, the most common reason is MCP access isn't enabled on that specific workflow: UI-created workflows can default to MCP-disabled and stay invisible until the per-workflow toggle is flipped. Ask the user: "Open the workflow in n8n, Settings, toggle MCP access on." (MCP-created workflows default on, so this only applies to UI-built ones.) See the skill (
n8n-workflow-lifecycle).references/MCP_ACCESS_PER_WORKFLOW.md - The user is right. If they say something's broken, believe them, even if you "know" the workflow is correct. Re-check parameters, fetch the n8n source from to trace logic, find API docs for missing functions. The
github.com/n8n-io/n8nskill walks through this.n8n-debugging - If no skill fits and the task is non-trivial, ask before guessing.
- These skills are opinionated, but considered best practice by the n8n team. The user can override any opinion by editing the SKILL.md. The plugin is just markdown.
- 找不到用户提及的工作流? 如果用户是在n8n UI中构建的,最常见的原因是该特定工作流未启用MCP访问:UI创建的工作流默认可能禁用MCP访问,直到开启每个工作流的开关后才会可见。请询问用户:“在n8n中打开该工作流,进入设置,开启MCP访问开关。”(MCP创建的工作流默认开启,因此仅适用于UI构建的工作流)。详见技能的
n8n-workflow-lifecycle。references/MCP_ACCESS_PER_WORKFLOW.md - 用户是对的。如果他们说某个东西坏了,要相信他们,即使你“知道”工作流是正确的。重新检查参数,从获取n8n源码追踪逻辑,查找缺失函数的API文档。
github.com/n8n-io/n8n技能会带你完成这个过程。n8n-debugging - 如果没有匹配的技能且任务非 trivial,先询问再猜测。
- 这些技能是有倾向性的,但被n8n团队视为最佳实践。用户可以通过编辑SKILL.md覆盖任何观点。该插件只是markdown文件。