using-n8n-skills

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Using 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
get_node_types
returns, or behavior differs from what the skill describes), suggest updating the skill and n8n instance to the latest stable.
官方n8n MCP会不断演进,因此不同版本间的工具名称、参数和默认行为可能会出现差异。当你发现差异时(技能中提及的工具不存在、参数结构与
get_node_types
返回的不匹配,或者行为与技能描述不符),建议将技能和n8n实例更新至最新稳定版本。

Non-negotiables

不可协商规则

Three rules with no exceptions. Violating any produces workflows that look right but break in production.
  1. 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.
  2. Validate AND verify before publishing.
    validate_workflow
    before
    publish_workflow
    , and
    get_workflow_details
    after every create or update to check the
    connections
    object. Validation alone misses many issues documented in the skills that will silently break workflows.
  3. 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
    .
三条无例外规则。违反任何一条都会导致工作流看似正常,但在生产环境中崩溃。
  1. 执行任何n8n操作前调用相关技能。不仅限于MCP工具调用。在编写SDK代码、配置节点、设计工作流、连接节点、构建Agent或处理错误之前:通过Skill工具调用匹配的技能。本文档是一个路由器,实际规则在技能主体中。如果已安装插件,PreToolUse钩子会在高影响的MCP调用时提醒你。其他所有操作的责任由你承担。宁可多阅读文档,也不要遗漏规则。
  2. 发布前必须验证并确认。发布工作流前先执行
    validate_workflow
    ,每次创建或更新后执行
    get_workflow_details
    以检查
    connections
    对象。仅靠验证无法发现技能文档中记录的许多会导致工作流静默崩溃的问题。
  3. 令牌/密钥绝不能放入文本字段。始终使用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
    search_workflows({ query: 'Subworkflow' })
    before building. See
    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.
