n8n:create-skill

Source excerpt starting at line 1.

1---2name: n8n:create-skill3description: >-4  Guides users through creating effective Agent Skills. Use when you want to5  create, write, or author a new skill, or asks about skill structure, best6  practices, or SKILL.md format.7---8# Creating skills9 10Skills 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.11 12## Where skills live13 14| Location | When to use |15|----------|-------------|16| **`.agents/skills/<name>/`** | Default for n8n: team-shared, versioned, agent-neutral source. |17| `.claude/plugins/n8n/skills/<name>/` | Claude-specific override, or a generated symlink to `.agents/skills/<name>/`. |18| `.opencode/skills/<name>/` | OpenCode-specific override only. Shared skills stay in `.agents/skills/<name>/`. |19| `~/.claude/skills/<name>/` | Personal skill for Claude Code across all projects. |20| `~/.config/opencode/skills/<name>/` | Personal skill for OpenCode across all projects. |21| `~/.cursor/skills/<name>/` | Optional personal skill for Cursor only, global to your machine. |22 23**Do not** put custom skills in `~/.cursor/skills-cursor/`—that is reserved for Cursor’s built-in skills.24 25Prefer **`.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.26 27## Before you write: gather requirements28 29Ask (or infer) briefly:30 311. **Purpose** — one concrete task or workflow.322. **Triggers** — when should the agent apply this skill?333. **Gaps** — what does the agent *not* already know (project rules, URLs, formats)?344. **Outputs** — templates, checklists, or strict formats?355. **Examples** — follow an existing shared skill in `.agents/skills/` if one fits.36 37Ask the user in plain language when you need more detail.38 39## File layout40 41```42skill-name/43├── SKILL.md       # required44├── reference.md   # optional — detail the agent reads only if needed45├── examples.md    # optional46└── scripts/       # optional47```48 49### Frontmatter (required)50 51```yaml52---53name: n8n:skill-name      # n8n:<name> — lowercase, hyphens, max 64 chars54description: >-         # max 1024 chars, non-empty — see below55  ...56---57```58 59**Name** — shared n8n skills use the `n8n:<name>` form so Claude Code namespaces60them under the `n8n` plugin (invoked as `/n8n:<name>`). The `<name>` part must61match the skill's directory name.62 63**Description** (discovery is everything — third person, WHAT + WHEN, trigger words):64 65- Good: `Extracts tables from PDFs and fills forms. Use when the user works with PDFs, forms, or document extraction.`66- Bad: `Helps with documents` or `I can help you with PDFs`67 68## Authoring rules69 701. **Concise** — assume the model is capable; only add non-obvious domain or project facts.712. **Progressive disclosure** — essentials in `SKILL.md`; long reference in `reference.md`. Link **one level deep** from `SKILL.md`.723. **Prefer one default** — e.g. one library or one workflow; add an escape hatch only if needed.734. **Stable wording** — one term per concept; avoid dated “until month X” notes unless you tuck legacy bits behind a short “Deprecated” note.745. **Paths** — forward slashes only (`scripts/foo.py`).75 76**Rough size:** aim for **well under ~200 lines** in `SKILL.md`; if it grows, split detail out.77 78### Scope: one job per skill (and parent skills)79 80- **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**.81- **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.82- **When one large skill is OK** — a single end-to-end flow that always runs together and shares one tight checklist;83 84### MCPs, CLI tools, and other skills85 86- **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`.87- **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:88  - Put a hint in the **frontmatter description** (e.g. “Requires Linear MCP for …”) so mismatches are obvious early.89  - 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.90- **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.91 92## Patterns (pick what fits)93 94- **Template** — give the exact output shape (markdown/code blocks).95- **Checklist** — numbered or `- [ ]` steps for multi-step work.96- **Branching** — “If A → …; if B → …” at the top of a workflow.97- **Scripts** — document run commands; say whether to **execute** or **read** the script.98 99## Workflow: create → verify100 1011. **Name + description** — hyphenated name; description with triggers.1022. **Outline** — minimal sections; link optional files.1033. **Implement** — `SKILL.md` first; add `reference.md` / `scripts/` only if they save tokens or reduce errors.1044. **Check** — third-person description; terminology consistent; no duplicate encyclopedic content the model already knows.105 106## Anti-patterns107 108- Verbose tutorials (“what is a PDF”) inside the skill.109- Many equivalent options with no default.110- Vague names (`helper`, `utils`).111- Deep chains of linked files.112- Assuming an MCP or tool is present without stating it or offering a fallback.113- One oversized skill that mixes unrelated workflows instead of smaller skills + a thin parent.114 115## Quick example stub116 117```markdown118---119name: n8n:my-workflow120description: Does X using project convention Y. Use when the user asks for X or mentions Z.121---122 123# My workflow124 1251. …1262. …127 128## Output format129 130Use a fenced code block for the exact shape reviewers should see.131 132## More detail133See [reference.md](reference.md) if edge cases matter.134```135