@n8n-as-code/n8nac 2026.3.2-next.3 → 2026.4.0-next.11

package/README.md

@@ -37,8 +37,10 @@ Once setup is done, just talk to OpenClaw:
 
 > "What operations does the Google Sheets node support?"
 
-The plugin injects the full n8n-architect instructions into every conversation
-so the AI knows the exact `n8nac` workflow (init-check → pull → edit → push → verify).
+The plugin now keeps its default prompt hook lightweight. OpenClaw can activate
+the bundled `n8n-architect` skill for explicit n8n workflow sessions, and that
+skill then reads the generated workspace `AGENTS.md` for the full workflow
+engineering guidance.
 
 ## CLI commands
 

package/index.ts

@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync, readFileSync } from "node:fs";
+import { accessSync, constants, existsSync, mkdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
 import { registerN8nAcCli } from "./src/cli.js";
@@ -6,7 +6,7 @@ import { createN8nAcTool } from "./src/tool.js";
 import { getWorkspaceDir, isWorkspaceInitialized } from "./src/workspace.js";
 
 // ---------------------------------------------------------------------------
-// AGENTS.md context injection — populated once on service start
+// Lightweight prompt context
 // ---------------------------------------------------------------------------
 
 const BOOTSTRAP_CONTEXT = `\
@@ -21,20 +21,6 @@ Once you have both, call the \`n8nac\` tool with \`action: "init_auth"\`, then
 \`action: "init_project"\` to finish setup.
 `;
 
-const MISSING_AGENTS_CONTEXT = `\
-## n8n-as-code — AI Context Missing
-
-The workspace is initialized, but the generated AI context file (\`AGENTS.md\`) is missing or unreadable.
-
-**Tell the user:**
-> "Your n8n-as-code workspace is connected, but the AI context needs to be regenerated before I can safely guide workflow changes."
-
-Ask the user to run \`npx --yes n8nac update-ai\` in the OpenClaw workspace, or rerun
-\`openclaw n8nac:setup\` if they want the setup wizard to repair it.
-`;
-
-let agentsContext: string | null = null;
-
 function readConfig(workspaceDir: string): Record<string, string> {
   try {
     const raw = readFileSync(join(workspaceDir, "n8nac-config.json"), "utf-8");
@@ -56,26 +42,46 @@ function buildStatusHeader(workspaceDir: string): string {
     `- Workspace directory: \`${workspaceDir}\``,
     `- n8n host: \`${host}\``,
     `- Active project: \`${project}\``,
-    "",
-    "Skip the 'Workspace Bootstrap' section below — setup is complete.",
-    "Proceed directly to the user's request using the `n8nac` tool.",
-    "",
-    "---",
-    "",
   ].join("\n");
 }
 
-function loadAgentsContext(workspaceDir: string): string | null {
-  const p = join(workspaceDir, "AGENTS.md");
-  if (!existsSync(p)) return null;
+function hasAgentsContext(workspaceDir: string): boolean {
+  const agentsPath = join(workspaceDir, "AGENTS.md");
   try {
-    const raw = readFileSync(p, "utf-8");
-    return buildStatusHeader(workspaceDir) + raw;
+    accessSync(agentsPath, constants.R_OK);
+    return true;
   } catch {
-    return null;
+    return false;
   }
 }
 
+export function buildPromptContext(workspaceDir: string): string {
+  if (!isWorkspaceInitialized(workspaceDir)) {
+    return BOOTSTRAP_CONTEXT;
+  }
+
+  const agentsPath = join(workspaceDir, "AGENTS.md");
+  const guidanceLines = hasAgentsContext(workspaceDir)
+    ? [
+        "",
+        "Detailed workflow-authoring guidance is intentionally scoped to the `n8n-architect` skill.",
+        "Only use that deeper n8n workflow context when the request is clearly about n8n workflow work.",
+        `When that happens, read \`${agentsPath}\` for workspace-specific instructions.`,
+      ]
+    : [
+        "",
+        "Detailed workflow-authoring guidance is intentionally scoped to the `n8n-architect` skill, but the generated workspace AI context file (`AGENTS.md`) is missing.",
+        "If the user starts explicit n8n workflow work, regenerate `AGENTS.md` with `npx --yes n8nac update-ai` or rerun `openclaw n8nac:setup` first.",
+      ];
+
+  return [
+    buildStatusHeader(workspaceDir),
+    ...guidanceLines,
+    "",
+    "For unrelated requests, ignore this plugin context.",
+  ].join("\n");
+}
+
 // ---------------------------------------------------------------------------
 // Plugin
 // ---------------------------------------------------------------------------
@@ -94,19 +100,10 @@ const n8nAcPlugin = {
     mkdirSync(workspaceDir, { recursive: true });
 
     // -- Context injection ---------------------------------------------------
-    // Prepend n8n-architect instructions to every prompt build.
+    // Keep default context lightweight; full workflow-authoring guidance lives
+    // in the bundled `n8n-architect` skill and the workspace AGENTS.md file.
     api.on("before_prompt_build", () => {
-      const initialized = isWorkspaceInitialized(workspaceDir);
-      // Lazy-load: setup may have run after the gateway started, so the
-      // service start() missed it.  Re-attempt on every prompt until loaded.
-      // The status header embeds host + project, so re-read on every call
-      // when not yet cached to pick up fresh config after setup.
-      if (agentsContext === null && initialized) {
-        agentsContext = loadAgentsContext(workspaceDir);
-      }
-      const context = agentsContext ?? (initialized ? MISSING_AGENTS_CONTEXT : BOOTSTRAP_CONTEXT);
-      if (!context) return;
-      return { prependContext: context };
+      return { prependContext: buildPromptContext(workspaceDir) };
     });
 
     // -- Agent tool ----------------------------------------------------------
@@ -119,17 +116,12 @@ const n8nAcPlugin = {
     );
 
     // -- Service -------------------------------------------------------------
-    // On gateway start: refresh the AGENTS.md cache so the agent always has
-    // up-to-date node knowledge.
     api.registerService({
       id: "n8nac-context",
       start: async () => {
-        // Invalidate so next before_prompt_build re-reads from disk.
-        agentsContext = null;
         if (isWorkspaceInitialized(workspaceDir)) {
-          agentsContext = loadAgentsContext(workspaceDir);
-          if (agentsContext) {
-            api.logger.info("[n8nac] Workspace ready — AI context loaded.");
+          if (hasAgentsContext(workspaceDir)) {
+            api.logger.info("[n8nac] Workspace ready — lightweight prompt context enabled; n8n skill available.");
           } else {
             api.logger.warn("[n8nac] Workspace ready, but AGENTS.md is missing or unreadable.");
           }
@@ -137,9 +129,7 @@ const n8nAcPlugin = {
           api.logger.info("[n8nac] Workspace not initialized. Run `openclaw n8nac:setup`.");
         }
       },
-      stop: async () => {
-        agentsContext = null;
-      },
+      stop: async () => {},
     });
   },
 };

package/openclaw.plugin.json

@@ -2,6 +2,9 @@
   "id": "n8nac",
   "name": "n8n-as-code",
   "description": "Create and manage n8n workflows from OpenClaw. Guides the AI through n8nac initialization and provides workflow tools.",
+  "skills": [
+    "skills"
+  ],
   "configSchema": {
     "type": "object",
     "additionalProperties": false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@n8n-as-code/n8nac",
-  "version": "2026.3.2-next.3",
+  "version": "2026.4.0-next.11",
   "description": "OpenClaw plugin for n8n-as-code — create and manage n8n workflows from OpenClaw",
   "keywords": [
     "n8n",
@@ -38,6 +38,7 @@
     "README.md",
     "index.ts",
     "openclaw.plugin.json",
+    "skills/",
     "src/",
     "tsconfig.json"
   ],

package/skills/n8n-architect/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: n8n-architect
+description: Use when the user explicitly wants to create, edit, validate, sync, or troubleshoot n8n workflows, asks about n8n nodes or automation, or wants to use the n8nac tool.
+---
+
+# n8n Architect
+
+Use this skill only for explicit n8n workflow work.
+
+## First steps
+
+1. Check whether `n8nac-config.json` exists in the workspace root.
+2. If the workspace is initialized, read `AGENTS.md` from the workspace root before making workflow changes. It is the detailed, workspace-specific source of truth generated by `n8nac update-ai`.
+3. If `AGENTS.md` is missing or unreadable, regenerate it with `npx --yes n8nac update-ai` or run the `openclaw n8nac:setup` command before attempting workflow authoring.
+4. If the workspace is not initialized, ask the user for the n8n host URL and API key, then use the `n8nac` tool with `action: "init_auth"` and `action: "init_project"` to complete setup yourself.
+
+## Using the n8nac tool
+
+- Use the `n8nac` tool for setup checks, workflow list/pull/push/verify, validation, and `skills` lookups.
+- Use `action: "skills"` whenever you need node search or schema details.
+- Never guess node parameters. The schema lookup is the source of truth.
+- Treat `AGENTS.md` as the authoritative workflow-engineering protocol once this skill is active.
+
+## Reading workflow files efficiently
+
+Every `.workflow.ts` file starts with a `<workflow-map>` block — a compact index generated automatically at each sync. Always read this block first before opening the rest of the file.
+
+```
+// <workflow-map>
+// Workflow : My Workflow
+// Nodes   : 12  |  Connections: 14
+//
+// NODE INDEX
+// ──────────────────────────────────────────────────────────────────
+// Property name                    Node type (short)         Flags
+// ScheduleTrigger                  scheduleTrigger
+// AgentGenerateApplication         agent                      [AI] [creds]
+// OpenaiChatModel                  lmChatOpenAi               [creds] [ai_languageModel]
+// Memory                           memoryBufferWindow         [ai_memory]
+// GithubCheckBranchRef             httpRequest                [onError→out(1)]
+//
+// ROUTING MAP
+// ──────────────────────────────────────────────────────────────────
+// ⚠️ Nodes flagged [ai_*] are NOT in the → routing — they connect via .uses()
+// ScheduleTrigger
+//   → Configuration1
+//     → BuildProfileSources → LoopOverProfileSources
+//       .out(1) → JinaReadProfileSource → LoopOverProfileSources (↩ loop)
+//
+// AI CONNECTIONS
+// AgentGenerateApplication.uses({ ai_languageModel: OpenaiChatModel, ai_memory: Memory })
+// </workflow-map>
+```
+
+### How to navigate a workflow as an agent
+
+1. Read `<workflow-map>` only — locate the property name you need.
+2. Search for that property name in the file (for example `AgentGenerateApplication =`).
+3. Read only that section — do not load the entire file into context.
+
+This avoids loading 1500+ lines when you only need to patch 10.
+
+
+### AI tool nodes
+
+When an AI agent uses tool nodes:
+
+- ✅ Search for the exact tool node first.
+- ✅ Run `npx --yes n8nac skills node-info <nodeName>` before writing parameters.
+- ✅ Connect tool nodes as arrays: `this.Agent.uses({ ai_tool: [this.Tool.output] })`.
+- ❌ Do not assume tool parameter names or reuse stale node-specific guidance.
+