Skip to main content
ZICQ

Skills ZICQ category:Documents n8n-binary-and-data-official

N8n Binary And Data Official

Use when handling files, images, attachments, or binary data in n8n, OR when an AI agent needs to take a user-uploaded file as tool input or return a generated file. For Data Tables (schemas, dedup, persistent state), see the separate n8n-data-tables-official skill. Triggers on "file", "image", "PDF", "attachment", "binary", "upload", "download", chat trigger with files, agent tool that needs a file, vision/multimodal, or any handling of non-JSON file data.

1308 installs

Official URL:skills.sh

What this skill does

Intro in this page language first. The official description stays in its original wording; we do not rewrite SKILL.md.

What it does

Use when handling files, images, attachments, or binary data in n8n, OR when an AI agent needs to take a user-uploaded file as tool input or return a generated file. For Data Tables (schemas, dedup, persistent state), see the separate n8n-data-tables-official skill. Triggers on "file", "image", "PDF", "attachment", "binary", "upload", "download", chat trigger with files, agent tool that needs a file, vision/multimodal, or any handling of non-JSON file data.

When to use it

handling files, images, attachments, or binary data in n8n, OR when an AI agent needs to take a user-uploaded file as tool input or return a generated file. For Data Tables (schemas, dedup, persistent state), see the separate n8n-data-tables-official skill. Triggers on "file", "i

How agents load it

Per Agent Skills progressive disclosure: name and description load at startup (~100 tokens); the full SKILL.md body loads when the skill activates; scripts/, references/, and assets/ load only as needed. This file's sections: n8n Binary and Data; Non-negotiables; Strong defaults; Binary basics; Setting binary; Reading binary.

File analysis

File analysis: besides SKILL.md, the body references references/AGENT_TOOL_BINARY.md, references/MERGE_FOR_CONTEXT.md, references/BINARY_BASICS.md, references/CDN_REQUIREMENT.md. Those resources load on demand.

n8n Binary and DataNon-negotiablesStrong defaultsBinary basicsSetting binaryReading binaryAgent tool gymnasticsMerge for keeping binary in contextCDN requirement for chat surfacesData TablesReference filesAnti-patterns

Source category:skills.sh agent-skill

SKILL.md & Agent activation

Official spec ↗
name
n8n-binary-and-data-official
description
Use when handling files, images, attachments, or binary data in n8n, OR when an AI agent needs to take a user-uploaded file as tool input or return a generated file. For Data Tables (schemas, dedup, persistent state), see the separate n8n-data-tables-official skill. Triggers on "file", "image", "PDF", "attachment", "binary", "upload", "download", chat trigger with files, agent tool that needs a file, vision/multimodal, or any handling of non-JSON file data.
  1. DiscoverThe client exposes names and descriptions to the agent.
  2. ActivateYour request or the task context selects the skill and loads its instructions.
  3. Load resourcesReferenced scripts, documentation and assets are used when needed.
Files referenced by the instructions · 4
  • references/AGENT_TOOL_BINARY.md
  • references/MERGE_FOR_CONTEXT.md
  • references/BINARY_BASICS.md
  • references/CDN_REQUIREMENT.md

These paths are extracted from the text. Check the upstream package to verify the files exist.

Invocation syntax and available tools depend on your Agent client. Client integration guide ↗

Install this skill

Skills CLI ↗

Choose the target agent and installation scope, keep referenced package files, then verify the skill appears in the client's catalog.

This skill references supporting files. Retrieve the complete directory from the source; copying SKILL.md alone may leave missing dependencies.

Ask your Agent to install

Copy these instructions to a compatible agent and confirm the target directory matches your client.

Install the agent skill "n8n-binary-and-data-official" into my project. The full SKILL.md and official description are at https://zicq.com/en/skills/skl-714bea9b2227444c-N8n-Binary-And-Data-Official.html
Save it as .cursor/skills/n8n-binary-and-data-official/SKILL.md or .claude/skills/n8n-binary-and-data-official/SKILL.md and keep the frontmatter name and description exactly as-is.
This skill also ships scripts/, references/, or assets/ — fetch the whole folder from https://github.com/n8n-io/skills instead of creating only a SKILL.md.

