using-n8n-skills

使用 n8n 技能

官方 n8n MCP 会不断演进，因此不同版本中的工具名称、参数和默认行为可能会发生变化。如果发现不一致（技能中提到的工具不存在、参数结构与 get_node_types 返回的结果不符，或实际行为与技能描述不同），建议将技能和 n8n 实例更新到最新稳定版本。

不容妥协的事项

以下三条规则没有例外。违反任何一条，都会导致工作流看起来没问题，却在生产环境中出故障。

1. 执行任何 n8n 操作之前，都要调用相关技能。 不只是调用 MCP 工具。在编写 SDK 代码、配置节点、设计工作流、连接节点、构建 Agent 或处理错误之前，都要通过 Skill 工具调用对应技能。本文档是路由指南，具体规则以技能正文为准。如果安装了插件，PreToolUse 钩子会在影响最大的 MCP 调用上提醒你。其他操作则由你自行负责。拿不准时，多读一些文档。
2. 发布之前，先验证并核实。 执行 publish_workflow 之前，先执行 validate_workflow；每次创建或更新后，都要执行 get_workflow_details 检查 connections 对象。仅靠验证会遗漏技能中记录的许多问题，这些问题会导致工作流在无提示的情况下出故障。
3. 绝不能将令牌或密钥放入文本字段。 始终使用 n8n 凭据系统。如果没有原生节点，请使用官方凭据类型配置 HTTP Request。请参阅 n8n-credentials-and-security。

依赖技能，而非训练数据

n8n 的发展速度快于任何模型的训练数据更新。参数名称会变化，新 MCP 工具会推出，默认值会更改，某些模式会被弃用。你“记得”的内容很可能是错的，而且往往不会显露出来。

应相信技能和实时 MCP 工具（get_node_types、get_sdk_reference、get_workflow_best_practices），而不是依赖记忆。如果技能与“你所知道的”内容矛盾，应以技能为准。如果 get_node_types 与技能矛盾，应以工具为准。不遵循这一原则，就会交付看起来正确、却会在无提示的情况下失败的工作流：参数名称不存在、节点已重命名、模式已弃用。

除非用户偏好另有要求，否则宁可加载过多技能，也不要加载过少。即使是包含 3 个节点的 Webhook 工作流，通常也需要 n8n-node-configuration、n8n-expressions、n8n-error-handling 和 n8n-workflow-lifecycle。在 n8n 中，没有小到不需要技能的操作。

建议的默认做法（每项技能均有自己的例外规则）

• Code 节点是最后的选择。 优先使用表达式，然后是在 Edit Fields 中使用箭头函数，最后才用 Code。只有在多来源聚合、使用库和有状态操作时，才值得使用 Code。请参阅 n8n-code-nodes。
• 任何可复用的内容都应变成无状态子工作流。 构建之前，先通过 search_workflows({ tags: ['subworkflow'] }) 搜索现有工作流。请参阅 n8n-subworkflows。

红旗：意味着必须停止并调用技能的想法

这些自我说服会导致跳过技能。如果你发现自己有以下任何想法，请通过 Skill 工具调用相关技能，即使你“之前已经在本次会话中读过它”。

