1实现原理 · 为什么它能做到

工具能力全部来自外部的 n8n-mcp MCP server，仓库只做技能层；托管模式以 streamable-http 端点声明，工具名形如 `mcp__n8n-mcp__*`。

mcp.json

"url": "https://api.n8n-mcp.com/mcp"

上一行是 `"type": "streamable-http",`；同一文件还给出 npx 自托管变体（.mcp.json.example 需要 N8N_API_URL / N8N_API_KEY，放在 MCP server 的环境里，仓库脚本自身不读这两个变量）。

入口技能被 SessionStart hook 在每个会话（含 resume/clear/compact）把整个 SKILL.md 读出来注入 additionalContext，从而实现『始终加载』。

hooks/session-start.sh

META_SKILL="${PLUGIN_ROOT}/skills/using-n8n-mcp-skills/SKILL.md"

随后 `SKILL_BODY="$(cat "${META_SKILL}")"` 读全文并用 jq 生成 hookSpecificOutput.additionalContext；source=clear/compact 时还会删掉本会话的提醒去重标记，让提醒重新生效。

『决策瞬间提示』靠 hook 注册表实现：用锚定正则匹配 MCP 工具全名，命中即执行同目录的 bash 脚本。

hooks/hooks.json

"matcher": "^mcp__.*__get_node$",

该 matcher 的 command 指向 `${CLAUDE_PLUGIN_ROOT}/hooks/pre-tool-use/get-node.sh`；同文件共注册 1 个 SessionStart + 7 个 PreToolUse（create/update/validate/test/instances/manage_credentials/get_node）+ 1 个 PostToolUse。

通用提醒做一次性去重：以 session_id + marker 名在临时目录建 .loaded 标记，同一会话不重复打扰。

hooks/pre-tool-use/_emit.sh

MARKER="${STATE_DIR}/${SESSION_ID}-${MARKER_NAME}.loaded"

STATE_DIR = ${TMPDIR:-/tmp}/n8n-mcp-skills-state；无 jq 时回退 python3 解析 stdin 的 session_id，两者都没有就直接 exit 0。

节点级高危提醒刻意不去重：每次查 Set/Code/Merge/Loop/DateTime/DataTable/Agent 都重新注入，理由是重复查询往往意味着在重新考虑同一反模式。

hooks/pre-tool-use/get-node.sh

# High-risk-node warnings: NOT deduped. Each lookup fires the warning fresh.

节点类型从 `.tool_input.nodeType` 取短名（如 nodes-base.set），逐个正则匹配拼装 WARNINGS 后一次输出。

PostToolUse 在 validate_workflow 之后解析 workflow JSON 的节点类型，把剩余风险路由回对应技能，并强调『验证通过 ≠ 正确』。

hooks/post-tool-use/validate-workflow.sh