ThoughtAction
"This workflow is simple, I'll just build it"Invoke
n8n-workflow-lifecycle
. Most "simple" workflows are 10+ nodes by the time they ship.
"I'll add a Set node here to map these fields"Invoke
n8n-expressions
. Set nodes feeding only 0 or 1 downstream consumer are the most common antipattern in this entire pack.
"I'll just use a Code node, it's easier"Invoke
n8n-code-nodes
. The bar is high. Most reaches for Code can be expressions or Edit Fields with arrow functions.
"Validation passed, I'm ready to publish"Invoke
n8n-workflow-lifecycle
and walk
VALIDATION_CHECKLIST.md
section 2.5 (the antipattern scan). Validation passing is necessary, not sufficient.
"The agent is wired up, the tool descriptions look fine"Invoke
n8n-agents
references/TOOLS.md
. Tool names and descriptions ARE part of the prompt, and "looks fine" usually means generic.
"I'll set this sub-workflow trigger to passthrough"Invoke
n8n-subworkflows
. Passthrough is only correct for binary-receiving sub-workflows that won't be agent tools.
"I'll use passthrough so binary works, then branch internally on which input shape arrived"Invoke
n8n-subworkflows
references/SUBWORKFLOW_PATTERNS.md
"Splitting by input shape". This is the signal to SPLIT into two outer sub-workflows (one Define Below, one passthrough) sharing a common downstream sub-workflow. Don't fight passthrough vs Define Below in one trigger.
"I should ask the user what their credential is named"Don't. The string in
newCredential('Label')
is cosmetic. See
n8n-credentials-and-security
.
"The user mentioned data analysis, I'll write Python"Invoke
n8n-code-nodes
. Default is JavaScript. Python only when explicitly asked.
"I'll add a Loop Over Items here to process each row"Invoke
n8n-loops
. Default per-item iteration probably handles it without a Loop Over Items node.
"Date math, I'll use a DateTime node"Invoke
n8n-expressions
. DateTime nodes are almost always wrong.
"I'll wrap this in a Merge with 3 sources"Invoke
n8n-connections
references/MERGE_INDEX_RULES.md
. Merge defaults to 2 inputs, and 3+ sources need
numberOfInputs
set explicitly.
"User said which project, I'll just build it"Invoke
n8n-workflow-lifecycle
. Project is not folder. Ask about folder placement BEFORE building. The MCP can't create folders, so if the requested folder doesn't exist, the user must create it in the UI first.
"I'll just run
test_workflow
to see what happens"
Invoke
n8n-workflow-lifecycle
references/TESTING.md
.
test_workflow
mocks the trigger only. Slack sends, DB writes, payments all fire for real. Ask the user first when downstreams have side effects.
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工具调用相关技能,即使你在会话早期“已经读过它”
想法操作
"这个工作流很简单,我直接构建就行"调用
n8n-workflow-lifecycle
。大多数“简单”工作流最终交付时都会有10个以上的节点。
"我在这里加个Set节点来映射这些字段"调用
n8n-expressions
。仅给0个或1个下游节点提供数据的Set节点是整个技能包中最常见的反模式。
"我直接用Code节点,这样更简单"调用
n8n-code-nodes
。使用Code节点的门槛很高。大多数想用Code节点的场景都可以用表达式或带箭头函数的Edit Fields替代。
"验证通过了,我可以发布了"调用
n8n-workflow-lifecycle
并查看
VALIDATION_CHECKLIST.md
的2.5节(反模式扫描)。验证通过是必要条件,但并非充分条件。
"Agent已经连接好了,工具描述看起来没问题"调用
n8n-agents
references/TOOLS.md
。工具名称和描述属于提示词的一部分,“看起来没问题”通常意味着描述过于通用。
"我把子工作流的触发器设置为直通模式"调用
n8n-subworkflows
。直通模式仅适用于接收二进制数据且不会作为Agent工具的子工作流。
"我用直通模式让二进制数据正常工作,然后在内部根据输入结构分支处理"调用
n8n-subworkflows
references/SUBWORKFLOW_PATTERNS.md
中的“按输入结构拆分”部分。这时候应该拆分为两个外部子工作流(一个用Define Below模式,一个用直通模式),共享同一个下游子工作流。不要在同一个触发器中纠结直通模式和Define Below模式。
"我应该问问用户他们的凭证叫什么名字"不要问。
newCredential('Label')
中的字符串只是显示用的。详见
n8n-credentials-and-security
"用户提到了数据分析,我用Python写"调用
n8n-code-nodes
。默认使用JavaScript。只有在用户明确要求时才使用Python。
"我在这里加个Loop Over Items节点来处理每一行数据"调用
n8n-loops
。默认的逐项迭代可能无需Loop Over Items节点就能处理。
"日期计算,我用DateTime节点"调用
n8n-expressions
。DateTime节点几乎总是错误选择。
"我用Merge节点合并3个数据源"调用
n8n-connections
references/MERGE_INDEX_RULES.md
。Merge节点默认只支持2个输入,3个及以上数据源需要显式设置
numberOfInputs
参数。
"用户说了项目名称,我直接构建就行"调用
n8n-workflow-lifecycle
。项目不等于文件夹。构建前先询问文件夹位置。MCP无法创建文件夹,因此如果请求的文件夹不存在,用户必须先在UI中创建它。
"我直接运行
test_workflow
看看结果"
调用
n8n-workflow-lifecycle
references/TESTING.md
test_workflow
只会模拟触发器。Slack消息发送、数据库写入、支付等操作都会真实执行。当下游操作有副作用时,先询问用户。测试数据仅对本次执行有效,且在执行查看器中没有视觉提示,因此调用后要告诉用户哪些节点使用了测试数据。
元技能(本文档)告诉你适用哪个技能。Skill工具加载实际规则。会话开始时读一遍元技能不能替代决策时刻调用技能。

Skill index

技能索引

