opencode-skills-collection 4.0.7 → 4.0.9

package/bundled-skills/n8n-agents/references/SYSTEM_PROMPT.md

@@ -0,0 +1,151 @@
+# System prompts
+
+The system prompt is the load-bearing config of an agent. Most "the agent isn't doing what I want" problems trace back to a system prompt that's too long, too vague, or mixing concerns.
+
+This file is opinionated: keep system prompts on **persona and global behavior**, push tool-specific instructions into tool descriptions, and iterate. The system prompt goes in `options.systemMessage` on the agent node.
+
+---
+
+## What the system prompt is for
+
+1. **Persona / role.** Who, scope, tone.
+2. **Global output rules.** Format conventions, display protocols (e.g. "show images via `![]()` markdown"), language.
+3. **Refusal and safety behavior.** What the agent should NOT do — prefer specific bounds over generic boilerplate.
+4. **Universal context.** Current date, user's name/role, company/product context.
+5. **Inter-tool flow rules.** "After generating, always show via the display protocol", "confirm before destructive operations" — things that touch multiple tools.
+6. **File-handling injection.** When chat includes uploaded files, inject the storage keys so the agent can reference them in tool calls (mechanics → **n8n-binary-and-data**).
+
+What it is NOT for: per-tool usage instructions. Those go in the tool's description.
+
+---
+
+## Always include the current date
+
+A hardcoded date is stale immediately. Inject it at runtime:
+
+```
+Current date: {{ $now }}
+```
+
+or formatted:
+
+```
+The current time is {{ $now.format('DDDD TTTT') }}
+```
+
+---
+
+## The modular split
+
+```
+System prompt    → Persona, global behavior, format rules, file handling
+Tool description → How to use THIS tool, its parameters, when to pick it over others
+$fromAI desc.    → What value to put in this specific parameter
+```
+
+Why this split:
+
+- **Reuse.** A well-described tool works in any agent; the system prompt doesn't re-teach it.
+- **Token efficiency.** Tool details only "load" when the model considers that tool. Per-tool text in the system prompt burns tokens every turn.
+- **Maintainability.** Update one tool description, not a paragraph buried in a 5000-token prompt.
+
+### What to move where
+
+| Was in the system prompt | Better location |
+|---|---|
+| "When using Generate Image, prefer realistic photography over `8k cinematic`" | `Generate Image` tool description |
+| "When the user uploads an image and asks for background changes, edit it, don't generate new" | `Edit Image` tool description (and a "do not use" boundary on `Generate Image`) |
+| "Use 9:16 aspect ratio for video tools" | `Generate Video` tool description |
+| "Respond with markdown image embeds: `![alt](url)`" | **System prompt** (global display rule) |
+| "Refuse to generate images of real people without consent" | **System prompt** (global safety) |
+| "Today is 2026-04-25" | **System prompt** as `{{ $now }}` (universal context, computed) |
+
+The first three move out; the last three stay in.
+
+---
+
+## Storing the prompt
+
+Inline (typed directly into `systemMessage`) is fine for a first agent or any prompt that lives in one place. A 1500-token inline prompt is a normal shape — don't push first-time builders toward externalization.
+
+The real reason to externalize is **piecing**, not length. Reusable chunks of context — `COMPANY_DESCRIPTION`, `BRAND_VOICE`, `CURRENT_PROMOTION` — each get one canonical home, and every prompt that needs them references that home. Suggest this when you see one of:
+
+- Multiple agents share the same context (same product description, same compliance language).
+- Pieces drift on their own cadence (`COMPANY_DESCRIPTION` quarterly, `CURRENT_PROMOTION` weekly).
+- A non-engineer owns part of the prompt (marketing owns brand voice, legal owns disclosures).
+- You want to A/B test one chunk without touching the rest.
+
+If none apply, stay inline. Mid-prompt restructures cost more than they save with no second consumer to pay them back.
+
+### How piecing works
+
+Load each chunk at workflow start (one node per chunk — a Data Table `Get Row`, an HTTP fetch, a Set node), then reference them inline in `systemMessage` where they should appear:
+
+```
+=You are the assistant for {{ $('Company Description').first().json.value }}.
+
+## Market positioning
+{{ $('Market Fit').first().json.value }}
+
+## Brand voice
+{{ $('Brand Voice').first().json.value }}
+
+Current date: {{ $now }}
+User: {{ $('Lookup').first().json.name }}
+```
+
+Mix sources: a **Data Table** (default for shared chunks, editable in UI), **n8n Variables** (`$vars.X`, paid plans — short shared values like a brand name), or **computed at run time** (`$now`, current user, available files).
+
+---
+
+## Common patterns
+
+### Include
+
+- **Display protocols** for output needing specific formatting (markdown image syntax, link format, code-block conventions).
+- **Conversational style cues** for user-facing agents ("ask one clarifying question before destructive actions").
+- **Boundaries** unique to this agent ("only answer questions about domain X, otherwise redirect").
+- **Universal context** that changes per execution (date, user identity, files).
+
+### Exclude
+
+- **Per-tool usage docs** — move to tool descriptions.
+- **Generic safety language** — built in; reinforcing adds tokens without changing behavior. Reserve for specific risks.
+- **"You are a helpful assistant" preamble** — replace with a specific role.
+- **Lengthy examples that aren't earning their tokens** — one sharp example beats five mediocre ones.
+
+---
+
+## Iteration loop
+
+Treat the system prompt like code:
+
+1. Run the agent on representative inputs.
+2. Note where it does the wrong thing.
+3. Decide: system-prompt fix, tool-description fix, or downstream-validation fix?
+4. Make the smallest change that addresses it.
+5. Re-test on the same inputs PLUS one or two new ones.
+6. Watch for regressions on previously-working inputs.
+
+Most "the agent doesn't follow my instructions" issues are conflicts between the system prompt, tool descriptions, and model defaults. Resolve those conflicts first.
+
+---
+
+## Anti-patterns
+
+| Anti-pattern | Symptom | Fix |
+|---|---|---|
+| "You are a helpful assistant" + no specifics | Generic responses, no identity | Replace with a specific role and scope |
+| 5000-token prompt with a section per tool | Token cost, slow responses, hard to edit | Move tool sections to tool descriptions |
+| Hardcoded date / "current year" | Stale immediately | Inject `{{ $now }}` at runtime |
+| A stack of `DON'T` rules | Model gets defensive, refuses too eagerly | Frame as positive instructions where possible |
+| Multiple pasted "examples" | Cargo-cult, rarely earns its tokens | One sharp example, or none |
+| Per-execution context hardcoded | Hard to update | Build the prompt from a template + variables |
+
+---
+
+## Cross-references
+
+- Tool descriptions as the other half of the split → **TOOLS.md**
+- The system-prompt half of structured output → **STRUCTURED_OUTPUT.md**
+- File-handling injection mechanics → **n8n-binary-and-data**

