A pattern shows up the moment teams start using AI agents with n8n: the agent has rough familiarity with MCP but misses the specifics. It forgets to publish workflows before calling them. It guesses at input shapes. It doesn't know that tokens are per-user, not per-instance.
Re-explaining all of that every session is wasted time. The fix is a skill file — a short reference the agent loads automatically at the start of every conversation, so the constraints are already in context before the first prompt.
What a skill file is
A skill file is a markdown document with a small YAML frontmatter block, placed in a folder the agent watches. The format is identical across Claude Code, Codex, Kimi, Cursor, and most other MCP-compatible agents:
---
name: n8n-instance-mcp
description: Use when connecting an AI agent to an n8n instance via MCP — to list, run, build, or debug workflows.
---
# n8n Instance MCP
...reference content...
The description field is the load-bearing part. The agent reads it to decide whether the skill is relevant for the current task. Descriptions that start with "Use when…" and name specific situations work far better than vague ones — the agent uses them as triggers, not summaries.
Install the public skills
There's a public repo at github.com/arturl95/n8n-agent-skills. Two skills:
-
n8n-instance-mcp— setup, auth, execution patterns, common mistakes for n8n's instance-level MCP -
n8n-workflow-trigger-mcp— exposing a single workflow as its own MCP endpoint with typed inputs
Claude Code
Drop everything into the project's skills folder:
git clone https://github.com/arturl95/n8n-agent-skills .claude/skills/n8n
Or pick one skill:
mkdir -p .claude/skills
curl -o .claude/skills/n8n-instance-mcp.md \
https://raw.githubusercontent.com/arturl95/n8n-agent-skills/main/n8n-instance-mcp/SKILL.md
Claude Code picks up any markdown file in .claude/skills/ automatically.
Codex
mkdir -p ~/.codex/skills
curl -o ~/.codex/skills/n8n-instance-mcp.md \
https://raw.githubusercontent.com/arturl95/n8n-agent-skills/main/n8n-instance-mcp/SKILL.md
Kimi K2 / Cursor / Windsurf
Each has its own skills or rules directory. Drop the markdown file there and it gets loaded into context the same way.
What the agent actually learns
After installing the instance-MCP skill, the agent stops getting tripped up on:
-
Workflows must be published and "Available in MCP" — toggling one without the other does nothing
-
Tokens are per-user, so different teammates need different tokens
-
Listing workflows first is more reliable than guessing names — n8n keys on IDs internally
-
Reverse proxies often strip
Authorizationheaders or buffer SSE; that's the usual self-hosted failure mode -
Building or updating workflows from prose requires n8n 1.88+
That's a category of back-and-forth that disappears the moment the skill is loaded.
Write skills for your own instance
The bigger payoff is writing skills for your specific n8n setup — your workflow names, your inputs, your conventions. A good one looks like:
---
name: acme-workflows
description: Use when working with ACME Corp's n8n instance — covers available workflows, expected inputs, and gotchas for our internal automations.
---
# ACME Corp n8n Workflows
MCP endpoint: https://acme.app.n8n.cloud/mcp
## Send Lead to CRM
Triggered for new leads. Inputs: email (string), source (string).
Note: Only works for domains in `approved_domains.json` — check first.
## Generate Weekly Report
No inputs. Runs Fridays automatically; can also be triggered manually.
Returns: { report_url, row_count }
## Slack Incident Alert
Inputs: severity ("low"|"medium"|"high"), message (string).
High severity pages on-call directly — use sparingly.
A skill like that captures the why and the gotchas — the things that aren't obvious from a workflow name alone.
The setup that works in practice
Three pieces, and you're done:
- One generic skill from the public repo — covers MCP mechanics
- One project-specific skill — your workflows, your inputs, your conventions
.mcp.jsonwith your token (in.gitignore)
After that, anyone on the team can open Claude Code in the project and start triggering and building workflows immediately. No setup walkthrough required.
Contributing
Found a pattern missing from the public skills? An edge case that bit you on self-hosted? PRs are open at github.com/arturl95/n8n-agent-skills. The goal is to make agent-plus-n8n setup take under five minutes.
