n8n:create-skill

A skill is a short document that teaches an AI assistant one specific job, and this is how to write one so the assistant actually finds it and follows it.

WHEN TO USE

SCOPE

USE FOR

Scaffold a new skill file with its name and description set up correctly at the top.
Decide whether a workflow needs one skill or should split into smaller composed skills.
Place a new skill in the right directory for team-shared or personal use.
Check a drafted skill against n8n's authoring rules and anti-patterns before shipping it.

This is a saved copy of the skill's SKILL.md instructions. It may differ from the upstream file or the version you install.

In this document (9)

Creating skills

Skills are markdown (plus optional scripts) that teach the agent a focused workflow. Keep SKILL.md short—the context window is shared with chat, code, and other skills.

Where skills live

Location	When to use
`.agents/skills/<name>/`	Default for n8n: team-shared, versioned, agent-neutral source.
`.claude/plugins/n8n/skills/<name>/`	Claude-specific override, or a generated symlink to `.agents/skills/<name>/`.
`.opencode/skills/<name>/`	OpenCode-specific override only. Shared skills stay in `.agents/skills/<name>/`.
`~/.claude/skills/<name>/`	Personal skill for Claude Code across all projects.
`~/.config/opencode/skills/<name>/`	Personal skill for OpenCode across all projects.
`~/.cursor/skills/<name>/`	Optional personal skill for Cursor only, global to your machine.

Do not put custom skills in ~/.cursor/skills-cursor/—that is reserved for Cursor’s built-in skills.

Prefer .agents/skills/ for anything that should match how the rest of the team works. Run pnpm sync:skill-links after adding or removing shared skills.

Before you write: gather requirements

Ask (or infer) briefly:

Purpose — one concrete task or workflow.
Triggers — when should the agent apply this skill?
Gaps — what does the agent not already know (project rules, URLs, formats)?
Outputs — templates, checklists, or strict formats?
Examples — follow an existing shared skill in .agents/skills/ if one fits.

Ask the user in plain language when you need more detail.

File layout

skill-name/
├── SKILL.md       # required
├── reference.md   # optional — detail the agent reads only if needed
├── examples.md    # optional
└── scripts/       # optional

Frontmatter (required)

---
name: n8n:skill-name      # n8n:<name> — lowercase, hyphens, max 64 chars
description: >-         # max 1024 chars, non-empty — see below
  ...
---

Name — shared n8n skills use the n8n:<name> form so Claude Code namespaces them under the n8n plugin (invoked as /n8n:<name>). The <name> part must match the skill's directory name.

Description (discovery is everything — third person, WHAT + WHEN, trigger words):

Good: Extracts tables from PDFs and fills forms. Use when the user works with PDFs, forms, or document extraction.
Bad: Helps with documents or I can help you with PDFs

Authoring rules

Concise — assume the model is capable; only add non-obvious domain or project facts.
Progressive disclosure — essentials in SKILL.md; long reference in reference.md. Link one level deep from SKILL.md.
Prefer one default — e.g. one library or one workflow; add an escape hatch only if needed.
Stable wording — one term per concept; avoid dated “until month X” notes unless you tuck legacy bits behind a short “Deprecated” note.
Paths — forward slashes only (scripts/foo.py).

Rough size: aim for well under ~200 lines in SKILL.md; if it grows, split detail out.

Scope: one job per skill (and parent skills)

Single responsibility — one primary workflow or decision tree per skill. If triggers and steps diverge a lot (e.g. “create issue” vs “create PR” vs “full ticket → PR flow”), split into smaller dedicated skills.
Prefer small + compose — two or three focused skills keep irrelevant detail out of context until needed. A parent (orchestrator) skill can say when to follow each child workflow and link to their SKILL.md; avoid pasting full child content into the parent.
When one large skill is OK — a single end-to-end flow that always runs together and shares one tight checklist;

MCPs, CLI tools, and other skills

Prefer CLI and repo commands when they solve the same problem — agents handle them well and they usually add less scaffolding noise to context than MCP tool discovery and schemas. Examples: gh for PRs/issues, pnpm scripts from AGENTS.md.
MCPs are optional per user — not everyone has the same servers enabled. If a skill requires a specific MCP to work as written, say so explicitly:
- Put a hint in the frontmatter description (e.g. “Requires Linear MCP for …”) so mismatches are obvious early.
- Add a short Prerequisites (or Requirements) block near the top: which integration, what it is used for, and a fallback (e.g. web UI, gh, or “ask the user to paste …”) when it is missing.
Referencing other skills — use the harness-visible invocation name (e.g. n8n:create-issue where namespacing is available, otherwise create-issue). For human-readable links, give the canonical path from the repo root (e.g. .agents/skills/create-issue/SKILL.md). From a sibling folder, a relative link works too: [create-issue](../create-issue/SKILL.md). Parent skills should delegate steps instead of duplicating long procedures.

Patterns (pick what fits)

Template — give the exact output shape (markdown/code blocks).
Checklist — numbered or - [ ] steps for multi-step work.
Branching — “If A → …; if B → …” at the top of a workflow.
Scripts — document run commands; say whether to execute or read the script.

Workflow: create → verify

Name + description — hyphenated name; description with triggers.
Outline — minimal sections; link optional files.
Implement — SKILL.md first; add reference.md / scripts/ only if they save tokens or reduce errors.
Check — third-person description; terminology consistent; no duplicate encyclopedic content the model already knows.

Anti-patterns

Verbose tutorials (“what is a PDF”) inside the skill.
Many equivalent options with no default.
Vague names (helper, utils).
Deep chains of linked files.
Assuming an MCP or tool is present without stating it or offering a fallback.
One oversized skill that mixes unrelated workflows instead of smaller skills + a thin parent.

Quick example stub

---
name: n8n:my-workflow
description: Does X using project convention Y. Use when the user asks for X or mentions Z.
---

# My workflow

1. …
2. …

## Output format

Use a fenced code block for the exact shape reviewers should see.

## More detail
See [reference.md](reference.md) if edge cases matter.

Install this skill from n8n-io/n8n on GitHub, not from a copy somewhere else. The command below does this for you.

Run this outside your AI tool, using Node.js 22.20.0 or newer. Skills CLI 1.7.2 skips skill selection; prompts cancel installation without an interactive terminal. If choosing Project when asked about installation scope, open your project's folder before running this.

Install checklist

Check selected tools if a picker appears; Claude Code may be unchecked under Additional agents. ↑/↓ moves, Space toggles selections, Enter confirms.
Without a tool picker, check Installing to: for your intended tool. Stop if it names a different tool.
If asked, choose Symlink (Recommended) for shared files or Copy to all agents for separate copies; review the summary before confirming installation.
Install the find-skills skill? defaults to Yes, adding another skill for all projects. Choose No if you don't want that extra installation.

Skills CLI 1.7.2 sends install data to skills.sh by default, including the source, skill names, target tools and file details; GitHub sources are reported only when GitHub confirms the repository is public, while other remote sources can also be reported. Confirmed-public GitHub sources also trigger a security-audit request. Before installing, set the environment variable DO_NOT_TRACK=1 or DISABLE_TELEMETRY=1 to disable both.

npx skills add n8n-io/n8n --skill "n8n:create-skill" --full-depth

After installing for Claude Code, open it in the installation project if you chose Project; Global makes the skill available across projects on this computer. Once Claude Code loads the skill, its description helps Claude decide when to use it.

If installation created a top-level skills folder that did not exist when your Claude Code session started, run /reload-skills in that session. Run it again after later changes in that folder.

What's inside

Files included with this skill.

View on GitHub