docs: sync skills pack to n8n-skills v1.28.0 (folder management) (czlonkowski#976)

* docs: sync skills pack to n8n-skills v1.28.0 (folder management)

The bundled pack predates the 2.68.0 folder feature. Synced from
n8n-skills v1.28.0: n8n_manage_folders (six actions, list counts,
recursive totals, delete/archive semantics), the moveToFolder diff
operation, and parentFolderId on workflow create - including the
write-only placement and delete-archives-workflows behaviors.

Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* docs: sync Copilot review polish from n8n-skills v1.28.1

Explicit folderId placeholder in the moveToFolder verification example;
router delete note clarifies workflows move to the project root and are
archived, not removed.

Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: czlonkowski

CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.68.1] - 2026-08-04
+
+### Changed
+
+- **Bundled skills pack synced to n8n-skills v1.28.1.** The pack predates the folder feature that shipped in 2.68.0, so nothing in it mentioned `n8n_manage_folders` or folder placement. The tools-expert skill (category list, quick reference, version requirements, WORKFLOW_GUIDE) now documents all six folder actions with the list counts and recursive totals, the `moveToFolder` operation (21 diff operation types), and `parentFolderId` on workflow create — including the two behaviors an agent must know: a workflow's folder is write-only in n8n's API (verify placement via a folder's `get` counts, never by reading the workflow), and folder `delete` without `transferToFolderId` archives the folder's workflows (`"0"` transfers them to the project root and keeps them active). The always-on router gains the matching one-liner.
+
 ## [2.68.0] - 2026-08-04
 
 ### Added

data/skills/n8n-mcp-tools-expert/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: n8n-mcp-tools-expert
-description: Expert guide for using n8n-mcp MCP tools effectively. Use when searching for nodes, validating configurations, accessing templates, managing workflows, managing credentials, auditing instance security, or using any n8n-mcp tool. Provides tool selection guidance, parameter formats, and common patterns. IMPORTANT — Always consult this skill before calling any n8n-mcp tool — it prevents common mistakes like wrong nodeType formats, incorrect parameter structures, and inefficient tool usage. If the user mentions n8n, workflows, nodes, or automation and you have n8n MCP tools available, use this skill first.
+description: Expert guide for using n8n-mcp MCP tools effectively. Use when searching for nodes, validating configurations, accessing templates, managing workflows, organizing workflows into folders, managing credentials, auditing instance security, or using any n8n-mcp tool. Provides tool selection guidance, parameter formats, and common patterns. IMPORTANT — Always consult this skill before calling any n8n-mcp tool — it prevents common mistakes like wrong nodeType formats, incorrect parameter structures, and inefficient tool usage. If the user mentions n8n, workflows, nodes, or automation and you have n8n MCP tools available, use this skill first.
 ---
 
 # n8n MCP Tools Expert
@@ -18,9 +18,10 @@ n8n-mcp provides tools organized into categories:
 3. **Workflow Management** → [WORKFLOW_GUIDE.md](WORKFLOW_GUIDE.md)
 4. **Template Library** - Search and deploy 2,700+ real workflows
 5. **Data Tables** - Manage n8n data tables and rows (`n8n_manage_datatable`)
-6. **Credential Management** - Full credential CRUD + schema discovery (`n8n_manage_credentials`)
-7. **Security & Audit** - Instance security auditing with custom deep scan (`n8n_audit_instance`)
-8. **Documentation & Guides** - Tool docs, AI agent guide, Code node guides
+6. **Workflow Folders** - Folder CRUD + workflow placement (`n8n_manage_folders`)
+7. **Credential Management** - Full credential CRUD + schema discovery (`n8n_manage_credentials`)
+8. **Security & Audit** - Instance security auditing with custom deep scan (`n8n_audit_instance`)
+9. **Documentation & Guides** - Tool docs, AI agent guide, Code node guides
 
 ---
 
@@ -38,6 +39,7 @@ n8n-mcp provides tools organized into categories:
 | `validate_workflow` | Checking complete workflow | 100-500ms |
 | `n8n_deploy_template` | Deploy template to n8n instance | 200-500ms |
 | `n8n_manage_datatable` | Managing data tables and rows | 50-500ms |
+| `n8n_manage_folders` | Folder CRUD + organizing workflows | 100-500ms |
 | `n8n_manage_credentials` | Credential CRUD + schema discovery | 50-500ms |
 | `n8n_audit_instance` | Security audit (built-in + custom scan) | 500-5000ms |
 | `n8n_autofix_workflow` | Auto-fix validation errors | 200-1500ms |
@@ -219,12 +221,13 @@ See [VALIDATION_GUIDE.md](VALIDATION_GUIDE.md) for:
 ### Workflow Management
 See [WORKFLOW_GUIDE.md](WORKFLOW_GUIDE.md) for:
 - n8n_create_workflow
-- n8n_update_partial_workflow (20 operation types including patchNodeField and setNodeGroups!)
+- n8n_update_partial_workflow (21 operation types including patchNodeField, setNodeGroups, and moveToFolder!)
 - Smart parameters (branch, case)
 - AI connection types (8 types)
 - Workflow activation (activateWorkflow/deactivateWorkflow)
 - n8n_deploy_template
 - n8n_workflow_versions
+- n8n_manage_folders (folder CRUD + workflow placement)
 - n8n_manage_credentials (credential CRUD + schema discovery)
 - n8n_audit_instance (security auditing)
 
@@ -252,6 +255,14 @@ See [OPERATIONS_GUIDE.md](OPERATIONS_GUIDE.md) for all actions, filter condition
 
 ---
 
+## Workflow Folders
+
+`n8n_manage_folders` organizes workflows into folders (actions `create`/`list`/`get`/`rename`/`move`/`delete`; n8n 2.19+, registered free Community tier and up). `projectId` defaults to `'personal'`. Placing workflows happens in the *workflow* tools: `parentFolderId` on `n8n_create_workflow`, or the `moveToFolder` operation of `n8n_update_partial_workflow` (both n8n 2.32+; `null` = project root). Two things to internalize: a workflow's folder is **write-only** in n8n's API (verify placement via a folder's `get` counts, never by reading the workflow), and `delete` without `transferToFolderId` **archives** the folder's workflows (`transferToFolderId: "0"` moves them to the project root instead, keeping them active).
+
+See [WORKFLOW_GUIDE.md](WORKFLOW_GUIDE.md) for all actions, list filters/counts, and the delete semantics.
+
+---
+
 ## Credential Management
 
 `n8n_manage_credentials` is the unified credential tool: actions `list`, `get`, `create`, `update`, `delete`, `getSchema`. It never returns secrets — `get`/`create`/`update` strip the `data` field. Use `getSchema` before `create` to discover required fields. The optional `includeUsage: true` flag (on `list`/`get`) reverse-scans workflows and attaches `usedIn: [{id, name, active}]` + `usageCount` — use it before deleting or rotating a credential to see what breaks (it triggers a full client-side scan, caps at 5000 workflows, excludes archived, and degrades to a `usageScanError` field on failure).
@@ -298,6 +309,7 @@ See [OPERATIONS_GUIDE.md](OPERATIONS_GUIDE.md) for examples.
 - n8n_workflow_versions
 - n8n_autofix_workflow
 - n8n_manage_datatable
+- n8n_manage_folders (folder CRUD: n8n 2.19+, registered Community tier and up; workflow placement via parentFolderId/moveToFolder: n8n 2.32+)
 - n8n_manage_credentials
 - n8n_audit_instance
 
@@ -322,6 +334,7 @@ If API tools unavailable, use templates and validation-only workflows.
 | validate_node (minimal) | <50ms | Small |
 | validate_node (full) | <100ms | Medium |
 | validate_workflow | 100-500ms | Medium |
+| n8n_manage_folders | 100-500ms | Small |
 | n8n_manage_credentials | 50-500ms | Small-Medium |
 | n8n_audit_instance | 500-5000ms | Large |
 | n8n_create_workflow | 100-500ms | Medium |
@@ -368,9 +381,10 @@ If API tools unavailable, use templates and validation-only workflows.
 7. Workflows can be **activated via API** (`activateWorkflow` operation)
 8. Workflows are built **iteratively** (56s avg between edits)
 9. **Data tables** managed with `n8n_manage_datatable` (CRUD + filtering)
-10. **Credentials** managed with `n8n_manage_credentials` (CRUD + schema discovery)
-11. **Security audits** via `n8n_audit_instance` (built-in + custom deep scan)
-12. **AI agent guide** available via `tools_documentation({topic: "ai_agents_guide", depth: "full"})`
+10. **Folders** managed with `n8n_manage_folders`; workflow placement is write-only (verify via folder counts, not the workflow)
+11. **Credentials** managed with `n8n_manage_credentials` (CRUD + schema discovery)
+12. **Security audits** via `n8n_audit_instance` (built-in + custom deep scan)
+13. **AI agent guide** available via `tools_documentation({topic: "ai_agents_guide", depth: "full"})`
 
 **Common Workflow**:
 1. search_nodes → find node

data/skills/n8n-mcp-tools-expert/WORKFLOW_GUIDE.md

@@ -24,7 +24,8 @@ n8n_create_workflow({
   name: "Webhook to Slack",  // Required
   nodes: [...],              // Required: array of nodes
   connections: {...},        // Required: connections object
-  settings: {...}            // Optional: workflow settings
+  settings: {...},           // Optional: workflow settings
+  parentFolderId: "abc123"   // Optional: folder to create in (n8n 2.32+; omit = project root)
 })
 ```
 
@@ -72,6 +73,7 @@ n8n_create_workflow({
 - Workflows created **inactive** (activate with `activateWorkflow` operation)
 - Auto-sanitization runs on creation
 - Validate before creating for best results
+- `parentFolderId` places the workflow in a folder at creation (find or create folders with `n8n_manage_folders`). On n8n < 2.32 the whole create is rejected with a 400 naming the field — retry without it
 
 ---
 
@@ -83,7 +85,7 @@ n8n_create_workflow({
 
 **Common pattern**: 56s average between edits (iterative building!)
 
-### 20 Operation Types
+### 21 Operation Types
 
 **Node Operations** (7 types):
 1. `addNode` - Add new node
@@ -112,8 +114,9 @@ n8n_create_workflow({
 18. `activateWorkflow` - Activate workflow for automatic execution
 19. `deactivateWorkflow` - Deactivate workflow
 
-**Project Management Operations** (1 type):
+**Project Management Operations** (2 types):
 20. `transferWorkflow` - Transfer workflow to a different project (enterprise/cloud)
+21. `moveToFolder` - Move workflow into a folder, or to the project root with `parentFolderId: null` (n8n 2.32+)
 
 ### Intent Parameter (IMPORTANT!)
 
@@ -441,6 +444,33 @@ workflow without groups and warns; it does not fail.
 modes when the workflow has any. `mode: "active"` returns the *published* version's groups, which
 can differ from the draft's.
 
+### moveToFolder (Folder Placement, n8n 2.32+)
+
+Move the workflow into a folder as part of a diff:
+
+```javascript
+n8n_update_partial_workflow({
+  id: "workflow-id",
+  intent: "Move into the Production folder",
+  operations: [
+    {type: "moveToFolder", parentFolderId: "abc123"}  // or null = project root
+  ]
+})
+```
+
+n8n treats a workflow's folder as **write-only**: it can be set but never read back
+(no field in `n8n_get_workflow`, no folder filter on `n8n_list_workflows`). Verify a
+move indirectly — `n8n_manage_folders({action: "get", folderId: "abc123"})` reports the
+folder's recursive `totalWorkflows` — or visually in the n8n UI. Two consequences:
+
+- If a mixed update fails after the PUT persisted, the rollback restores the graph but
+  **cannot** restore the previous folder (it was never readable); the error says so.
+- Combined with `transferWorkflow` in one request, the folder move applies in the
+  *source* project before the transfer — move in a separate call after transferring.
+
+On n8n < 2.32 the operation fails with a 400 naming `parentFolderId` plus upgrade
+guidance. Find or create folders with `n8n_manage_folders` (see below).
+
 ### Cleanup & Recovery
 
 **cleanStaleConnections** - Remove broken connections:
@@ -995,6 +1025,67 @@ n8n_evaluations({
 
 ---
 
+## n8n_manage_folders (FOLDER MANAGEMENT)
+
+**Use when**: Organizing workflows into folders — creating structure before deploying a batch, restructuring a grown instance, or finding where to place a new workflow.
+
+Folder CRUD needs n8n >= 2.19 and a licensed instance (folders unlock on the **registered free Community tier** — Settings → Usage and plan → register — and up) plus `folder:*` API key scopes. Placing *workflows* into folders needs n8n >= 2.32 and happens in the workflow tools (`parentFolderId` on `n8n_create_workflow`, `moveToFolder` op), not here.
+
+### 6 Actions
+
+`create`, `list`, `get`, `rename`, `move`, `delete`. `projectId` defaults to `'personal'` (the calling user's personal project) on every action — pass a real project ID on multi-project enterprise instances.
+
+### Create a Folder
+
+```javascript
+n8n_manage_folders({action: "create", name: "Production"})
+// Nested: add parentFolderId: "abc123"
+// → {id, name, parentFolderId}
+```
+
+### List Folders (with contents counts)
+
+```javascript
+n8n_manage_folders({action: "list"})
+// Optional: nameFilter (contains match), parentFolderId (direct children only),
+//           sortBy ("name:asc" ... default "updatedAt:desc"), skip, take (max 100)
+// → folders: [{id, name, parentFolder, workflowCount, subFolderCount, path}], count
+// count = total matching the query, not the page size; path = names from root
+```
+
+### Folder Details (recursive totals)
+
+```javascript
+n8n_manage_folders({action: "get", folderId: "abc123"})
+// → {..., totalSubFolders, totalWorkflows}  // recursive — this is how you verify
+//    a workflow placement, since n8n never reports a workflow's folder directly
+```
+
+### Rename / Move
+
+```javascript
+n8n_manage_folders({action: "rename", folderId: "abc123", name: "Staging"})
+n8n_manage_folders({action: "move", folderId: "abc123", parentFolderId: "def456"})
+n8n_manage_folders({action: "move", folderId: "abc123", parentFolderId: null})  // → project root
+```
+
+### Delete (read this one)
+
+```javascript
+n8n_manage_folders({action: "delete", folderId: "abc123", transferToFolderId: "0"})
+```
+
+Without `transferToFolderId`, the folder's workflows are moved to the project root **and ARCHIVED** (deactivated), and sub-folders are deleted. Pass `transferToFolderId` to move contents somewhere first — `"0"` means the project root and keeps workflows active. Prefer the transfer form unless archiving is intended.
+
+**Gotchas**:
+- Folder names are not unique — `list` before `create` to avoid duplicates
+- A workflow's folder cannot be read back through the API; don't build logic that queries folder membership. Folder contents are visible only as counts
+- The `'personal'` default resolves through the projects API when licensed; on Community (where that API is 403) it infers the project from an existing workflow — a brand-new instance with zero workflows needs an explicit `projectId`, or create any workflow first
+- 403 = missing `folder:*` scopes or an unregistered/unlicensed instance; 404 = wrong project/folder ID, or n8n < 2.19 (no folders API at all)
+- On n8n 2.19–2.31 folder CRUD works but workflow placement doesn't (that needs 2.32+)
+
+---
+
 ## Workflow Lifecycle
 
 **Standard pattern**:

data/skills/n8n-workflow-patterns/SKILL.md

@@ -364,6 +364,7 @@ These skills work together with Workflow Patterns:
 - Deploy templates (n8n_deploy_template)
 - Use `tools_documentation({topic: "ai_agents_guide", depth: "full"})` for AI pattern guidance
 - Manage data tables with `n8n_manage_datatable`
+- Organize workflows into folders with `n8n_manage_folders`
 
 **n8n Expression Syntax** - Use to:
 - Write expressions in transformation nodes

data/skills/using-n8n-mcp-skills/SKILL.md

@@ -133,8 +133,9 @@ closes the gap where a tool's full description isn't loaded until first use.
 - `n8n_executions` — list/inspect executions. **There is no `execute_workflow` tool.**
 - `n8n_evaluations` — evaluation test runs: list runs, aggregated metrics, per-case results (n8n ≥ 2.30), plus `run`/`cancel` to start or stop a run (n8n ≥ 2.32). `run` executes the workflow against its whole dataset — real nodes fire, so ask the user first. A 403 can mean the API key was created before the action's minimum version (re-create it for the testRun scopes), evaluations aren't licensed on the plan, or the key's owner lacks access to the workflow — for `run`/`cancel`, specifically the `workflow:execute` scope.
 
-**Data, credentials, audit**
+**Data, folders, credentials, audit**
 - `n8n_manage_datatable` — Data Table CRUD, filtering, dry-run.
+- `n8n_manage_folders` — workflow folder CRUD with contents counts (n8n ≥ 2.19, registered Community tier and up; `projectId` defaults to `personal`). Place workflows via `parentFolderId` on `n8n_create_workflow` or the `moveToFolder` op (n8n ≥ 2.32). Placement is write-only — verify via a folder's `get` counts, never by reading the workflow. `delete` without `transferToFolderId` moves the folder's workflows to the project root and ARCHIVES them — they still exist, but deactivated (`transferToFolderId: "0"` = transfer to project root without archiving).
 - `n8n_manage_credentials` — credential CRUD + `getSchema` discovery.
 - `n8n_audit_instance` — security audit (hardcoded secrets, unauthenticated webhooks, error-handling gaps).
 

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "n8n-mcp",
-  "version": "2.68.0",
+  "version": "2.68.1",
   "description": "Integration between n8n workflow automation and Model Context Protocol (MCP)",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",