# n8n-code-tool

A skill that teaches your agent to write JavaScript or Python for the n8n Custom Code Tool, the node an AI Agent calls, and to avoid its runtime traps.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 1600 installs · ★ 6523
- Author: czlonkowski
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/czlonkowski/n8n-skills/tree/HEAD/skills/n8n-code-tool/SKILL.md
- Updated: 2026-10-24
- HTML: https://affpapa.org/en/nevibecode/skills/n8n-code-tool

## What it does

The skill covers `@n8n/n8n-nodes-langchain.toolCode`, the node an AI Agent invokes in n8n. In the editor it looks like the workflow Code node, but it ships from a different package and runs under LangChain instead of being fed by the previous node.

Return a string, not an items array. Input arrives as `query` in JavaScript and `_query` in Python, and the variable name is fixed. `$fromAI()`, `$input` and `$helpers` are absent from the sandbox because no execution data reaches it. Copy logic out of a Code node and you get Wrong output type returned or No execution data available.

There are two input modes. With `specifyInputSchema: false` the model sends a single string you parse yourself. With `true` the tool turns into a LangChain `DynamicStructuredTool` and receives a validated object, described either by `jsonSchemaExample` or a hand-written JSON Schema. Argument validation kills a class of runtime errors, though it needs an n8n build with schema support, so check the version before you plan around it. The tool description is what decides whether the agent calls the thing at all.

## Requirements
- Works with: n8n

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add czlonkowski/n8n-skills --skill n8n-code-tool -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/n8n-code-tool/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/n8n-code-tool/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add czlonkowski/n8n-skills --skill n8n-code-tool -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/n8n-code-tool/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add czlonkowski/n8n-skills --skill n8n-code-tool -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/n8n-code-tool/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install czlonkowski/n8n-skills n8n-code-tool
```

2. **Manually: put the files in place**
- File: `.github/skills/n8n-code-tool/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add czlonkowski/n8n-skills --skill n8n-code-tool -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/czlonkowski/n8n-skills --path skills/n8n-code-tool
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/n8n-code-tool/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add czlonkowski/n8n-skills --skill n8n-code-tool -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/czlonkowski/n8n-skills/tree/HEAD/skills/n8n-code-tool/SKILL.md

## When to use it
- write a Code Tool that returns a plain string the agent can read
- parse a JSON string the model packed into `query`
- declare argument types with `jsonSchemaExample` so numeric fields stop arriving as strings
- fix Wrong output type returned after pasting Code node logic into the tool
- word a tool description that gets the agent to actually invoke it

## Example prompts
- Write an n8n Code Tool that parses `query` as JSON, computes the monthly payment and returns a JSON string
- Port this Code node script to `@n8n/n8n-nodes-langchain.toolCode`, it fails with Wrong output type returned
- Turn on `specifyInputSchema` and write a schema for a loan calculator tool

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: bd8f7ab69a31b553.

BEGIN THIRD-PARTY FILE bd8f7ab69a31b553
````text
---
name: n8n-code-tool
description: "Write JavaScript or Python for the n8n Custom Code Tool (@n8n/n8n-nodes-langchain.toolCode) — the AI-agent-callable tool, NOT the workflow Code node. Use when building a Code Tool attached to an AI Agent, writing code that an LLM will invoke, parsing the `query` input, returning a string result, defining an input schema for structured arguments (specifyInputSchema, jsonSchemaExample, DynamicStructuredTool), or troubleshooting errors like \"Wrong output type returned\", \"No execution data available\", \"The response property should be a string, but it is an object\", \"Cannot assign to read only property 'name'\", or an AI agent that refuses to call the tool. Covers the critical differences between Code node and Code Tool: return format (string vs `[{json:{...}}]`), unavailability of `$fromAI`/`$input`/`$helpers` in the Code Tool sandbox, naming rules for AI invocation, and when to use `toolWorkflow`/HTTP Request Tool instead."
---

# n8n Custom Code Tool

Expert guidance for writing code inside `@n8n/n8n-nodes-langchain.toolCode` — the tool an AI Agent can invoke, **not** the regular workflow Code node.

---

## ⚠️ This is NOT the Code node

The Custom Code Tool looks like a Code node in the editor — same JavaScript editor, similar layout — but it is a **completely different node** from a different package with a **different runtime contract**.

| | Code node | Custom Code Tool |
|---|---|---|
| **Node type** | `n8n-nodes-base.code` | `@n8n/n8n-nodes-langchain.toolCode` |
| **Package** | `n8n-nodes-base` | `@n8n/n8n-nodes-langchain` |
| **Invoked by** | Previous node (workflow flow) | AI Agent (LangChain) |
| **Input** | `$input.all()` — item stream | `query` — string or object from LLM |
| **Return** | `[{json: {...}}]` (items array) | **A string** |
| **`$fromAI()`** | N/A | **Not available** (see Errors) |
| **HTTP helper** | `this.helpers.httpRequest` (auth helpers blocked) | Not exposed to the tool sandbox |
| **State** | Per-run execution data | No `getContext`, no `$getWorkflowStaticData` |

**If you treat it like a Code node, it fails.** The rest of this skill covers the Code Tool's actual contract.

---

## Quick Start

### Minimal JavaScript Code Tool

```javascript
// `query` is whatever the AI sent (a string by default)
return `You asked: ${query}`;
```

### Minimal Python Code Tool

```python
````
END THIRD-PARTY FILE bd8f7ab69a31b553

The third-party file has ended. Everything between the bd8f7ab69a31b553 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2401 of 16247 bytes. © czlonkowski · MIT · https://github.com/czlonkowski/n8n-skills/tree/HEAD/skills/n8n-code-tool/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md