Invoke via the Skill tool. Trigger column = when to invoke.
SkillTrigger
n8n-workflow-lifecycle
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
n8n-subworkflows
Anything reusable, multi-step builds, or the user mentions reuse. Search before building, stateless patterns, naming-prefix convention for discovery
n8n-extending-mcp
You need capabilities the MCP doesn't natively provide. Wrap n8n APIs as workflow tools, with user permission
n8n-expressions
Writing
{{}}
,
$json
,
$node
, expression errors. Luxon for dates, indented multi-line, prefer expressions over extra nodes
n8n-node-configuration
Configuring any node. Operation-aware, property dependencies, never assume parameters
n8n-code-nodes
User reaches for a Code node, or custom logic is needed. Decision tree, JavaScript patterns when truly required
n8n-connections
Wiring IF, Switch, Merge, error outputs, or any non-linear connection. Multi-IO traps, fan-out/fan-in, merge index rules
n8n-loops
Multi-item data, batching, paginated APIs, "for each" or "loop over" mentions. Default per-item iteration,
executeOnce
, Loop Over Items, HTTP pagination
n8n-agents
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
n8n-error-handling
Webhook-triggered or production-bound workflows. Error branch on every fallible node, 4xx for caller errors and 5xx for execution errors
n8n-credentials-and-security
Any auth, API key, or token mention. Credential system, custom credentials, HTTP Request with official creds
n8n-binary-and-data
Files, images, attachments. Binary handling patterns, agent-tool boundary, CDN requirement for chat hub
n8n-data-tables
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
n8n-debugging
Errors, unexpected behavior, "this isn't working". Believe the user, check parameters, fetch n8n source from GitHub
通过Skill工具调用。触发列=调用时机。
技能触发时机
n8n-workflow-lifecycle
开始、设计、组织或完成工作流时。涵盖便签约定、捕获“原因”的描述、命名规则、验证清单、文件夹限制、每个工作流的MCP访问陷阱
n8n-subworkflows
处理任何可复用内容、多步骤构建,或用户提及复用需求时。构建前先搜索,无状态模式,用于发现的命名前缀约定
n8n-extending-mcp
你需要MCP原生不具备的功能时。经用户许可后,将n8n API封装为工作流工具
n8n-expressions
编写
{{}}
$json
$node
,或遇到表达式错误时。使用Luxon处理日期,缩进多行格式,优先使用表达式而非额外节点
n8n-node-configuration
配置任何节点时。关注操作类型、属性依赖,绝不假设参数
n8n-code-nodes
用户想要使用Code节点,或需要自定义逻辑时。决策树,真正需要时的JavaScript模式
n8n-connections
连接IF、Switch、Merge节点,错误输出,或任何非线性连接时。多IO陷阱、扇出/扇入、合并索引规则
n8n-loops
处理多条目数据、批量处理、分页API,或提及“for each”“loop over”时。默认逐项迭代、
executeOnce
、Loop Over Items节点、HTTP分页
n8n-agents
LangChain Agent节点、工具调用、系统提示词、结构化输出、内存、RAG时。工具名称/描述作为提示词的一部分,子工作流作为工具,模块化提示词设计
n8n-error-handling
处理Webhook触发或生产环境工作流时。每个可能出错的节点都要设置错误分支,4xx表示调用方错误,5xx表示执行错误
n8n-credentials-and-security
提及任何认证、API密钥或令牌时。凭证系统、自定义凭证、使用官方凭证的HTTP Request节点
n8n-binary-and-data
处理文件、图片、附件时。二进制数据处理模式、Agent-工具边界、聊天中心的CDN要求
n8n-data-tables
处理Data Tables时:模式、默认列(id/createdAt/updatedAt)、无外键的关系设计、去重、仅使用基本类型不使用JSON的规则、SDK与UI手动映射的奇怪问题
n8n-debugging
遇到错误、意外行为或“这不管用”时。相信用户,检查参数,从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
mcp__<server>__<tool>
where
<server>
depends on the user's MCP config.
MCP延迟工具描述以节省令牌。以下是简短列表,让你从一开始就了解每个工具的功能。
工具名称显示时不带MCP前缀。完整名称为
mcp__<server>__<tool>
,其中
<server>
取决于用户的MCP配置。

Workflow management

工作流管理

