n8n-nodes-skills-tool

Community node package for skill-driven AI workflows in n8n.

It provides two nodes:

• Skills Tool: exposes your skills library to an AI Agent as a single tool with structured actions.
• Skills Cache Builder: trigger node that scans for updates and keeps skill metadata/content warm in cache.

Installation

Install from Settings -> Community Nodes in n8n, or manually:

npm install n8n-nodes-skills-tool

Skill Library Structure

skills/
  sql-query-builder/
    SKILL.md
    examples/
      northwind.sql
  email-drafting/
    SKILL.md

Each skill folder should contain SKILL.md.

Example frontmatter:

---
name: sql-query-builder
description: Generates optimized SQL queries from natural language
resources:
  - examples/northwind.sql
---

Notes:

• name and description are used for skill discovery.
• resources is optional.
• If resources is omitted, resource listing falls back to a shallow folder scan.

Source Modes

Skills Tool

• googleDrive: requires credential googleDriveOAuth2Api.
• oneDrive: requires credential microsoftOneDriveOAuth2Api.
• localFolder: reads from mounted path (default /data/skills).
• manual: single inline skill from node fields (no builder/cache warmup needed).

Skills Cache Builder

• googleDrive, oneDrive, localFolder.
• Manual mode is intentionally not supported for the builder.

Tool Contract (Skills Tool)

The AI Agent receives one tool and calls it with an action field.

Supported actions:

• get_skill (requires name): returns full SKILL.md content.
• list_skill_resources (requires name): returns resource paths.
• get_skill_resource (requires name and resourcePath): returns text content of one resource file.

Important behavior:

• The skill catalog is injected into the tool description so the model can see available skill names/descriptions before choosing an action.
• allowedSkills can restrict which skills are visible to the agent.
• In manual mode, only one skill exists and resource fetching is not supported.

How Skill Caching Works

Caching has two primary layers plus adapter-level fallback cache.

L1 (process memory)

• In-memory Map keyed by sourceMode:idOrPath.
• Fastest reads.
• Cleared on n8n/container restart.

L2 (workflow static data)

• Persisted under workflow static data as skills.l2.<cacheKey>.
• Survives restarts.
• Used to warm L1 after restart.

Adapter-level cache (metadata/content)

• Stored in static data (skills.meta, skills.content.<name>, skills.vfs).
• TTL is 60 minutes.
• Used by source adapters to reduce repeated API/file reads.

What is cached in the unified entry

• meta: list of { name, description }.
• vfs: preloaded SKILL.md text by skill name.
• deltaToken: source-specific change token/snapshot.
• ts: write timestamp.

VFS size cap

Skills Cache Builder preloads SKILL.md files into vfs up to 512 KB total (MAX_VFS_BYTES).

• If a skill is not in vfs, get_skill falls back to the source adapter and fetches it on demand.

How Updates Are Detected

Skills Cache Builder runs cache checks and updates only when needed.

• oneDrive: uses Graph delta endpoint and stores @odata.deltaLink as deltaToken.
• googleDrive: compares a sorted snapshot of child skill folder names.
• localFolder: treated as changed each run (full rebuild path).

If no changes are detected, builder emits status: "no_changes" and warms L1 from L2 if needed.
If changed, builder refreshes metadata/content and emits status: "updated".

Trigger Behavior (Skills Cache Builder)

Parameters:

• autoRebuild (default true): whether polling is enabled.
• intervalMinutes (default 5): schedule interval when auto rebuild is on.

Runtime behavior:

• Always performs an immediate cache check on activation/manual trigger.
• When autoRebuild = true, keeps polling on interval.
• Also exposes manualTriggerFunction for on-demand refresh.

Node output payload:

{
  "status": "updated | no_changes",
  "skillCount": 12,
  "vfsSizeKb": 180,
  "cacheKey": "localFolder:/data/skills"
}

vfsSizeKb is present when status is updated.

Recommended Setup

Use two workflows.

Workflow A: Cache maintenance

1. Add Skills Cache Builder.
2. Configure source (Google Drive/OneDrive/Local Folder).
3. Enable Auto Rebuild on Schedule and set interval.
4. Activate workflow.

Workflow B: AI execution

1. Add AI Agent.
2. Add Skills Tool and connect to agent Tools input.
3. Configure the same source and same folder/path as Workflow A.
4. Optionally set Allowed Skill Names or IDs.

Critical: both nodes must point to the same source identity so they share the same cache key semantics.

Local Folder Setup (Docker)

Mount host skills folder into the n8n container:

volumes:
  - /path/to/skills:/data/skills:ro

Then set both nodes to:

• Source = Local Folder
• Skills Folder Path = /data/skills

Troubleshooting

"Skills cache is empty. Run the Skills Cache Builder node first"

• Run the Skills Cache Builder node once manually.
• Ensure source mode and folder/path match between builder and tool.
• Confirm credentials can list/read the folder.

Skill not found

• Verify skill folder name and SKILL.md path.
• Check allowedSkills is not filtering it out.
• For manual mode, only the configured manual skill name is valid.

Resource fetch failures

• get_skill_resource supports text-like files only.
• In manual mode, resource fetch is not supported.

Requirements

• n8n >= 1.0.0
• Node.js >= 22.0.0
• Google Drive mode: OAuth credential with Drive read access
• OneDrive mode: OAuth credential with Files.Read access

License

MIT