From a00dd19c43a3964153082ea1118e8ae0f85505a3 Mon Sep 17 00:00:00 2001 From: Csaba Tuncsik Date: Wed, 8 Apr 2026 09:57:39 +0200 Subject: [PATCH] chore: Move Claude Code skills, agents and commands under n8n plugin (no-changelog) (#28020) --- .claude/README.md | 35 +++------ .claude/plugins/n8n/README.md | 71 +++++++------------ .../n8n/agents/developer.md} | 4 +- .../n8n/agents/linear-issue-triager.md} | 2 +- .../n8n/commands/plan.md} | 0 .../n8n/commands/triage.md} | 2 +- .../n8n}/skills/content-design/SKILL.md | 1 - .../n8n/skills/conventions}/SKILL.md | 1 - .../n8n}/skills/create-issue/SKILL.md | 1 - .../n8n}/skills/create-pr/SKILL.md | 1 - .../n8n}/skills/create-skill/SKILL.md | 9 ++- .../n8n}/skills/linear-issue/SKILL.md | 1 - .../n8n}/skills/loom-transcript/SKILL.md | 1 - .../n8n}/skills/node-add-oauth/SKILL.md | 1 - .../n8n}/skills/reproduce-bug/SKILL.md | 1 - .../skills/spec-driven-development/SKILL.md | 1 - AGENTS.md | 7 ++ 17 files changed, 49 insertions(+), 90 deletions(-) rename .claude/{agents/n8n-developer.md => plugins/n8n/agents/developer.md} (87%) rename .claude/{agents/n8n-linear-issue-triager.md => plugins/n8n/agents/linear-issue-triager.md} (99%) rename .claude/{commands/n8n-plan.md => plugins/n8n/commands/plan.md} (100%) rename .claude/{commands/n8n-triage.md => plugins/n8n/commands/triage.md} (69%) rename .claude/{ => plugins/n8n}/skills/content-design/SKILL.md (99%) rename .claude/{skills/n8n-conventions => plugins/n8n/skills/conventions}/SKILL.md (99%) rename .claude/{ => plugins/n8n}/skills/create-issue/SKILL.md (99%) rename .claude/{ => plugins/n8n}/skills/create-pr/SKILL.md (99%) rename .claude/{ => plugins/n8n}/skills/create-skill/SKILL.md (87%) rename .claude/{ => plugins/n8n}/skills/linear-issue/SKILL.md (99%) rename .claude/{ => plugins/n8n}/skills/loom-transcript/SKILL.md (99%) rename .claude/{ => plugins/n8n}/skills/node-add-oauth/SKILL.md (99%) rename .claude/{ => plugins/n8n}/skills/reproduce-bug/SKILL.md (99%) rename .claude/{ => plugins/n8n}/skills/spec-driven-development/SKILL.md (99%) diff --git a/.claude/README.md b/.claude/README.md index f6ec665f537..93e84daaf2c 100644 --- a/.claude/README.md +++ b/.claude/README.md @@ -2,6 +2,10 @@ This directory contains shared Claude Code configuration for the n8n team. +All skills, agents, and commands live under the `n8n` plugin at +`.claude/plugins/n8n/` for `n8n:` namespacing. See +[plugin README](plugins/n8n/README.md) for full details. + ## Setup ### Linear MCP Server @@ -33,31 +37,10 @@ To auto-approve Linear MCP tools, add to your global settings: **Note:** For GitHub/git operations, we use `gh` CLI and `git` commands instead of GitHub MCP. -## Available Commands +## Plugin -- `/n8n-triage PAY-XXX` - Analyze and triage a Linear issue -- `/n8n-plan PAY-XXX` - Create implementation plan +All skills, commands, and agents are auto-discovered from +`.claude/plugins/n8n/`. They get the `n8n:` namespace prefix automatically +(e.g. `n8n:create-pr`, `/n8n:plan`, `n8n:developer`). -## Quick Reference - -- `/n8n-conventions` - Load detailed conventions guide (optional - agents already know n8n patterns) - -## Workflow - -**Recommended approach:** -1. `/n8n-triage PAY-123` → Investigate root cause and severity (optional) -2. `/n8n-plan PAY-123` → Create detailed implementation plan -3. Review the plan in chat -4. Say "implement it" or "go ahead" → I'll launch n8n-developer agent -5. Implementation proceeds with full context from the plan - -## Agents - -- **n8n-developer** - Full-stack n8n development (frontend/backend/nodes) -- **n8n-linear-issue-triager** - Issue investigation and analysis - -## Skills - -- **n8n-conventions** - Quick reference pointing to /AGENTS.md (optional - agents have embedded knowledge) - - Use `/n8n-conventions` when you need detailed patterns - - References root docs instead of duplicating (~95 lines) +See [plugin README](plugins/n8n/README.md) for structure and design decisions. diff --git a/.claude/plugins/n8n/README.md b/.claude/plugins/n8n/README.md index 000f72b26bc..30d990c05d2 100644 --- a/.claude/plugins/n8n/README.md +++ b/.claude/plugins/n8n/README.md @@ -1,51 +1,19 @@ # n8n Claude Code Plugin -Shared skills, commands, and agents for n8n development. +Shared skills, commands, and agents for n8n development. All items are +namespaced under `n8n:` to avoid collisions with personal or third-party +plugins. -## Skills +## Usage -### `n8n:setup-mcps` +Skills, commands, and agents are auto-discovered by Claude Code from this +plugin directory. Everything gets the `n8n:` namespace prefix automatically. -Configures commonly used MCP servers for n8n engineers. - -**Usage:** -``` -/n8n:setup-mcps -``` - -**What it does:** -1. Checks which MCPs are already configured (matches by URL, not name) -2. Presents a multi-select menu of available MCPs (Linear, Notion, Context7, Figma) -3. For each selected MCP, asks which scope to install in: - - **user** (recommended) — available across all projects - - **local** — only in this project (`settings.local.json`) -4. Installs using official recommended commands - -**Note:** Project scope is intentionally not offered since `.claude/settings.json` is tracked in git. - -## Design Decisions - -### Why a plugin instead of standalone skills? - -To get the `n8n:` namespace prefix for all n8n-specific skills, avoiding name -collisions with built-in or personal skills. Claude Code only supports -colon-namespaced skills (`n8n:setup-mcps`) through the plugin system — -standalone `.claude/skills/` entries cannot be namespaced. This also provides a -home for future n8n skills, commands, and agents under the same `n8n:` prefix. - -### Why only user and local scope (no project scope)? - -Project scope writes MCP config to `.claude/settings.json`, which is tracked in -git. Since MCP credentials are personal (OAuth tokens, API keys), they should -not end up in version control. User scope makes MCPs available across all -projects; local scope (`settings.local.json`) keeps them project-specific but -gitignored. - -### Why ask scope per MCP instead of once for all? - -Engineers may want different scopes for different MCPs. For example, Context7 -and Figma are useful across all projects (user scope), while Linear or Notion -might only be needed for this project (local scope). +| Type | Example | Invocation | +|------|---------|------------| +| Skill | `skills/create-pr/SKILL.md` | `n8n:create-pr` | +| Command | `commands/plan.md` | `/n8n:plan PAY-XXX` | +| Agent | `agents/developer.md` | `n8n:developer` | ## Plugin Structure @@ -54,13 +22,24 @@ might only be needed for this project (local scope). ├── .claude-plugin/ │ ├── marketplace.json # Marketplace manifest │ └── plugin.json # Plugin identity +├── agents/ +│ └── .md # → n8n: agent +├── commands/ +│ └── .md # → /n8n: command ├── skills/ -│ └── sample-skill/ -│ └── SKILL.md +│ └── /SKILL.md # → n8n: skill └── README.md ``` -## Known Issues +## Design Decisions + +### Why a plugin instead of standalone skills? + +To get the `n8n:` namespace prefix, avoiding collisions with personal or +third-party plugins. Claude Code only supports colon-namespaced items through +the plugin system — standalone `.claude/skills/` entries cannot be namespaced. + +### Known Issues - Plugin skill namespacing requires omitting the `name` field from SKILL.md frontmatter due to a [Claude Code bug](https://github.com/anthropics/claude-code/issues/17271). diff --git a/.claude/agents/n8n-developer.md b/.claude/plugins/n8n/agents/developer.md similarity index 87% rename from .claude/agents/n8n-developer.md rename to .claude/plugins/n8n/agents/developer.md index d775a5476db..1adf63b93de 100644 --- a/.claude/agents/n8n-developer.md +++ b/.claude/plugins/n8n/agents/developer.md @@ -1,6 +1,6 @@ --- -name: n8n-developer -description: Use this agent for any n8n development task - frontend (Vue 3), backend (Node.js/TypeScript), workflow engine, node creation, or full-stack features. The agent automatically applies n8n conventions and best practices. Examples: user: 'Add a new button to the workflow editor' assistant: 'I'll use the n8n-developer agent to implement this following n8n's design system.' user: 'Create an API endpoint for workflow export' assistant: 'I'll use the n8n-developer agent to build this API endpoint.' user: 'Fix the CSS issue in the node panel' assistant: 'I'll use the n8n-developer agent to fix this styling issue.' +name: developer +description: Use this agent for any n8n development task - frontend (Vue 3), backend (Node.js/TypeScript), workflow engine, node creation, or full-stack features. The agent automatically applies n8n conventions and best practices. Examples: user: 'Add a new button to the workflow editor' assistant: 'I'll use the developer agent to implement this following n8n's design system.' user: 'Create an API endpoint for workflow export' assistant: 'I'll use the developer agent to build this API endpoint.' user: 'Fix the CSS issue in the node panel' assistant: 'I'll use the developer agent to fix this styling issue.' model: inherit color: blue --- diff --git a/.claude/agents/n8n-linear-issue-triager.md b/.claude/plugins/n8n/agents/linear-issue-triager.md similarity index 99% rename from .claude/agents/n8n-linear-issue-triager.md rename to .claude/plugins/n8n/agents/linear-issue-triager.md index 67ed6b16351..08256acd9aa 100644 --- a/.claude/agents/n8n-linear-issue-triager.md +++ b/.claude/plugins/n8n/agents/linear-issue-triager.md @@ -1,5 +1,5 @@ --- -name: n8n-linear-issue-triager +name: linear-issue-triager description: Use this agent proactively when a Linear issue is created, updated, or needs comprehensive analysis. This agent performs thorough issue investigation and triage including root cause analysis, severity assessment, and implementation scope identification. model: inherit color: red diff --git a/.claude/commands/n8n-plan.md b/.claude/plugins/n8n/commands/plan.md similarity index 100% rename from .claude/commands/n8n-plan.md rename to .claude/plugins/n8n/commands/plan.md diff --git a/.claude/commands/n8n-triage.md b/.claude/plugins/n8n/commands/triage.md similarity index 69% rename from .claude/commands/n8n-triage.md rename to .claude/plugins/n8n/commands/triage.md index 8f1eb5537f1..9bb4a449bb3 100644 --- a/.claude/commands/n8n-triage.md +++ b/.claude/plugins/n8n/commands/triage.md @@ -4,4 +4,4 @@ argument-hint: [PAY-XXXX | DEV-XXXX | ENG-XXXX] allowed-tools: Task --- -Use the n8n-linear-issue-triager agent to triage Linear issue $ARGUMENTS. +Use the n8n:linear-issue-triager agent to triage Linear issue $ARGUMENTS. diff --git a/.claude/skills/content-design/SKILL.md b/.claude/plugins/n8n/skills/content-design/SKILL.md similarity index 99% rename from .claude/skills/content-design/SKILL.md rename to .claude/plugins/n8n/skills/content-design/SKILL.md index f16d387c35c..0ef01d02b2a 100644 --- a/.claude/skills/content-design/SKILL.md +++ b/.claude/plugins/n8n/skills/content-design/SKILL.md @@ -1,5 +1,4 @@ --- -name: content-design description: > Product content designer for UI copy. Use when writing, reviewing, or auditing user-facing text: button labels, error messages, tooltips, empty states, modal copy, diff --git a/.claude/skills/n8n-conventions/SKILL.md b/.claude/plugins/n8n/skills/conventions/SKILL.md similarity index 99% rename from .claude/skills/n8n-conventions/SKILL.md rename to .claude/plugins/n8n/skills/conventions/SKILL.md index 20a805b7ec2..71d8eafdc9a 100644 --- a/.claude/skills/n8n-conventions/SKILL.md +++ b/.claude/plugins/n8n/skills/conventions/SKILL.md @@ -1,5 +1,4 @@ --- -name: n8n-conventions description: Quick reference for n8n patterns. Full docs /AGENTS.md --- diff --git a/.claude/skills/create-issue/SKILL.md b/.claude/plugins/n8n/skills/create-issue/SKILL.md similarity index 99% rename from .claude/skills/create-issue/SKILL.md rename to .claude/plugins/n8n/skills/create-issue/SKILL.md index ce227654af3..c47465ad4cf 100644 --- a/.claude/skills/create-issue/SKILL.md +++ b/.claude/plugins/n8n/skills/create-issue/SKILL.md @@ -1,5 +1,4 @@ --- -name: create-issue description: Create Linear tickets or GitHub issues following n8n conventions. Use when the user asks to create a ticket, file a bug, open an issue, or says /create-issue. argument-hint: "[linear|github] " compatibility: diff --git a/.claude/skills/create-pr/SKILL.md b/.claude/plugins/n8n/skills/create-pr/SKILL.md similarity index 99% rename from .claude/skills/create-pr/SKILL.md rename to .claude/plugins/n8n/skills/create-pr/SKILL.md index 9039feac420..6054f402957 100644 --- a/.claude/skills/create-pr/SKILL.md +++ b/.claude/plugins/n8n/skills/create-pr/SKILL.md @@ -1,5 +1,4 @@ --- -name: create-pr description: Creates GitHub pull requests with properly formatted titles that pass the check-pr-title CI validation. Use when creating PRs, submitting changes for review, or when the user says /pr or asks to create a pull request. allowed-tools: Bash(git:*), Bash(gh:*), Read, Grep, Glob --- diff --git a/.claude/skills/create-skill/SKILL.md b/.claude/plugins/n8n/skills/create-skill/SKILL.md similarity index 87% rename from .claude/skills/create-skill/SKILL.md rename to .claude/plugins/n8n/skills/create-skill/SKILL.md index 6c1d5b41058..c3336caaf8c 100644 --- a/.claude/skills/create-skill/SKILL.md +++ b/.claude/plugins/n8n/skills/create-skill/SKILL.md @@ -1,5 +1,4 @@ --- -name: create-skill description: >- Guides users through creating effective Agent Skills. Use when you want to create, write, or author a new skill, or asks about skill structure, best @@ -13,13 +12,13 @@ Skills are markdown (plus optional scripts) that teach the agent a focused workf | Location | When to use | |----------|-------------| -| **`.claude/skills//` in this repo** | Default for n8n: team-shared, versioned. **Cursor picks up project skills from here** when working in the repo (same idea as Claude Code). | +| **`.claude/plugins/n8n/skills//`** | Default for n8n: team-shared, versioned, namespaced under `n8n:`. | | `~/.claude/skills//` | Personal skill for Claude Code across all projects. | | `~/.cursor/skills//` | 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 **repo `.claude/skills/`** for anything that should match how the rest of the team works. +Prefer **plugin `.claude/plugins/n8n/skills/`** for anything that should match how the rest of the team works. ## Before you write: gather requirements @@ -29,7 +28,7 @@ Ask (or infer) briefly: 2. **Triggers** — when should the agent apply this skill? 3. **Gaps** — what does the agent *not* already know (project rules, URLs, formats)? 4. **Outputs** — templates, checklists, or strict formats? -5. **Examples** — follow an existing skill in `.claude/skills/` if one fits. +5. **Examples** — follow an existing skill in `.claude/plugins/n8n/skills/` if one fits. Ask the user in plain language when you need more detail. @@ -80,7 +79,7 @@ description: >- # max 1024 chars, non-empty — see below - **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** — give the path from the **repository root** (e.g. `.claude/skills/create-issue/SKILL.md`) so humans and tools can resolve it. From a sibling folder, a relative link works too: `[create-issue](../create-issue/SKILL.md)`. Name the skill and the task; parent skills should delegate steps instead of duplicating long procedures. +- **Referencing other skills** — use the namespaced invocation name (e.g. `n8n:create-issue`) so the agent resolves the plugin skill. For human-readable links, give the path from the repo root (e.g. `.claude/plugins/n8n/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) diff --git a/.claude/skills/linear-issue/SKILL.md b/.claude/plugins/n8n/skills/linear-issue/SKILL.md similarity index 99% rename from .claude/skills/linear-issue/SKILL.md rename to .claude/plugins/n8n/skills/linear-issue/SKILL.md index 40f2f336392..b78ddde94d4 100644 --- a/.claude/skills/linear-issue/SKILL.md +++ b/.claude/plugins/n8n/skills/linear-issue/SKILL.md @@ -1,5 +1,4 @@ --- -name: linear-issue description: Fetch and analyze Linear issue with all related context. Use when starting work on a Linear ticket, analyzing issues, or gathering context about a Linear issue. disable-model-invocation: true argument-hint: "[issue-id]" diff --git a/.claude/skills/loom-transcript/SKILL.md b/.claude/plugins/n8n/skills/loom-transcript/SKILL.md similarity index 99% rename from .claude/skills/loom-transcript/SKILL.md rename to .claude/plugins/n8n/skills/loom-transcript/SKILL.md index 5d121b4d8e8..b07be5a4a4c 100644 --- a/.claude/skills/loom-transcript/SKILL.md +++ b/.claude/plugins/n8n/skills/loom-transcript/SKILL.md @@ -1,5 +1,4 @@ --- -name: loom-transcript description: Fetch and display the full transcript from a Loom video URL. Use when the user wants to get or read a Loom transcript. argument-hint: [loom-url] --- diff --git a/.claude/skills/node-add-oauth/SKILL.md b/.claude/plugins/n8n/skills/node-add-oauth/SKILL.md similarity index 99% rename from .claude/skills/node-add-oauth/SKILL.md rename to .claude/plugins/n8n/skills/node-add-oauth/SKILL.md index 66a185bfce7..9059b7639fc 100644 --- a/.claude/skills/node-add-oauth/SKILL.md +++ b/.claude/plugins/n8n/skills/node-add-oauth/SKILL.md @@ -1,5 +1,4 @@ --- -name: node-add-oauth description: Add OAuth2 credential support to an existing n8n node — creates the credential file, updates the node, adds tests, and keeps the CLI constant in sync. Use when the user says /node-add-oauth. argument-hint: "[node-name] [optional: custom-scopes flag or scope list]" --- diff --git a/.claude/skills/reproduce-bug/SKILL.md b/.claude/plugins/n8n/skills/reproduce-bug/SKILL.md similarity index 99% rename from .claude/skills/reproduce-bug/SKILL.md rename to .claude/plugins/n8n/skills/reproduce-bug/SKILL.md index e29e2f8d6e9..d4cedd3c059 100644 --- a/.claude/skills/reproduce-bug/SKILL.md +++ b/.claude/plugins/n8n/skills/reproduce-bug/SKILL.md @@ -1,5 +1,4 @@ --- -name: reproduce-bug description: Reproduce a bug from a Linear ticket with a failing test. Expects the full ticket context (title, description, comments) to be provided as input. user_invocable: true --- diff --git a/.claude/skills/spec-driven-development/SKILL.md b/.claude/plugins/n8n/skills/spec-driven-development/SKILL.md similarity index 99% rename from .claude/skills/spec-driven-development/SKILL.md rename to .claude/plugins/n8n/skills/spec-driven-development/SKILL.md index 25fd65868d4..151b88e6d1b 100644 --- a/.claude/skills/spec-driven-development/SKILL.md +++ b/.claude/plugins/n8n/skills/spec-driven-development/SKILL.md @@ -1,5 +1,4 @@ --- -name: spec-driven-development description: Keeps implementation and specs in sync. Use when working on a feature that has a spec in .claude/specs/, when the user says /spec, or when starting implementation of a documented feature. Also use when the user asks to verify implementation against a spec or update a spec after changes. --- diff --git a/AGENTS.md b/AGENTS.md index be623018ec3..005d6524ecb 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -20,6 +20,13 @@ frontend, and extensible node-based workflow engine. Hygiene below) - Use mermaid diagrams in MD files when you need to visualise something +## Claude Code Plugin + +n8n-specific skills, commands, and agents live in `.claude/plugins/n8n/` and +are namespaced under `n8n:`. Use `n8n:` prefix when invoking them +(e.g. `/n8n:create-pr`, `/n8n:plan`, `n8n:developer` agent). +See [plugin README](.claude/plugins/n8n/README.md) for structure and details. + ## Essential Commands ### Building