想法	操作
“这个工作流很简单，我直接构建就行”	调用 n8n-workflow-lifecycle。大多数“简单”的工作流在交付时都有 10 个以上节点。
“我在这里添加一个 Set 节点来映射这些字段”	调用 n8n-expressions。在整个工具包中，仅有 0 或 1 个下游使用者的 Set 节点是最常见的反模式。
“我直接用 Code 节点吧，这样更简单”	调用 n8n-code-nodes。要求很高。大多数使用 Code 节点的场景都可以用表达式或带箭头函数的 Edit Fields 实现。
“验证通过了，我可以发布了”	调用 n8n-workflow-lifecycle，并检查 VALIDATION_CHECKLIST.md 第 2 节（反模式扫描）。验证通过是必要条件，但并非充分条件。
“Agent 已经连好了，工具描述看起来也没问题”	调用 n8n-agents 的 references/TOOLS.md。工具名称和描述都是提示词的一部分，而“看起来没问题”通常意味着描述太宽泛。
“我会把这个子工作流触发器设为 passthrough”	调用 n8n-subworkflows。passthrough 只适用于接收二进制数据且不会用作 Agent 工具的子工作流，或确实不接收输入的子工作流（Define Below 至少需要一个字段）。
“我会用 passthrough 支持二进制数据，然后在内部根据收到的输入形状分支”	调用 n8n-subworkflows 的 references/SUBWORKFLOW_PATTERNS.md 中的“按输入形状拆分”。这意味着应拆分为两个外层子工作流（一个使用 Define Below，一个使用 passthrough），并让它们共用一个下游子工作流。不要在一个触发器中纠结于 passthrough 和 Define Below 的选择。
“这一部分很大，我把它提取到子工作流中”	如果只是为了让画布更整洁（而非复用、隔离或测试），节点组更轻量、更快、更简单：将其保留为内联节点，并通过 setNodeGroups 分组。仅在需要复用、隔离或将其用作 Agent 工具时，才提取为子工作流。请参阅 n8n-workflow-lifecycle 中的“可读性”。
“我应该问用户他们的凭据叫什么”	不要问。newCredential('Label') 中的字符串仅用于显示。请参阅 n8n-credentials-and-security。
“用户提到了数据分析，我来写 Python”	调用 n8n-code-nodes。默认使用 JavaScript。只有在用户明确要求时才使用 Python。
“我在这里添加一个 Loop Over Items 来处理每一行”	调用 n8n-loops。默认的逐项迭代可能无需 Loop Over Items 节点就能处理。
“日期计算？我用 DateTime 节点吧”	调用 n8n-expressions。DateTime 节点几乎总是不合适。
“我会把这几个步骤用一个包含 3 个来源的 Merge 包起来”	调用 n8n-node-configuration 中的 references/MERGE_NODE.md。Merge 默认有 2 个输入，3 个或更多来源需要显式设置 numberOfInputs。
“我会让这三个耗时步骤并行执行”	调用 n8n-workflow-lifecycle 并阅读“执行模型”一节。n8n 会按顺序执行分支（按 Y 坐标从上到下），不会并发执行。要实现真正的并发，请参阅 n8n-loops 和 n8n-subworkflows（mode: 'each' + waitForSubWorkflow: false）。
“用户说了是哪个项目，我直接构建就行”	调用 n8n-workflow-lifecycle。项目不等于文件夹。构建前先询问文件夹位置。MCP 无法创建文件夹，因此如果用户请求的文件夹不存在，用户必须先在 UI 中创建。
“我直接运行 test_workflow 看看会发生什么”	调用 n8n-workflow-lifecycle 中的 references/TESTING.md。test_workflow 只会模拟触发器。Slack 发送、数据库写入和付款都会真实执行。如果下游操作有副作用，请先询问用户。

元技能（本文档）会告诉你适用哪项技能。Skill 工具会加载具体规则。 在会话开始时读过一次元技能，并不能替代在做出决策时调用相应技能。

技能索引

通过 Skill 工具调用。触发条件列说明何时调用。

技能	触发条件
n8n-workflow-lifecycle	开始、设计、整理或完成工作流。涵盖便笺约定、说明中阐明 why、命名、验证清单、文件夹限制，以及 MCP 按工作流授权访问这一注意事项
n8n-subworkflows	涉及可复用内容、多步骤构建，或用户提到复用。构建前先搜索、无状态模式、基于标签的发现约定
n8n-extending-mcp	需要 MCP 原生不具备的功能。经用户许可，将 n8n API 封装为工作流工具
n8n-expressions	编写 {{}}、$json、$node 或处理表达式错误。日期使用 Luxon、多行内容缩进，优先使用表达式而非额外节点
n8n-node-configuration	配置任何节点。根据操作选择配置、处理属性依赖关系，切勿假定参数
n8n-code-nodes	用户想使用 Code 节点，或需要自定义逻辑。决策树、确有必要时采用 JavaScript 模式
n8n-loops	涉及多项数据、批处理、分页 API，或提到“逐项处理”或“循环”。默认逐项迭代、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 工具（精简参考）

MCP 会省略工具说明以节省令牌。以下是简要列表，帮助你从第一轮对话开始掌握每个工具。

工具名称不含 MCP 前缀。限定名称格式为 mcp__<server>__<tool>，其中 <server> 取决于用户的 MCP 配置。

工作流管理