(.tool_input.workflow.nodes // .tool_input.nodes // [])

脚本注释说明取 LONG form 类型（如 n8n-nodes-base.set）比 grep 源码更稳；无节点 JSON（by-id 校验）时输出通用提示要求手动调用 validation + workflow-patterns 技能。

技能内容采用渐进式披露：SKILL.md 只留核心与索引，细节放在同目录参考 .md，由正文相对链接按需加载。

skills/n8n-code-javascript/SKILL.md

**See**: [DATA_ACCESS.md](DATA_ACCESS.md) → "Mode Performance" for the corollaries, hop costs, and scale check.

每个技能文件尾部的 Related Files 列出其参考文件；self-hosting 技能把部署细节外置到 SECURITY.md / QUEUE_MODE.md。

自托管技能把部署模板放进 assets/，由 agent 通过 ssh 抄写到目标机后 docker compose 启动——这是全包唯一『指导 agent 在远端执行命令』的技能。

skills/n8n-self-hosting/SKILL.md

`ssh <target> 'cat > <DATA_FOLDER>/docker-compose.yml' < assets/docker-compose.single.yml`.

模板本身不含密钥（要求 Secrets live only in `.env`，mode 600）；部署前还要求用 `curl -s ifconfig.me` 与 dig 做 DNS/公网 IP 预检。

打包脚本把版本一致性做成硬断言：两个 manifest 的 version 不一致即 exit 1，然后按目录自动发现技能打 zip。

build.sh

VERSION=$(read_version .claude-plugin/plugin.json)

下一行 `AGENT_PLUGIN_VERSION=$(read_version plugin.json)`；不一致时打印 Version mismatch 并退出。输出为 dist/ 下的单技能 zip 与整包 zip（dist/ 被 .gitignore 忽略）。

2核心能力

01入口路由：先判定该加载哪个专家技能，而不是直接上手做

02三条不可协商规则（先载技能 / 验证且核对 connections / 密钥不进文本字段）

03工具面即知识：用限定名 `mcp__<server>__<tool>` 讲清有哪些工具，填补工具描述未加载的空白

04红旗表：把『我正准备……』的念头映射到必须加载的技能

05hook 强制层：在会话开始与关键 MCP 工具调用前后注入『此刻该加载哪个技能』

06凭证纪律与多实例安全：凭证写操作前强制确认当前实例，避免密钥写错环境

07端到端自托管部署（SSH + Docker Compose + Caddy 自动 TLS）

3外部依赖

Kind	Dependency / Endpoint
api	n8n-mcp 托管 MCP 端点（streamable-http，OAuth 登录）
network	托管端点的接入说明（OAuth 后于 dashboard 连接自己的 n8n 实例）
package	npm 包 n8n-mcp（经 npx 从 registry 拉取，自托管模式）
cli	npx（启动 stdio 模式 MCP server 的示例配置）
cli	docker / docker compose（自托管技能在目标机上执行）
package	容器镜像：Caddy（自动 TLS）与 n8n 本体
network	部署前公网 IP / DNS 预检（curl 与 dig）
cli	hook 运行时依赖 jq，缺失时回退 python3，都没有则静默放弃

4管控建议与判定依据

建议配套管控措施

面向 Agent

分级或逐次授权，建议在沙箱运行

面向管理者

审批流程、可回滚、全程审计

判定依据（文件路径与关键语句摘要）

scripts/: 执行本地脚本或命令: 宿主按 hooks.json 调用仓库内脚本：SessionStart→hooks/session-start.sh（`"command": "${C
网络端点: 声明外部网络访问: hook 脚本内零网络调用：hooks/ 全文无 curl/wget/nc/dev-tcp/eval 调用点，只读 stdin、写 /tmp 标记、输
本地工作目录: 文件读写与工件输出: 去重标记文件：`MARKER="${STATE_DIR}/${SESSION_ID}-${MARKER_NAME}.loaded"` + `touch

审计说明： 🔵 蓝：知晓即可。仓库可执行面只有 hooks/ 下 9 个 bash 与 build.sh：hook 由插件宿主在 SessionStart 与 MCP 工具调用前后执行，行为是读 stdin、写 ${TMPDIR}/n8n-mcp-skills-state 下的去重标记、建一个空缓存目录、输出写死的提醒 JSON——不联网、不读凭证、不碰 ~/.claude 内容，且全部 fail-open（异常即 exit 0）。工具能力来自外部 n8n-mcp MCP server（托管端点 https://api.n8n-mcp.com/mcp），凭证（N8N_API_URL/N8N_API_KEY）由 MCP server 侧持有，仓库脚本从不读取——这部分属宿主与 MCP server 的信任边界，不是本 skill 的行为。按『仅本地工具/CLI 与本地读写、无网络外发、无凭证』归蓝档。知情点两条：安装插件即把 router 的 markdown 注入每个会话（设计意图，但无完整性校验）；自托管技能会指导 agent 用 ssh/docker 在远端机上执行部署命令（需用户显式要求）。

5第二遍独立确认

[ok] skill.path = skills/using-n8n-mcp-skills — 重读 skills/ 目录：15 个子目录、该层无 SKILL.md；glob **/SKILL.md 得 15 个且全部位于 skills/<name>/SKILL.md。重读 hooks/session-start.sh 确认 META_SKILL 指向 using-n8n-mcp-skills，重读 .claude-plugin/marketplace.json 确认同一 bundle 枚举 15 条路径——router 即入口，选它作路径。
[ok] official_desc 逐字 — 重读 skills/using-n8n-mcp-skills/SKILL.md L2-4：description 为单行长文本，正文 L6 才是标题，说明未使用 YAML 折行，逐字转录无拼接误差。
[ok] external_deps：MCP 端点与两种接入方式 — 重读 mcp.json 全 9 行（streamable-http + https://api.n8n-mcp.com/mcp）、.mcp.json.example（npx + MCP_MODE=stdio + N8N_API_URL/N8N_API_KEY 占位）、SKILL.md 的 Hosted/Self-hosted 两段。端点、命令、变量名逐字一致。
[ok] security：hooks 是否联网 — 对 hooks/ 全目录独立 grep（curl|wget|nc |/dev/tcp|eval |base64|N8N_API|API_KEY|TOKEN|\.env）：仅命中提醒文本里的 tokens 字样。逐行重读 _emit.sh 与 session-start.sh 确认无子进程下载、无网络命令。结论不变：hooks 不联网。
[ok] security：hooks 读取的环境变量集合 — 重读 session-start.sh（CLAUDE_PLUGIN_ROOT、HOME、TMPDIR、stdin）与 _emit.sh（TMPDIR、stdin，无 jq 时 python3 兜底）；全仓 grep keychain 零命中，`\.claude` 仅命中 .gitignore 与文档安装指令。
[ok] security：写文件路径 — 重读 _emit.sh 的 STATE_DIR/MARKER/touch、get-node.sh 的同名目录、session-start.sh 的 CACHE_DIR + mkdir 与 rm -f 清理：写路径只有 ${TMPDIR:-/tmp}/n8n-mcp-skills-state/*.loaded（约定前缀）与 ~/.cache/n8n-mcp-skills（仅建目录），另有 build.sh 的 dist/。
[ok] 去重策略：通用一次 vs 节点级每次 — 重读 _emit.sh（有 marker 即 exit 0）与 get-node.sh（通用提醒走 has_marker 去重，高危节点分支无 marker 检查）。题面所述『节点级提醒不去重』在源码注释与逻辑上均成立。
[discrepancy] 披露 vs 实际：评估套件能否运行 — README 写 `npm test` 与 `claude-code --skill n8n-expression-syntax "Test webhook data access"`，但全仓无 package.json、无测试框架配置、无 CI workflow；evaluations/ 下 57 个 JSON 只有 id/skills/query/expected_behavior 字段，无 runner；docs/DEVELOPMENT.md 自述 `*Coming soon: Evaluation framework*`。README 的注释行也写着 `# Run evaluations (if testing framework available)`——即该命令在仓内无法兑现，评估实为人工对照流程。

6结论

把『技能被遗忘』这个 agent 通病做成了工程问题：用 hook 在会话开始与工具调用瞬间注入路由提醒，而不是只靠 description 触发

安全纪律被写进流程而非只做提示：密钥必须走 n8n 凭证系统、验证通过≠正确、多实例下凭证写入前必须确认当前实例

渐进式披露结构良好：主文件短、细节外置，模型可按需加载，token 成本可控

供应链透明度高：hooks 代码来源、改动范围与许可证都被显式声明

可靠性设计克制：所有 hook fail-open，缺依赖或出错都静默放行，绝不阻塞用户的工具调用

适合： 适合已经在用（或准备上）n8n + n8n-mcp 的个人与团队，尤其是反复被『n8n 节点配置细节、表达式语法、Merge 多输入接线』这类隐性坑拖慢的场景；也适合想研究『如何用 hook 让技能在正确时机被自动加载』的 skill 作者——本仓的 SessionStart + PreToolUse 强制层是少见且完整的实现样本。对自建 n8n 的用户，self-hosting 技能提供了一套 SSH + Compose + Caddy 的可执行部署剧本。

不适合： 不适合不使用 n8n-mcp（或任何等价 MCP server）的场景——技能层没有工具就只剩纯建议，价值大幅缩水。不适合把『安全』寄托在 skill 上的用户：写操作门禁是提示词纪律，真正的强制来自 MCP server 与 n8n 侧权限。不适合需要可复现评测结论的采购/审计流程（仓内无 runner、无 CI、无通过率数据）。也不适合非 Claude Code / 非 Codex 客户端下期待『自动加载』——那里 hook 层不存在。

Install Agent-Ready

① Verified Mirror 2026-09-15

Option A · Direct DownloadDownload n8n-workflow-skills.tar.gz

sha256: 9b92af0c1951282e…

Option B · Copy Guide for Agent

install.json

agent 读 JSON 指南后会自动从本站下载安装，无需更多说明。

② Upstream GitHub

GitHub Repo ↗

Pinned to commit 2df0f18cb5.