1. 基本信息
项目自述名称：所在仓库自述为「n8n Skills」（n8n 官方出品的技能合集插件，插件 ID
n8n-skills）；本技能自身文档标题为「n8n Error Handling」。
| 项目 | 内容 | 数据来源 |
|---|---|---|
| 名称 | n8n-error-handling-official-n8n-io-skills | — |
| 作者/维护者 | n8n 团队（官方组织 n8n-io，插件 manifest 标注 author: n8n，主页 n8n.io） | GitHub API + 仓库 .claude-plugin/plugin.json |
| 来源链接 | https://github.com/n8n-io/skills/tree/main/skills/n8n-error-handling-official | — |
| 许可证 | Apache-2.0 | GitHub API |
| GitHub Stars（仓库整体） | 373 | GitHub API |
| 该子技能单独统计 | GitHub 不提供子目录级 star 数；改用该子技能相关的 Issue/PR 记录作为热度证据（见第 6、8 章） | 说明性备注 |
| Forks | 39 | GitHub API |
| 最新版本 | 插件 v1.1.0 | 仓库 .claude-plugin/plugin.json |
| 安装方式 | Claude Code / Codex 插件市场一条命令；其他平台可用 skills.sh 或手动复制 SKILL.md | 官方 README |
2. 功能介绍与亮点
核心能力：教 Claude Code / Codex 等编程 Agent 在搭建 n8n workflow 时把“错误处理”钉成硬性规则，而不是出问题后再补救。针对 webhook/API 型 workflow：要求每个可能出错节点的错误输出都接到 Respond to Webhook，且状态码要对应真实原因（调用方的错误给 4xx、自己的错误给 5xx），避免“错误路径返回 200”这种让调用方误以为成功的坑。针对无人值守 workflow（定时、队列驱动）：要求设置 workflow 级 error workflow，捕获逃过单节点处理的超时、节点间崩溃等情况。配套一张“故障原因 → HTTP 状态码 → 错误码 → 处理路径”的十行映射表，以及 retryOnFail 自愈配置（默认 3 次重试、5 秒等待上限）用于吸收瞬时 429 和上游抖动。反模式表逐条列出“用 Code 节点吞掉错误当数据返回”“每次失败都返回 500”等真实场景与后果。
亮点：
- 明确划出“什么时候可以不这么严格”的边界——仅自己一人使用、会盯着看的一次性 workflow，避免对轻量场景过度设计；
- Schema 校验部分附两份可直接复制的 TypeScript 示例文件，而非纯文字描述；
- n8n 官方团队亲自出品（README “Built by the n8n team”）；
- 与 credentials-and-security、workflow-lifecycle 等 12 个姊妹技能共享同一套 hook 自动路由机制。
3. 适用场景
固定分类：集成与工作流自动化
- 用 Claude Code / Codex 通过 n8n MCP 搭建 webhook 触发的 API 型 workflow、需要保证调用方永远拿到明确响应（而非超时）的开发者；
- 搭建定时/队列驱动的无人值守 workflow、担心某次运行悄悄失败没人发现的团队；
- 已经把 n8n 用作业务自动化中枢、但现有 workflow 里错误分支基本没接、或所有失败都返回“Internal Server Error”的老用户，需要系统性补课。
受益人群：把 n8n 用于生产级自动化、需要把“失败要喊出来”落实到具体节点配置的初中级开发者。
4. 跨 Agent 兼容性
- Claude Code：✅ 原生支持——官方插件市场一条命令安装，同一插件包内其余技能已验证过安装流程。
- Codex：✅ 原生支持（需 Codex ≥ 0.142.0）；但同插件市场安装在 Codex Desktop 的 Windows 环境下有已知 hook 执行问题（Issue #40，2026-07-23，独立用户 weijunswj），这是插件层面共性问题，非本技能内容专属缺陷。
- OpenClaw：❓ 未验证——README 仅笼统提及其他平台可尝试 skills.sh，未点名验证 OpenClaw。
- Hermes Agent：❓ 本技能自身未验证。相关背景：同一插件包内姊妹技能
n8n-debugging-official曾被独立用户举报（Issue #29，2026-07-04）存在“把 issue 编号持久化写入 workflow 文件”的问题，被 Hermes 内置安全扫描器标记为 dangerous 并拦截安装，截至 2026-07-27 仍处 open 状态。本技能内容经查未见同类持久化写入指引，但因随同一插件整体安装，未来若在 Hermes 环境使用需留意该姊妹技能的扫描结果。
5. 推荐理由
n8n 官方团队出品，把“workflow 为什么会悄悄挂掉”这个几乎每个自动化开发者都踩过的坑，拆解成 webhook 型与无人值守型两类场景各自的硬性规则、一张故障原因到 HTTP 状态码的映射表、以及 retryOnFail 自愈参数的具体数值——不是“记得处理错误”这种空泛提醒，而是可以直接照抄的配置动作与反模式对照。同仓库的两个姊妹技能（workflow-lifecycle 方法论、credentials-and-security 凭据安全）均已验证过质量水准，本技能延续同等的详实程度，补上生产级 workflow 最容易被忽视的一环。
6. 评分
| 维度 | 分数 | 说明 |
|---|---|---|
| 受欢迎程度 | 7 | n8n 为知名工作流自动化厂商、官方团队亲自出品，仓库整体 373 stars（合集仓库数字，不代表本技能个体热度，见第 1 章说明）；GitHub 不提供子目录级 star 数，改查该文件专属的 Issue/PR 记录——检索未见任何 issue 或 PR 专门提及本技能文件本身；对比之下，同仓库的 n8n-credentials-and-security-official 有独立开发者提交并合并的 PR 记录作为佐证，本技能目前仅代表“暂无已知问题”而非活跃讨论 |
| 可用性 | 8 | Claude Code 官方插件市场一条命令安装，Codex 有对应命令；技能正文附故障原因映射表、反模式对照表与可直接复制的 TypeScript 示例文件，能直接照做；依赖预先开启 MCP server 的 n8n 实例作为前置条件，非纯开箱即用 |
| 安全性 | 8 | 见下方安全检查清单 |
| 综合 | 7.67 | 三项均值 |
安全检查清单：
| 检查项 | 结果 |
|---|---|
| ① Shell 命令权限范围 | 本技能自身不含可执行脚本，仅指导 Agent 配置 n8n 节点属性（onError、retryOnFail 等）与调用已授权的 MCP 工具，未见越权行为，未扣分 |
| ② 运行时联网外发 | 未发现独立于用户自有 n8n 实例之外的外发行为 |
| ③ API key/凭据存储 | 本技能不涉及凭据处理，该主题由同仓库姊妹技能 n8n-credentials-and-security-official 专门覆盖，不适用 |
| ④ 可疑指令/注入迹象 | 本技能文本未见可疑指令。但同一插件包内的姊妹技能 n8n-debugging-official 曾于 2026-07-04 被独立用户举报存在“持久化写入 workflow 文件”的问题，并被 Hermes Agent 安全扫描器标记为 dangerous，截至 2026-07-27 仍处 open 状态尚未修复——与本技能内容无直接关系，但因随同一插件整体安装，计入扣分 |
| ⑤ 作者/组织信誉 | n8n 为知名工作流自动化厂商，官方组织 n8n-io，插件 manifest（author: n8n，homepage: n8n.io）可核验，未扣分 |
| ⑥ License 明确性 | Apache-2.0，明确，未扣分 |
| ⑦ 最近维护时间 | 仓库 2026-04-20 创建，最近提交 2026-07-26，持续更新，非弃置项目，未扣分 |
7. 跟同类 Skills 相比的优势
| 名称 | 定位 | 官方程度 / 热度证据 | 与本技能的差异 |
|---|---|---|---|
| n8n-error-handling-official（本技能，n8n 官方） | webhook / 无人值守 workflow 专项错误处理规范 | 官方仓库，GitHub 检索未见该文件专属 issue/PR 提及 | 160 行，含故障原因→状态码映射表、retryOnFail 自愈参数、可复制 TypeScript 示例 |
czlonkowski/n8n-skills 的 n8n-error-handling（社区版同名技能） |
主题高度一致：per-node 错误输出 + workflow 级 error workflow + 4xx/5xx 响应规范 | 社区维护，所属仓库 5,881 stars，规模远超官方仓库 | 269 行，篇幅更长、覆盖更细，但非 n8n 官方直接维护，核心思路与本技能高度相近 |
| n8n-credentials-and-security-official（同仓库姊妹技能） | 凭据/密钥认证专项 | 官方仓库，已有独立开发者 PR 合并记录 | 覆盖领域不同（认证 vs 错误处理），二者常在同一生产级 workflow 中配合使用 |
| n8n-workflow-lifecycle-official（同仓库姊妹技能） | workflow 全生命周期方法论（计划→构建→校验→测试→发布→交接） | 官方仓库 | 广度优先，错误处理只是其六阶段流程中的一条 non-negotiable，未展开状态码映射与自愈重试细节 |
核心差异化：与社区版同名技能相比，二者解决的问题和思路高度相近，但本技能是 n8n 官方直接维护、随官方“生产级 workflow 构建”技能包统一分发，并与同仓库凭据安全、生命周期两个专项技能共享同一套路由机制，形成一套官方认证的完整体系，而非孤立单点技能。
8. 用户评价
该技能目前在第三方平台与 GitHub 均未发现具名用户评价，也未检索到专门提及该技能文件的 issue 或 PR。
9. 其他补充
同仓库另有 12 个专项技能（工作流生命周期、凭据安全、循环分页、AI Agent 节点配置、二进制数据处理等）与 1 个路由入口技能 using-n8n-skills-official，随插件一次性安装，共享同一套 hook 自动路由机制。仓库明确欢迎社区为其他编程 Agent（Cursor、OpenCode 等）贡献适配插件。
10. 安装使用方式
Claude Code（官方推荐）：
/plugin marketplace add n8n-io/skills
/plugin install n8n-skills@n8n-io安装时会提示填写 n8n 实例 URL，随后运行 /reload-plugins 生效。
Codex：
codex plugin marketplace add n8n-io/skills
codex plugin add n8n-skills@n8n-io重启后首次运行会提示信任插件 hooks，需批准以启用自动路由提醒；另需手动添加 MCP 服务器：
codex mcp add n8n-mcp --url https://<你的n8n域名>/mcp-server/http其他平台（OpenClaw / Hermes 等，非官方支持）：
npx skills add n8n-io/skills需自行在 AGENTS.md 中补充片段，引导 Agent 在涉及 webhook/定时任务的 n8n 任务时主动加载本技能——通用安装方式没有 hook 自动触发，退化为纯文档。
前置条件：需要一个已开启实例级 MCP server 的 n8n 实例（Cloud 或自托管均可，最低 n8n 2.2.0），在 n8n 的 Settings → Instance-level MCP 中启用。
11. 注意事项
- 需要预先具备已开启 MCP server 的 n8n 实例，单纯装技能无法替代该前置配置；
- 同插件包内姊妹技能
n8n-debugging-official存在尚未修复的安全披露（Issue #29），若计划在 Hermes 环境使用同一插件包，建议关注该 issue 的后续修复进展； - Codex Desktop 在 Windows 上执行插件自带 shell hooks 存在已知不稳定问题（Issue #40，截至 2026-07-27 仍 open），会影响自动路由提醒的可靠性，但不影响手动查阅技能正文；
retryOnFail的waitBetweenTries参数在 n8n 引擎侧硬性上限为 5000ms、maxTries上限为 5，超出配置会被引擎自动截断；- 插件版本仍处 v1.1.0，仓库创建于 2026-04-20，历史积累约 3 个月，长期可持续性有待观察。