package/bundled-skills/n8n-agents/references/TOOLS.md

@@ -0,0 +1,199 @@
+# Agent tools
+
+The agent picks tools by reading their **name** and **description** — nothing else. Both are part of the prompt. Treat tool design like API design: what it does, when to use it, what each parameter means, and how it fails.
+
+---
+
+## The four tool types
+
+### 1. Native tool node
+
+Pre-built tool versions of regular nodes: `slackTool`, `gmailTool`, `googleSheetsTool`, `toolCalculator`, `notionTool`, `httpRequestTool`, and so on. Identical to their non-tool counterparts except parameters can be agent-filled via `$fromAI()`.
+
+- **Pros**: minimal config, well-tested, native feel.
+- **Cons**: one node = one operation. Multi-step logic doesn't fit.
+- **Use when**: the capability maps cleanly to one node and one operation.
+
+When a native node is missing an operation or needs a non-standard param shape, point an **HTTP Request Tool** at the service's API with the service's *predefined credential type* — you reuse the existing OAuth/API-key credential and get the full API.
+
+### 2. Sub-workflow as tool (`@n8n/n8n-nodes-langchain.toolWorkflow`)
+
+The default for anything beyond one node. Any workflow becomes a tool with typed `$fromAI()` inputs.
+
+- **Pros**: full power of n8n inside the tool — branching, error handling, sub-sub-workflows, native nodes, custom logic. Reusable across agents. Independently testable.
+- **Cons**: one extra workflow boundary, slight latency.
+- **Use when**: more than one node, logic that might be reused, or you want testability.
+
+The canonical n8n way to build agent capabilities. → **SUBWORKFLOW_AS_TOOL.md**
+
+### 3. HTTP Request Tool (`@n8n/n8n-nodes-langchain.toolHttpRequest`)
+
+A wrapper around the HTTP Request node exposing its parameters to the agent.
+
+- **Pros**: any HTTP API becomes a tool with one node.
+- **Cons**: HTTP only. Auth/retry/error handling are yours to wire.
+- **Use when**: calling a single external API the agent should orchestrate directly.
+
+One thing to know: HTTP Request has its own HTTP-level timeout (default 5 minutes) — bump `options.timeout` for slow endpoints. The agent tool itself has no timeout; the agent waits as long as the tool takes. Pointing it at, say, the Notion API (with the Notion predefined credential) lets the agent compose path, method, and body itself — covering operations the native node doesn't expose. Trade-off: the agent is now writing API requests, which is more error-prone and needs a capable model plus clear endpoint guidance in the description. That widens the blast radius — make sure the user understands.
+
+### 4. MCP Client Tool (`@n8n/n8n-nodes-langchain.mcpClientTool`)
+
+Connects the agent to any MCP server. Two flavors:
+
+- **External MCP servers** — any third-party or self-hosted MCP (GitHub, Linear, Notion, custom internal). One node exposes every tool that server offers.
+- **n8n-hosted MCP** — a workflow on the same instance published with MCP access enabled. Same client node, pointed at an n8n MCP trigger URL. Lets one workflow serve many agents.
+
+- **Cons**: tool descriptions and shapes come from the server, so quality varies and you can't easily tune them. Auth and reachability are yours.
+- **Use when**: a maintained MCP server already covers the capability, or you want one published workflow to serve many agents.
+
+### Plus: Custom Code Tool (`@n8n/n8n-nodes-langchain.toolCode`)
+
+Pure inline computation (math, parsing, formatting). Its runtime contract is **string in / string out, no `$fromAI`, no `$helpers`** and is owned by the **n8n-code-tool** skill — read it before writing one. Rule of thumb: if you want `$fromAI()` in the code, you want `.toolWorkflow` instead.
+
+---
+
+## Decision: which tool type?
+
+```
+Capability the agent needs?
+├── One native node + one operation does it
+│     → native tool node
+├── Native node missing an op / needs custom params for ONE API
+│     → HTTP Request Tool (with the service's predefined credential)
+├── More than one node, or logic that might be reused
+│     → Sub-workflow as tool (.toolWorkflow)   ← default when in doubt
+├── Pure deterministic computation, one-off, inline
+│     → Custom Code Tool (.toolCode)            ← see n8n-code-tool
+└── A maintained MCP server covers it / publish n8n logic to many agents
+      → MCP Client Tool
+```
+
+---
+
+## `$fromAI()`: how the agent fills tool parameters
+
+`$fromAI()` is a **real n8n expression helper**, written inside a tool node's parameter expressions. Parameters the agent should decide get wrapped in it:
+
+```
+sendTo:  ={{ $fromAI('recipient', 'Email address of the recipient', 'string') }}
+subject: ={{ $fromAI('subject', 'Email subject line, concise and informative', 'string') }}
+body:    ={{ $fromAI('body', 'Email body in plain text, professional tone', 'string') }}
+```
+
+Shape: `$fromAI(paramName, description, type?, defaultValue?)`
+
+- **paramName** — the name the model uses internally. snake_case or camelCase, be consistent.
+- **description** — what value to produce. **Part of the prompt.** Be specific: format, range, example.
+- **type** — `'string'` (default), `'number'`, `'boolean'`, `'json'`. Enforced — a wrong-typed value fails the call.
+- **defaultValue** — used when the model omits the parameter.
+
+It carries **JSON only** — it cannot carry binary (no base64, no file bytes), even through a non-AI binding. For binary, pass a storage key as a string and have the tool re-fetch (→ **n8n-binary-and-data**).
+
+A good description vs a useless one:
+
+```
+✅ ={{ $fromAI('imageName', 'Storage key for an existing image to edit, or empty for a new generation. Use the exact key shown in the system prompt; do not reconstruct or guess.', 'string') }}
+
+❌ ={{ $fromAI('imageName', 'image name', 'string') }}   // useless to the model
+```
+
+Treat `$fromAI` descriptions like JSDoc — the model reads them to figure out what to pass.
+
+---
+
+## Plumbed params: hide what the agent shouldn't decide
+
+Not every parameter has to be `$fromAI`. Any parameter can be filled deterministically from workflow context, and **plumbed values are invisible to the agent** — not in the tool schema, not influenceable by anything the model produces:
+
+```
+reason:        ={{ $fromAI('reason', 'Why the user is requesting a refund', 'string') }}   // agent-filled
+customerId:    ={{ $('Chat Trigger').first().json.user.id }}                                 // hidden
+maxRefund:     ={{ $('Get user tier').first().json.refundLimit }}                            // hidden
+idempotencyKey:={{ $('Chat Trigger').first().json.sessionId }}                               // hidden
+```
+
+Plumb anything the agent shouldn't get wrong or see:
+
+- **Identity** — `userId`, `customerId`, authenticated actor, tenant scope.
+- **Authority limits** — refund caps, tier flags, allowed regions.
+- **Correlation IDs** — `sessionId`, idempotency keys, trace IDs.
+
+**Give the agent a button to push, not a steering wheel.** The strongest version is a sensitive tool with **zero `$fromAI` parameters**: a "Refund order" tool takes `orderId` from the trigger, `amount` from the fetched order record, `actor` from the session — all plumbed. The agent literally cannot refund the wrong order; it only chooses whether to fire. Pair with **HUMAN_REVIEW.md** for actions needing both deterministic params and sign-off.
+
+---
+
+## Tool name and description as prompt
+
+Selection process the model runs every turn:
+
+1. It gets the system prompt, conversation, and the list of tools.
+2. For each tool it reads name + description + parameter schema (with `$fromAI` descriptions).
+3. It picks the tool whose description best matches what it needs to do.
+
+**Bad names and descriptions cause bad selection — usually silently.** The model just doesn't call your tool, or calls a different one with garbage parameters. No error.
+
+### Names: verb-first and specific
+
+| Good | Bad | Why |
+|---|---|---|
+| `Search customer database` | `query` / `tool1` | Generic names say nothing |
+| `Generate image with Veo` | `imageGen` | Which generator? |
+| `Edit existing image` | `edit` | Edit what? |
+| `Send Slack message to channel` | `slack` | Name the action, not just the surface |
+| `Lookup user by email` | `getUser` | Lookup how? |
+
+### Descriptions: three parts
+
+1. **What it does** (one sentence).
+2. **When to use it** (one or two sentences, with boundaries / examples).
+3. **Parameter notes** (only if not already covered in `$fromAI` descriptions).
+
+```
+Edit existing image: Modifies an image the user already uploaded, based on a prompt.
+Use when the user uploaded an image and asks for changes (color, style, composition, content).
+Do NOT use for generating new images from scratch — use Generate Image for that.
+The imageName parameter must be the storage key of the existing image as listed in your
+available files; do not pass the original filename or a URL.
+```
+
+That description does work that would otherwise bloat the system prompt — which is exactly the point.
+
+---
+
+## Tool descriptions as modular prompts
+
+Anything specific to *how to call this tool* belongs in the tool's description, not the system prompt:
+
+| In the system prompt (move out) | Better in the tool description |
+|---|---|
+| "When generating images, prefer realistic photography over `8k cinematic`" | `Generate Image`: "Default to realistic photography aesthetics…" |
+| "If the search tool returns nothing, summarize politely" | `Search`: "Returns up to 10 results; if empty, report 'no matches' rather than retrying broader" |
+| "Use 9:16 for video tools" | `Generate Video`: "Defaults to 9:16; pass `aspectRatio: '16:9'` for landscape" |
+
+Three reasons: **reusability** (the tool teaches each new agent how to use it), **token efficiency** (per-tool guidance only loads when the model considers that tool, not every turn), **maintainability** (one description, not a buried paragraph).
+
+---
+
+## Granularity: one tool with branching, not two near-identical tools
+
+The model gets confused choosing between near-identical tools. If two are ~80% the same internally:
+
+- **One tool with a branching parameter.** `Generate Image` vs `Edit Image` share most logic → collapse to one with an `imageName` parameter (empty = generate, populated = edit).
+- **Two tools only when genuinely distinct AND the descriptions clearly differentiate.** `Send DM` vs `Send Channel Message` are distinct.
+
+---
+
+## Operational notes
+
+- **maxIterations.** Agents have a configurable tool-call cap (`options.maxIterations`), and the default is **low**. A multi-tool agent that chains calls hits it and surfaces "max iterations reached" or empty output. Raise it. Build a fallback — don't trust graceful recovery.
+- **Tool-call cost.** Each call is at minimum one extra model round-trip. Frequently-called tools should return **concise** results — bloated returns burn input tokens fast.
+- **Tool failure handling.** Set `onError: 'continueErrorOutput'` on tool sub-workflows where you want the agent to receive an error string instead of halting; the agent can retry, switch tools, or report. → **n8n-error-handling**.
+
+---
+
+## Cross-references
+
+- The sub-workflow tool pattern in detail → **SUBWORKFLOW_AS_TOOL.md**
+- System-prompt-vs-tool-description split → **SYSTEM_PROMPT.md**
+- Passing binary into tools → **n8n-binary-and-data**
+- The Custom Code Tool contract → **n8n-code-tool**