ToolWhat it does
search_workflows
Search workflows across the instance by
query
(matches name and description, but tags are not filterable via MCP). The only cross-workflow tool. Use it to discover what already exists.
get_workflow_details
Fetch a workflow's full JSON by ID. Use after every create/update to verify connections.
search_folders
List folders. You cannot create or move folders. You can only place workflows into folders that already exist.
search_projects
List projects.
archive_workflow
/
publish_workflow
/
unpublish_workflow
Soft-delete / activate / deactivate. Validate before publish.
工具功能
search_workflows
在实例中通过
query
搜索工作流(匹配名称和描述,但标签无法通过MCP过滤)。这是唯一的跨工作流工具。用于发现已存在的工作流。
get_workflow_details
通过ID获取工作流的完整JSON数据。每次创建/更新后使用以验证连接。
search_folders
列出文件夹。你无法创建或移动文件夹。只能将工作流放入已存在的文件夹中。
search_projects
列出项目。
archive_workflow
/
publish_workflow
/
unpublish_workflow
软删除/激活/停用工作流。发布前先验证。

Workflow building

工作流构建

ToolWhat it does
get_sdk_reference
Fetch the n8n Workflow SDK reference. Read this before writing workflow code. Sections include
guidelines
and
design
.
search_nodes
Discover nodes by capability (e.g. "gmail", "slack", "schedule trigger"). Returns IDs plus discriminators (resource/operation/mode).
get_node_types
Fetch exact TypeScript parameter definitions for node IDs. Required before configuring any node. Don't guess parameter names.
get_suggested_nodes
Curated recommendations by workflow technique category.
create_workflow_from_code
Save a workflow from SDK code. Always include a 1-2 sentence
description
.
update_workflow
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
publish_workflow
runs.
validate_workflow
Validate SDK code before create/update. Necessary but not sufficient: won't catch the
.to()
trap.
工具功能
get_sdk_reference
获取n8n工作流SDK参考文档。编写工作流代码前务必阅读。包括
guidelines
design
章节。
search_nodes
根据功能发现节点(例如“gmail”“slack”“schedule trigger”)。返回ID及鉴别符(资源/操作/模式)。
get_node_types
获取节点ID对应的精确TypeScript参数定义。配置任何节点前必须使用。不要猜测参数名称。
get_suggested_nodes
按工作流技术类别提供精选推荐节点。
create_workflow_from_code
从SDK代码保存工作流。务必包含1-2句话的
description
update_workflow
通过ID用新的SDK代码更新现有工作流。会替换整个工作流定义:不支持部分更新。仅保存草稿;需执行
publish_workflow
后才会生效。
validate_workflow
创建/更新前验证SDK代码。这是必要步骤但不够充分:无法捕获
.to()
陷阱。

Workflow testing & execution

工作流测试与执行

ToolWhat it does
prepare_test_pin_data
Returns JSON Schemas (not data) for nodes that need pinning: triggers, credentialed nodes, and HTTP Request. You generate sample values.
test_workflow
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
n8n-workflow-lifecycle
references/TESTING.md
.
execute_workflow
Production execution with the real trigger. Wire error handling first. Same side-effect rules as
test_workflow
.
get_execution
Fetch a previous execution by ID.
工具功能
prepare_test_pin_data
返回需要固定数据的节点的JSON Schema(而非数据):触发器、带凭证的节点和HTTP Request节点。你需要生成示例值。
test_workflow
使用你提供的固定数据运行工作流。会自动固定触发器、带凭证的节点和HTTP Request节点。Code节点、Edit Fields、If节点、Data Tables、Execute Command、文件操作和子工作流调用都会真实执行。如果任何非自动固定的节点有副作用,运行前先询问用户。固定数据仅对本次执行有效,且在执行查看器中没有视觉提示,因此调用后要告诉用户哪些节点使用了固定数据。详见
n8n-workflow-lifecycle
references/TESTING.md
execute_workflow
使用真实触发器执行生产环境工作流。先连接错误处理分支。副作用规则与
test_workflow
相同。
get_execution
通过ID获取之前的执行记录。

Data tables

数据表格

