1仕組みと動作原理
ツールの機能はすべて外部の n8n-mcp MCP サーバーから提供され、当リポジトリはスキル層のみを担当します。ホスト型モードは 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 サーバー側の環境変数として配置され、リポジトリのスクリプト自体はこれらを読み込みません）。
エントリポイントスキルは、SessionStart フックによって各セッション（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 の際には、本セッションのリマインダー重複排除マーカーを削除して再通知を有効化します。
「判断の瞬間に提示するヒント」はフック登録テーブルによって実現されており、アンカー付き正規表現で MCP ツールの完全名にマッチした場合、同ディレクトリの bash スクリプトを実行します。
hooks/hooks.json
"matcher": "^mcp__.*__get_node$",
このマッチャーの 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 が登録されています。
一般的なリマインダーは 1 回限りの重複排除を実施：一時ディレクトリに session_id + マーカー名の .loaded ファイルを作成し、同一セッション内での不要な再通知を防ぎます。
hooks/pre-tool-use/_emit.sh
MARKER="${STATE_DIR}/${SESSION_ID}-${MARKER_NAME}.loaded"
STATE_DIR = ${TMPDIR:-/tmp}/n8n-mcp-skills-state です。jq が存在しない場合は stdin の session_id を python3 でパースする処理にフォールバックし、双方が存在しない場合は直ちに 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 の実行後にワークフロー JSON のノードタイプを解析し、残存リスクを対応する専門スキルにルーティングするとともに、「検証通過 ≠ 正常動作」であることを強調します。
hooks/post-tool-use/validate-workflow.sh
(.tool_input.workflow.nodes // .tool_input.nodes // [])
スクリプト内のコメントによると、完全形式のタイプ（n8n-nodes-base.set など）を取得する方がソースコードを grep するより確実です。ノード JSON が存在しない場合（ID 指定による検証時）は、validation および workflow-patterns スキルの手動呼び出しを促す汎用ヒントを出力します。
スキル内容は段階的開示（Progressive Disclosure）を採用：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/ に配置し、エージェントが SSH 経由で対象マシンに転送した上で docker compose を起動させます。これは本パック内で唯一「エージェントにリモートコマンド実行を指示する」スキルです。
skills/n8n-self-hosting/SKILL.md
`ssh <target> 'cat > <DATA_FOLDER>/docker-compose.yml' < assets/docker-compose.single.yml`.
テンプレート自体に秘密情報は含まれません（「Secrets live only in `.env`」、パーミッション 600 を要求）。デプロイ前には `curl -s ifconfig.me` と dig を用いた DNS/パブリック IP の事前検証も義務付けています。
パッケージングスクリプトはバージョン整合性を厳格にアサートします：2 つのマニフェスト間でバージョンが一致しない場合は 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エントリルーティング：作業に直接着手する前に、まずどの専門スキルを読み込むべきかを判定
023つの不可侵ルール（スキルの事前ロード / 接続の検証と照合 / テキストフィールドへの秘密情報入力禁止）
03知識としてのツール仕様：完全修飾名 `mcp__<server>__<tool>` で提供ツールを明確化し、ツールの説明文が未ロードのギャップを補完
04レッドフラグ表：「〜しようとしている」という思考パターンを必須読み込みスキルへマッピング
05フックによる強制層：セッション開始時および主要な 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
- 网络端点: 外部ネットワークアクセスの宣言: フック内でのネットワーク呼び出しはゼロ：hooks/ 全体で curl/wget/nc/dev-tcp/eval の呼び出し箇所はなく、stdin 読み込み、/tmp マーカー書き込み、出力のみ
- 本地工作目录: ファイルの読み書きと成果物の出力: 重複排除マーカーファイル：`MARKER="${STATE_DIR}/${SESSION_ID}-${MARKER_NAME}.loaded"` + `touch
監査ノート： 🔵 青：内容の確認・認知で十分です。リポジトリ内の実行可能領域は hooks/ 配下の 9 個の bash スクリプトと build.sh のみです。フックはプラグインホストにより SessionStart および MCP ツール呼び出しの前後に実行されますが、その動作は stdin の読み取り、${TMPDIR}/n8n-mcp-skills-state 配下への重複排除マーカーの書き込み、空のキャッシュディレクトリ作成、固定リマインダー JSON の出力に限定されており、ネットワーク通信、認証情報の読み込み、~/.claude への干渉は行わず、すべてフェイルオープン（異常時は exit 0）となっています。ツールの実機能は外部の n8n-mcp MCP サーバー（ホスト型エンドポイント https://api.n8n-mcp.com/mcp）から提供され、認証情報（N8N_API_URL/N8N_API_KEY）は MCP サーバー側で保持されリポジトリスクリプトが読み取ることはありません。これはホストと MCP サーバー間の信頼境界に属するものであり、本スキルの振る舞いではありません。「ローカルツール/CLI およびローカル読み書きのみ、外部ネットワーク送信なし、認証情報へのアクセスなし」の基準に基づき青判定とします。留意点は 2 点：プラグイン導入時にルーターのマークダウンが全セッションに注入される点（設計意図ですが完全性検証はありません）、セルフホストスキルがリモート環境で 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結論
最適な用途： すでに n8n + n8n-mcp を利用している（または導入を検討している）個人やチームに最適です。特に n8n ノードの詳細設定、式構文、Merge ノードの複数入力の配線など、潜みやすい罠に作業を阻害されがちな環境に適しています。また、「フックを活用して適切なタイミングでスキルを自動ロードさせる手法」を研究したいスキル開発者にとっても、SessionStart + PreToolUse による強制レイヤーは貴重で完成度の高い実装サンプルとなります。n8n を自前で運用するユーザーに対しては、self-hosting スキルが SSH + Compose + Caddy による実践的なデプロイ手順を提供します。
不向きな用途： n8n-mcp（または同等の MCP サーバー）を利用しない環境には適しません。ツールが存在しない場合、スキル層は単なる助言集にとどまり価値が大幅に低下します。また、スキルのプロンプトに「セキュリティの完全な担保」を依存する運用には不向きです。書き込み制限はプロンプト上の規律であり、真の強制力は MCP サーバーおよび n8n 側の権限設計に依存します。再現可能な評価データ（リポジトリ内にテストランナー、CI、テスト通過率のデータはありません）を求める調達・監査プロセスには適していません。さらに、フック機構が存在しない Claude Code / Codex 以外のクライアント環境で「自動ロード」を期待する用途にも適しません。
Install Agent-Ready
① Verified Mirror 2026-09-15
Option A · Direct DownloadDownload n8n-workflow-skills.tar.gz
sha256:
Option B · Copy Guide for Agent9b92af0c1951282e…Agent はこの JSON ガイドから自動的にダウンロードして検証します。
② Upstream GitHub
GitHub Repo ↗
Pinned to commit 2df0f18cb5.