package/bundled-skills/n8n-binary-and-data/SKILL.md

@@ -0,0 +1,269 @@
+---
+name: n8n-binary-and-data
+description: Handle n8n files and binary data across uploads, downloads, transforms, multimodal inputs, agent tools, and chat surfaces.
+risk: unknown
+source: https://github.com/czlonkowski/n8n-skills/tree/main/skills/n8n-binary-and-data
+source_repo: czlonkowski/n8n-skills
+source_type: community
+date_added: "2026-07-21"
+author: Romuald Czlonkowski
+license: MIT
+license_source: https://github.com/czlonkowski/n8n-skills/blob/main/LICENSE
+---
+
+# n8n Binary and Data
+
+## When to Use
+
+Use this skill when an n8n workflow reads, transforms, stores, uploads, downloads, or transmits files and binary fields, including multimodal agent inputs and chat attachments.
+
+Treat uploaded files and generated URLs as potentially sensitive. Obtain approval before sending data to a new external host, use the narrowest retention and access scope available, avoid logging bytes or base64 payloads, and do not embed credentials in URLs or workflow fields.
+
+Every n8n item carries two independent slots: `$json` for structured data and `$binary` for file bytes. They travel side by side through the workflow. File contents — the actual PDF, image, or zip — live in `$binary`, never in `$json`. Get that split wrong and you read an empty field, lose a file mid-flow, or hand an AI agent a tool input it can't use.
+
+This skill covers where binary lives, how to read and write it, how to keep it from being silently stripped, the hard wall between binary and the AI-agent tool boundary, and why chat surfaces need a URL instead of raw bytes.
+
+---
+
+## The three rules that prevent 90% of binary bugs
+
+1. **File contents are in `$binary`, not `$json`.** After an HTTP download, a "Read Files", or an email-attachment trigger, the bytes sit in `$binary.<key>`. `$json` holds metadata at most. Reading `$json.data` for file contents gives you nothing.
+
+2. **Binary cannot cross the AI-agent tool boundary — in either direction.** Tool arguments and tool return values are JSON only. An uploaded image can't be passed into a tool as a file, and a tool can't return raw bytes. Pre-stage to storage and pass a key or URL through JSON instead. See `references/AGENT_TOOL_BINARY.md`.
+
+3. **Chat surfaces render images by URL, not by `$binary`.** Slack, Discord, Teams, Telegram, embedded webhook chat — none of them read the binary slot. The image has to live somewhere a URL can fetch it. See `references/CDN_REQUIREMENT.md`.
+
+---
+
+## The two slots
+
+Each item is shaped like this:
+
+```json
+{
+  "json": { "customerId": 42, "status": "sent" },
+  "binary": {
+    "invoice": {
+      "data": "<base64-encoded bytes>",
+      "mimeType": "application/pdf",
+      "fileName": "invoice-42.pdf",
+      "fileExtension": "pdf"
+    }
+  }
+}
+```
+
+The key inside `binary` (`invoice` here) is the **binary property name**. Most file-handling nodes have a `binaryPropertyName` parameter that points at it — the producer names the slot, the consumer references it by that name. The default key across most nodes is `data`, so when nothing tells you otherwise, assume `$binary.data`.
+
+`$json` and `$binary` are separate namespaces. An expression like `{{ $binary.invoice.fileName }}` reads file metadata; `{{ $json.customerId }}` reads data. They never mix.
+
+This split also explains a webhook gotcha: a Webhook trigger receiving `multipart/form-data` puts the uploaded file in `$binary` and the accompanying form fields in `$json.body` — so an uploaded file is not somewhere under `$json` at all. (The `$json.body` nesting for webhooks is **n8n-expression-syntax** territory.)
+
+See `references/BINARY_BASICS.md` for the full slot anatomy, mime types, and size limits.
+
+---
+
+## Producing binary
+
+You rarely build a `$binary` slot by hand — nodes populate it for you:
+
+| Source | How binary appears |
+|---|---|
+| HTTP Request with `responseFormat: "file"` | Response body lands in `$binary.data` (or the name you set) |
+| Read/Write Files from Disk | File contents read into `$binary` |
+| Storage downloads (S3, Google Drive, Dropbox, etc.) | Downloaded file in `$binary.<key>` |
+| Email triggers with attachments | Each attachment arrives in `$binary` |
+| Provider AI media nodes (image/audio gen) | Set `options.binaryPropertyOutput` so the bytes land where the next node looks |
+
+For an HTTP download, the one field that matters is `responseFormat`. Confirm it with `get_node` on `nodes-base.httpRequest` — leaving it as the default JSON/string format is the classic reason a downloaded file ends up as garbled text in `$json` instead of clean bytes in `$binary`.
+
+---
+
+## Reading and writing binary in a Code node
+
+Most workflows never need to crack open the bytes — they just pass binary through to a consumer (email attachment, file upload, Slack file). When you do need the raw bytes, do it in a Code node.
+
+**Read** with `getBinaryDataBuffer` — do not try to base64-decode `$binary.<key>.data` by hand:
+
+```javascript
+// Code node, "Run Once for Each Item"
+const buffer = await this.helpers.getBinaryDataBuffer(0, 'data'); // (itemIndex, propertyName)
+const text = buffer.toString('utf-8');
+const length = buffer.length;
+
+return [{
+  json: { ...$json, length },
+  binary: $input.item.binary,   // pass the binary through, or it's gone
+}];
+```
+
+**Write** by building the slot yourself — base64 the bytes plus a mime type and file name:
+
+```javascript
+const text = 'Hello, world!';
+return [{
+  json: { ok: true },
+  binary: {
+    report: {
+      data: Buffer.from(text).toString('base64'),
+      mimeType: 'text/plain',
+      fileName: 'report.txt',
+      fileExtension: 'txt',
+    },
+  },
+}];
+```
+
+The Code-node sandbox, helpers, and execution modes are the domain of **n8n-code-javascript** (and **n8n-code-python**) — use those for the language-level detail. The one binary-specific thing to remember here: a Code node that returns `[{ json: {...} }]` without re-attaching `binary` **silently drops the file**. See `references/BINARY_BASICS.md`.
+
+---
+
+## Keeping binary alive across transforms
+
+JSON-only nodes — Edit Fields (Set), Code, IF, and others — can drop the `$binary` slot from their output. The workflow validates clean and runs without error; the file just isn't there downstream when the email node goes to attach it.
+
+Two ways to keep it:
+
+- **Pass-through option on the transforming node.** Edit Fields has `includeOtherFields`; a Code node can return `binary: $input.item.binary` explicitly. Cheapest fix when it's available.
+- **Fan out and Merge by position.** Route the source into both the transform and a bypass branch, then recombine with a Merge in `combineByPosition` mode. The JSON comes from the transform side, the binary survives on the bypass side.
+
+```
+[Source with binary] ─┬─→ [Edit Fields: change JSON] ─┐
+                      │      (binary stripped here)     ├─→ [Merge: combineByPosition] ─→ [Email: attach]
+                      └──────────────────────────────────┘
+                          (bypass — binary passes through untouched)
+```
+
+`combineByPosition` pairs item N from each input, so the field counts must line up. The connection wiring and the alternatives for many-strip-point chains (upload-early, sub-workflow) are in `references/MERGE_FOR_CONTEXT.md`.
+
+---
+
+## The agent-tool binary boundary
+
+This is the sharpest edge. An AI Agent talks to its tools (Custom Code Tool, Call n8n Workflow Tool, HTTP Request Tool, MCP tools) over JSON. Binary does not fit through that pipe in either direction. The fix is the same shape both ways: **stage the bytes in storage, pass a key/URL through JSON, fetch on the other side.**
+
+**Inbound — a user uploads a file the agent's tool must operate on:**
+
+1. The chat trigger gives you a `files[]` array. Split it out and upload each file to private storage under a hashed key.
+2. Re-merge that branch before the agent runs (it's a synchronization barrier, not decoration), and set `executeOnce: true` on the agent so N files don't trigger N agent runs.
+3. Inject the keys into the agent's system prompt, listing both the original name (human context) and the storage key (what the tool needs), with an explicit "use EXACTLY this key".
+4. The tool receives the key as a string argument and downloads the file from storage itself.
+
+**Outbound — a tool generates a file the agent must return:**
+
+1. The tool sub-workflow generates the binary, uploads it to storage, and returns JSON like `{ "ok": true, "key": "...", "url": "https://...", "mimeType": "image/png" }`.
+2. The agent embeds the URL in its reply (or passes the key to another tool).
+
+`passthroughBinaryImages: true` on the agent only changes what the **LLM sees** for vision — it does **not** let tools receive the file, and it's image-only (no PDFs, audio, or video). You still need the upload-and-pass-key pattern for any tool. Full patterns, hash strategy, storage choices, and the long-running-tool variant are in `references/AGENT_TOOL_BINARY.md`.
+
+> Building the tool itself? See **n8n-code-tool** for the Custom Code Tool contract and **n8n-workflow-patterns** for the AI-Agent-with-tools shape.
+
+---
+
+## The CDN requirement for chat surfaces
+
+When a workflow generates an image and the user wants it shown inside a chat message:
+
+- **Binary on the item isn't enough.** The chat client renders messages that reference images by URL (or pushes bytes through the platform's own file-upload API). It never reads `$binary`.
+- **The bytes have to live somewhere a URL can fetch over HTTPS.** Upload to an object store or drive first, then embed the returned URL.
+- **n8n has no built-in CDN.** The user provides the storage.
+
+Ask which storage they already use rather than defaulting to S3 — object storage (S3, R2, GCS, Azure Blob, Backblaze B2, Supabase Storage) and drive-style services (Dropbox, Google Drive, OneDrive, Box) all work and all change the URL shape. Cloudflare R2 is the lowest-friction starting point if they have nothing. For sensitive content, use a signed URL with an expiry rather than a permanently public one. See `references/CDN_REQUIREMENT.md`.
+
+---
+
+## What's NOT available
+
+- **`$fromAI()` cannot carry binary.** It fills tool parameters with strings, numbers, booleans, and objects — never file bytes. Pass a storage key instead.
+- **Tool arguments and returns are JSON only.** There is no "binary parameter" on an agent tool, in or out.
+- **n8n ships no CDN or public file host.** Serving a file over a URL is always something the user's storage does, not n8n.
+- **`getBinaryDataBuffer` is a Code-node helper.** It isn't available in the Custom Code Tool sandbox (see **n8n-code-tool**).
+
+---
+
+## Where Data Tables live
+
+For persistent tabular storage — reference-counting staged files, tracking which keys are live, dedup — that's the `n8n_manage_datatable` surface, owned by **n8n-mcp-tools-expert**. This skill does not cover Data Tables.
+
+---
+
+## Anti-patterns
+
+| Anti-pattern | What goes wrong | Fix |
+|---|---|---|
+| Reading file contents from `$json` | Bytes live in `$binary`; `$json` is empty or metadata only | Read `$binary.<key>`, or `getBinaryDataBuffer` in a Code node |
+| HTTP download without `responseFormat: "file"` | Bytes arrive as mangled text in `$json`, not clean binary | Set `responseFormat: "file"` on the HTTP Request node |
+| Code node returns `[{json:{...}}]`, no `binary` | The file is silently dropped downstream | Re-attach `binary: $input.item.binary` in the return |
+| JSON transform (Edit Fields/IF) eats the binary | Email/upload node finds nothing to attach | Pass-through option, or fan out + Merge by position |
+| Passing an uploaded file into a tool via `$fromAI` | `$fromAI` can't carry binary; the tool gets nothing | Pre-stage to storage, inject the key in the system prompt, tool fetches by key |
+| Assuming `passthroughBinaryImages` lets tools see the file | It only affects what the LLM sees, and only for images | Still need the upload-and-pass-key pattern for tools |
+| Tool returns raw binary to the agent | Tool output is JSON; bytes don't survive (and bloat context) | Upload, return `{ key, url }` in JSON |
+| Posting `$binary` to a chat surface and expecting an image | Chat clients render by URL, not raw bytes | Upload to storage/CDN, embed the URL or use the platform file API |
+| Hardcoding base64 in a Code node | Huge workflow JSON, slow, leaky | Reference via `$binary`, or upload and reference by URL |
+
+---
+
+## Reference files
+
+| File | Read when |
+|---|---|
+| `references/BINARY_BASICS.md` | First time handling binary, or reading/writing the `$binary` slot, mime types, size limits |
+| `references/AGENT_TOOL_BINARY.md` | An agent tool needs an uploaded file, or produces one — the boundary in either direction |
+| `references/MERGE_FOR_CONTEXT.md` | Binary disappears after a JSON transform and you need to re-attach it |
+| `references/CDN_REQUIREMENT.md` | Showing images in a chat surface or anywhere that needs URL-referenced images |
+
+---
+
+## Integration with Other Skills
+
+**n8n-code-javascript / n8n-code-python**: the Code node is where you read/write raw bytes (`getBinaryDataBuffer`, `Buffer.from(...).toString('base64')`). Those skills own the sandbox, helpers, and execution-mode detail — this skill owns the rule that binary must be re-attached on return.
+
+**n8n-code-tool**: the Custom Code Tool sandbox is narrower — no `$binary`, no `getBinaryDataBuffer`, no `$fromAI`. When a tool needs a file, this skill's storage-key pattern is how it gets one.
+
+**n8n-workflow-patterns**: the agent-tool binary boundary sits inside the AI-Agent-with-tools pattern; the CDN flow is a generate → upload → reply chain.
+
+**n8n-node-configuration**: `responseFormat`, `binaryPropertyName`, `includeOtherFields`, `binaryPropertyOutput` are all conditional fields — use `get_node` to confirm the exact names on the user's version.
+
+**n8n-expression-syntax**: addressing `$binary.<key>.fileName` vs `$json.body` (webhook uploads in particular) is expression territory.
+
+**n8n-validation-expert**: a dropped binary slot is a silent failure — `validate_workflow` won't flag it. Confirm presence by inspecting the execution.
+
+**n8n-mcp-tools-expert**: owns `n8n_manage_datatable` (Data Tables) and `n8n_executions` — use the latter to confirm a `binary` slot actually survived a given node.
+
+**n8n-error-handling**: storage uploads and downloads fail; the inbound/outbound staging steps need error branches so a missing key doesn't 404 silently.
+
+**using-n8n-mcp-skills**: the index of how these skills fit together.
+
+---
+
+## Verifying binary survived
+
+Validation won't catch a stripped binary slot — it's a silent failure. Confirm it ran correctly:
+
+1. `n8n_test_workflow` (or trigger a real run) to produce an execution.
+2. `n8n_executions` to pull that execution, and inspect per-node output for the `binary` slot — it shows presence and metadata even if the base64 is too large to render.
+3. The node where `binary` last appears is the node before the strip. That's where the pass-through or Merge goes.
+
+---
+
+## Quick Reference Checklist
+
+- [ ] File contents read from `$binary.<key>` — never `$json`
+- [ ] HTTP downloads use `responseFormat: "file"`
+- [ ] Code nodes re-attach `binary` on return when the file must continue
+- [ ] JSON transforms either pass binary through or Merge it back (`combineByPosition`)
+- [ ] No attempt to pass binary into/out of an agent tool — keys/URLs through JSON instead
+- [ ] `passthroughBinaryImages` used only for LLM vision, not as a tool channel
+- [ ] Chat-surface images uploaded to storage; the URL is embedded, not the bytes
+- [ ] Storage backend chosen with the user (not defaulted to S3); signed URLs for sensitive content
+- [ ] Binary presence confirmed by inspecting the execution, not by validation
+
+---
+
+**Remember**: two slots, side by side. Data rides in `$json`, files ride in `$binary` — and the moment a file has to cross an agent tool or reach a chat surface, it travels as a URL, not as bytes.
+
+## Limitations
+
+- Storage limits, binary modes, and node-specific field names vary across n8n versions and hosting configurations.
+- An n8n validation pass cannot prove that file bytes survived a live execution; inspect execution data with a safe sample.
+- This skill does not choose a storage provider or authorize uploading sensitive data to one.