工具	功能
search_workflows	根据 query（名称或说明中包含的子字符串）和／或 tags（精确标签名称，采用 AND 语义：必须全部匹配）搜索实例中的工作流。主要的跨工作流发现工具。用于查找已有内容。
get_workflow_details	按 ID 获取工作流的完整 JSON。每次创建或更新后都要使用此工具验证连接。
search_folders	列出文件夹。**无法创建或移动文件夹。**只能将工作流放入已存在的文件夹。
search_projects	列出项目。
list_tags	列出所有工作流标签（每个标签包含 usageCount）。添加标签或筛选前，先检查实例中的标签词汇，以便复用完全一致的名称。通过 update_workflow 的 addTags/removeTags 添加或移除标签；没有重命名或删除标签的工具。
archive_workflow / publish_workflow / unpublish_workflow	软删除／激活／停用。发布前先验证。publish_workflow 可选接受 versionId，用于重新发布指定版本。
search_executions	按状态、工作流和时间范围筛选，搜索实例中的执行记录。用于“列出最近的运行记录”／“查找过去一小时内的失败记录”。单条执行记录使用 get_execution。

工作流构建

工具	功能
get_sdk_reference	获取 n8n Workflow SDK 参考文档。**编写工作流代码前请先阅读。**包含以下部分：patterns、patterns_detailed、expressions、functions、rules、import、guidelines、design、all。
get_workflow_best_practices	获取某项工作流技术的最佳实践。搜索节点前，每项技术调用一次。technique: "list" 可查看可用内容。
search_nodes	按功能查找节点（例如 “gmail”“slack”“schedule trigger”）。返回 ID 及判别字段（资源/操作/模式）。
get_node_types	获取节点 ID 对应的确切 TypeScript 参数定义。**配置任何节点前都必须调用。**不要猜测参数名称。
explore_node_resources	解析资源定位器（@searchListMethod）和加载选项（@loadOptionsMethod）参数背后的实际值：Slack 频道、Sheets 工作表/文档、数据库表/列、模型列表、标签。需要 list_credentials 返回的 credentialId（对于依赖项查询，请传入 currentNodeParameters）。在 get_node_types 之后调用，以获取实际下拉选项值，而不是臆造 ID。
create_workflow_from_code	从 SDK 代码保存工作流。务必附带 1 至 2 句话的 description。传入 skillsUsed（见下文）。
update_workflow	应用原子操作（最多 100 项，全部成功或全部失败）：节点/连接的增删改查、setNodeCredential、setNodeSettings（按节点设置 onError/retry/executeOnce）、setWorkflowSettings（errorWorkflow、时区、callerPolicy、超时、保存数据策略；n8n 2.29.0+）、setNodeGroups（画布分组）、setWorkflowMetadata、addTags/removeTags（自动创建未知名称）。保存为草稿；需要调用 publish_workflow 才能正式启用。传入 skillsUsed（见下文）。
validate_node_config	仅验证节点配置的架构（每次调用 1 至 50 项）。提供按参数列出的错误，不含图结构噪声。用于迭代/调试的辅助工具；发布仍需通过 validate_workflow。对于 ai_tool 子节点，请设置 isToolNode: true。
validate_workflow	在创建/更新前验证完整的 SDK 代码。此步骤必不可少，但并非充分条件：无法捕获所有连线陷阱（.to()、合并索引）。
list_credentials	列出可访问的凭据（可按类型/项目等筛选）。仅返回元数据，绝不返回密钥值。在通过 setNodeCredential 绑定前，先查找 ID。

工作流测试与执行

工具	功能
prepare_test_pin_data	为需要固定测试数据的节点返回 JSON Schema（不是数据）：触发器、带凭据的节点和 HTTP Request。由你生成示例值。
test_workflow	使用你提供的固定数据运行工作流。**自动为触发器、带凭据的节点和 HTTP Request 固定数据。**代码、Edit Fields、If、Data Tables、Execute Command、文件操作和子工作流调用都会真实运行。如果任何未自动固定数据的节点会产生副作用，请先征求确认。固定数据仅对单次执行有效，执行查看器中也没有可视标记，因此调用后要告知用户哪些节点固定了数据。参见 n8n-workflow-lifecycle 的 references/TESTING.md。
execute_workflow	使用真实触发器执行生产环境工作流。请先配置错误处理。副作用规则与 test_workflow 相同。executionMode 用于选择 manual（草稿）或 production（已发布）；聊天/表单/Webhook 触发器可使用结构化 inputs。调用后会立即返回执行 ID，不会等待完成；请轮询 get_execution 获取结果。
get_execution	通过 executionId 和 workflowId 获取执行记录（两者都必需）。默认仅返回元数据；设置 includeData: true（可选传入 nodeNames、truncateData）以获取节点输入/输出。