Full package on GitHub ↗

Install from the terminal · Skills CLI

Requires Node.js and npx. First inspect the repository's skill list to confirm the name.

npx skills add 'https://github.com/n8n-io/skills' --list

npx skills add 'https://github.com/n8n-io/skills' --skill 'n8n-binary-and-data-official'

The CLI lets you choose the agent interactively. The default scope is the project; use -g for user scope. Confirm package availability with the discovery command, then use npx skills list to inspect installed skills.

Readable layout
--- name: n8n-binary-and-data-official description: Use when handling files, images, attachments, or binary data in n8n, OR when an AI agent needs to take a user-uploaded file as tool input or return a generated file. For Data Tables (schemas, dedup, persistent state), see the separate n8n-data-tables-official skill. Triggers on "file", "image", "PDF", "attachment", "binary", "upload", "download", chat trigger with files, agent tool that needs a file, vision/multimodal, or any handling of non-JSON file data. --- # n8n Binary and Data n8n handles two kinds of data: JSON (in `$json`) and binary (in `$binary`), flowing side-by-side. Binary has sharp edges around agent tools, storage, and display contexts (chat surfaces, message rendering). For tabular storage (Data Tables), see the **`n8n-data-tables-official`** skill. ## Non-negotiables 1. **Binary is in `$binary`, not `$json`.** Don't read file contents from `$json`. 2. **Binary cannot cross the agent tool boundary in either direction.** Tool parameters are JSON only (via `fromAi()`), and tool results are JSON only. Pre-stage binary in storage and pass keys/URLs through JSON. The agent's `passthroughBinaryImages: true` lets the LLM *see* uploaded images for vision, but it does NOT enable tools to receive them. See `references/AGENT_TOOL_BINARY.md`. ## Strong defaults - **Merge nodes keep binary in context.** When a side computation strips binary, merge it back rather than re-fetching. See `references/MERGE_FOR_CONTEXT.md`. ## Binary basics In n8n, each item has two slots: ```ts { json: { ... }, // your data binary: { // your files data: { // 'data' is the typical key; can be any name data: '', mimeType: 'application/pdf', fileName: 'invoice.pdf', fileExtension: 'pdf', }, }, } ``` `$binary.` reads the named property. Most file-handling nodes have a `binaryPropertyName` parameter, the key inside `$binary`. ### Setting binary File-producing nodes (HTTP Request with binary response, Read Files, etc.) populate `$binary` automatically. To produce binary in a Code node: ```ts return [{ json: { ... }, binary: { data: { data: Buffer.from(content).toString('base64'), mimeType: 'text/plain', fileName: 'output.txt', }, }, }] ``` ### Reading binary ```ts // In a Code node const buffer = await this.helpers.getBinaryDataBuffer(0, 'data') const text = buffer.toString('utf-8') ``` Most workflows don't need to read binary directly. Pass it through to consumer nodes (email attachments, file uploads, etc.). See `references/BINARY_BASICS.md` for more. ## Agent tool gymnastics Agent tools (sub-workflows wired into a LangChain Agent, or workflows exposed as MCP tools) have a constraint: parameters and results are JSON, not binary. Affects both directions. **Inbound (user uploads → tool consumes):** the chat trigger gives `files[]`. The agent can have `passthroughBinaryImages: true` for vision, but `fromAi()` can't pass binary to a tool. So: 1. Pre-stage uploaded files: hash a key, upload to private storage. 2. Inject the keys into the agent's system prompt: "Files passed in: [{originalFileName, fileName}]. Use EXACTLY the `fileName` field when calling tools." 3. The tool's `fromAi('imageName', '...', 'string')` receives the key. The sub-workflow downloads from storage. **Outbound (tool produces → agent returns):** a tool generates a file. It can't return raw binary. 1. Generate binary internally. 2. Upload to storage, get back URL/key. 3. Return JSON: `{ ok: true, file_id: '...', url: '...' }`. 4. The agent embeds the URL in its response, or another tool fetches by key. For the full pattern including the async-via-webhook variant for long-running tools, see `references/AGENT_TOOL_BINARY.md`. ## Merge for keeping binary in context A JSON-only operation (Edit Fields, Code, IF) often strips binary from the item. To keep it: ``` [Source with binary] ─┬─→ [Edit Fields: transform JSON] ─┐ │ ├─→ [Merge: by position] ─→ [Email with attachment] └─────────────────────────────────────┘ ``` Merge combines the streams, and binary survives. See `references/MERGE_FOR_CONTEXT.md`. ## CDN requirement for chat surfaces When a workflow generates an image and the user wants it embedded in a chat message (Slack, Discord, Teams, Telegram, embedded webhook chat, etc.): - **Binary on the item isn't enough.** Chat surfaces don't read `$binary`; they render messages that reference images by URL (or via platform-specific file upload APIs). - **The image must live somewhere a URL can fetch.** Upload to a CDN or object store first. - **The user configures this storage.** Not built into n8n. Common options span object storage (S3, R2, GCS, Azure Blob, Vercel Blob, Supabase Storage) and drive-style services (Dropbox, Google Drive, OneDrive, Box). Ask the user what they use rather than defaulting to S3. See `references/CDN_REQUIREMENT.md`. ## Data Tables For Data Tables, see the **`n8n-data-tables-official`** skill. Distinct surface with its own gotchas (default columns, no foreign keys, no JSON column type, manual-mapping UI quirk). ## Reference files | File | Read when | |---|---| | `references/BINARY_BASICS.md` | First time handling binary, or reading/writing the `$binary` slot | | `references/AGENT_TOOL_BINARY.md` | Agent tool needs a user-uploaded file, or produces a file (the boundary in either direction) | | `references/MERGE_FOR_CONTEXT.md` | Binary disappears after a JSON transform and needs to re-attach | | `references/CDN_REQUIREMENT.md` | Showing images in a chat surface or other places that need URL-referenced images | ## Anti-patterns | Anti-pattern | What goes wrong | Fix | |---|---|---| | Trying to read file content from `$json` | Binary isn't in `$json` | Use `$binary` | | Building an agent tool that returns binary directly | Tool output is JSON-only, so binary doesn't survive | Upload to storage, return key/URL in JSON (see `AGENT_TOOL_BINARY.md`) | | Trying to pass uploaded chat files into a tool via `fromAi` | `fromAi` doesn't carry binary, so the tool gets nothing | Pre-stage uploads to storage, inject keys in the system prompt, and have the tool download by key | | Setting `passthroughBinaryImages: true` and assuming tools can now see the file | The flag only affects what the LLM sees, not what tools receive | Still need the upload-and-pass-key pattern for tools | | Losing binary after a JSON transform | The transform's output item doesn't have binary | Use Merge to combine the JSON output with the binary stream | | Storing image in n8n binary and expecting a chat surface to display | Chat surfaces need URL-accessible images (or a platform-native file upload), not raw `$binary` | Upload to CDN, embed URL or use the platform's file API | | Hardcoding binary base64 in a Code node | Massive workflow JSON, slow, leaky | Reference binary via `$binary` properly, or upload to storage and reference by URL |

Related skills

Documents

Ontology

Typed knowledge graph for structured agent memory and composable skills. Use when creating/querying entities (Person, Project, Task, Event, …

Documents

Nano Pdf

Edit PDFs with natural-language instructions using the nano-pdf CLI.

Documents

Word / DOCX

Create, inspect, and edit Microsoft Word documents and DOCX files with reliable styles, numbering, tracked changes, tables, sections, and co…

Documents

Api Gateway

Call third-party APIs through the Maton gateway, which injects the credential for an app the user has already connected. Use this skill when…