n8n's built-in tabular storage. Not an external service. Prefer over external DBs for workflow-local persistent state. Full surface:
ToolWhat it does
create_data_table
Create a new Data Table.
search_data_tables
Find existing Data Tables.
rename_data_table
/
rename_data_table_column
Rename.
add_data_table_column
/
delete_data_table_column
Schema changes.
add_data_table_rows
Append rows.
n8n内置的表格存储。不是外部服务。对于工作流本地的持久化状态,优先使用它而非外部数据库。完整功能如下:
工具功能
create_data_table
创建新的数据表格。
search_data_tables
查找现有数据表格。
rename_data_table
/
rename_data_table_column
重命名数据表格或列。
add_data_table_column
/
delete_data_table_column
修改数据表格模式。
add_data_table_rows
追加行数据。

The protocol, in order

协议步骤

For any n8n task:
  1. 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.
  2. Invoke the skill via the Skill tool before the first MCP call. Don't call n8n MCP tools blind.
  3. Read the SDK reference once per session before writing workflow code (
    get_sdk_reference
    ). The most efficient way to avoid SDK-shape mistakes.
  4. Get node types before configuring any node (
    get_node_types
    ). Guessing parameter names creates invalid workflows, sometimes silently.
  5. Validate before publish, verify after create/update. Validation catches schema errors. Verification (pulling the workflow back via
    get_workflow_details
    ) catches connection bugs validation misses.
  6. 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任务时:
  1. 识别匹配的技能:从上方的索引中找到对应的技能。如果任务涉及多个技能,先识别主要技能,再根据触发时机调用其他技能。
  2. 首次调用MCP工具前,通过Skill工具调用相关技能:不要盲目调用n8n MCP工具。
  3. 每次会话编写工作流代码前读一遍SDK参考文档
    get_sdk_reference
    ):这是避免SDK结构错误的最有效方式。
  4. 配置任何节点前获取节点类型
    get_node_types
    ):猜测参数名称会创建无效工作流,有时甚至是静默无效。
  5. 发布前验证,创建/更新后确认:验证捕获模式错误,确认(通过
    get_workflow_details
    拉回工作流)捕获验证无法发现的连接漏洞。
  6. 发现差异时告知用户:如果工具或参数与技能描述不符,告诉用户。可能需要更新。

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:
n8n-workflow-lifecycle
references/REVIEW_CHECKLIST.md
. Severity-tiered (MUST FIX / SHOULD FIX / NICE TO HAVE), with each item linking to the canonical skill ref for the fix. Distinct from
VALIDATION_CHECKLIST.md
(pre-publish gates for in-progress builds): REVIEW_CHECKLIST is for any workflow, including ones built by anyone, any age.
A review agent should call
get_workflow_details
first, walk the checklist top to bottom, and report findings grouped by severity. MUST FIX items shouldn't be auto-fixed without user confirmation.
对于审计、代码审查或任何以“审核这个工作流”“这有什么问题”“审核这个项目”为框架的任务,请遵循审核清单
n8n-workflow-lifecycle
references/REVIEW_CHECKLIST.md
。清单按严重程度分级(必须修复/应该修复/建议修复),每个条目都链接到对应的标准技能参考文档以获取修复方法。该清单与
VALIDATION_CHECKLIST.md
(进行中构建的发布前检查)不同:REVIEW_CHECKLIST适用于任何工作流,包括任何人在任何时间构建的工作流。
审核Agent应先调用
get_workflow_details
,从上到下遍历清单,按严重程度分组报告发现的问题。必须修复的项目未经用户确认不要自动修复。

When 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
    n8n-workflow-lifecycle
    skill (
    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
    github.com/n8n-io/n8n
    to trace logic, find API docs for missing functions. The
    n8n-debugging
    skill walks through this.
  • 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
  • 用户是对的。如果他们说某个东西坏了,要相信他们,即使你“知道”工作流是正确的。重新检查参数,从
    github.com/n8n-io/n8n
    获取n8n源码追踪逻辑,查找缺失函数的API文档。
    n8n-debugging
    技能会带你完成这个过程。
  • 如果没有匹配的技能且任务非 trivial,先询问再猜测。
  • 这些技能是有倾向性的,但被n8n团队视为最佳实践。用户可以通过编辑SKILL.md覆盖任何观点。该插件只是markdown文件。