数据表

n8n 内置的表格存储。不是外部服务。对于工作流本地持久化状态，优先使用它，而不是外部数据库。完整功能：

工具	功能
create_data_table	创建新的 Data Table。
search_data_tables	查找现有的 Data Table。
rename_data_table / rename_data_table_column	重命名。
add_data_table_column / delete_data_table_column	更改架构。
add_data_table_rows	追加行。

版本历史

工具	功能
get_workflow_history	列出工作流已保存的版本，按从新到旧排序（n8n 2.29.0+）。
get_workflow_version	根据 versionId 获取过去某个版本的完整内容。
restore_workflow_version	将过去某个版本重新应用为当前草稿（并记录一条新的历史记录）。

按顺序执行协议

对于任何 n8n 任务：

1. 从上面的索引中识别匹配的技能。 如果任务涉及多个技能，先识别主要技能，并在触发条件出现时再选择其他技能。
2. 在首次 MCP 调用前，通过 Skill 工具调用该技能。 不要盲目调用 n8n MCP 工具。
3. 在编写工作流代码前，每个会话读取一次 SDK 参考（get_sdk_reference）。这是避免 SDK 结构错误的最高效方式。
4. 在配置任何节点前获取节点类型（get_node_types）。猜测参数名称会创建无效工作流，有时还不会报错。
5. 发布前验证，创建或更新后检查。 验证可捕获架构错误。检查（通过 get_workflow_details 拉取工作流）可捕获验证无法发现的连接错误。
6. 发现偏差时及时说明。 如果工具或参数与技能说明不符，请告知用户。可能需要更新。

报告使用的技能

create_workflow_from_code 和 update_workflow 可选接收 skillsUsed: string[]。每次都要传入，以便 n8n 团队衡量插件对 MCP 输出的影响。

• 内容： 准备此工作流更改时调用的技能。使用完整的 Skill 工具名称（例如 n8n-skills:using-n8n-skills、n8n-skills:n8n-workflow-lifecycle）。
• 时间范围： 自上次成功的创建或更新调用以来调用的技能。每次调用后重置。
• 限制： 最多 50 项，每项最多 128 个字符。

审查现有工作流或项目

对于审计、代码审查，或任何以“审查此工作流”／“这个有什么问题”／“审计此项目”为主题的任务，请按照审查清单执行：n8n-workflow-lifecycle references/REVIEW_CHECKLIST.md。清单按严重程度分级（MUST FIX / SHOULD FIX / NICE TO HAVE），每项都链接到相应问题修复的规范技能参考。它与 VALIDATION_CHECKLIST.md（针对进行中的构建的发布前检查项）不同：REVIEW_CHECKLIST 适用于任何工作流，包括由任何人构建、无论年代的新旧工作流。

审查 Agent 应先调用 get_workflow_details，然后从上到下检查清单，并按严重程度分组报告发现的问题。未经用户确认，不应自动修复 MUST FIX 项。

不确定时

• 找不到用户提到的工作流？ 如果用户是在 n8n UI 中创建的，最常见的原因是该工作流未启用 MCP 访问权限：在 UI 中创建的工作流默认可能会禁用 MCP，因此在打开该工作流的 MCP 开关之前，它会一直不可见。请询问用户：“在 n8n 中打开工作流，进入 Settings，然后启用 MCP 访问权限。”（通过 MCP 创建的工作流默认已启用，因此这只适用于在 UI 中创建的工作流。）请参阅 n8n-workflow-lifecycle 技能（references/MCP_ACCESS_PER_WORKFLOW.md）。
• 用户是对的。如果用户说出了问题，就相信他们，即使你“知道”工作流是正确的。重新检查参数，从 github.com/n8n-io/n8n 获取 n8n 源码以追踪逻辑，并查找缺失函数的 API 文档。n8n-debugging 技能会引导你完成这些步骤。
• 如果没有适用的技能，且任务并不简单，请先询问，不要猜测。
• 这些技能带有鲜明的观点，但被 n8n 团队视为最佳实践。用户可以通过编辑 SKILL.md 来覆盖任何观点。该插件只是 Markdown。