n8n-architect

by EtienneLescot

Install this Skill

curl -fsSL -o n8n-architect.zip https://skill.seembox.com/api/v1/skills/n8n-architect/download && unzip n8n-architect.zip

Download n8n-architect.zip

SKILL.md About

---
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. If you need to add a second saved instance later, call `action: "init_auth"` with `newInstance: true` first.

## Using the n8nac tool

- Use the `n8nac` tool for setup checks, saved instance config management, workflow list/pull/push/verify, validation, and `skills` lookups.
- Use `action: "instance_list"` to inspect saved configs, `action: "instance_select"` to switch the active config, and `action: "instance_delete"` to remove a stale saved config.
- 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.
- When a workflow fails due to missing credentials (Class A), identify the missing credentials clearly and use the documented `n8nac` CLI commands from `AGENTS.md` (for example `npx --yes n8nac workflow credential-required <workflowId> --json`, `npx --yes n8nac credential schema <type>`, `npx --yes n8nac credential create --type <type> --name "<name>" --file cred.json --json`, and `npx --yes n8nac workflow activate <workflowId>`). Do not invent unsupported `n8nac` tool actions or CLI flags; use `--help` if you are unsure.
- When `n8nac test` reports that a webhook is not registered, treat that as a runtime-state issue first, not as a workflow-code bug. For classic Webhook/Form triggers, the test URL usually requires a manual arm step in the n8n editor (`Execute workflow` or `Listen for test event`). There is no documented public API here to arm test webhooks automatically.
- When a webhook call succeeds but the workflow still seems broken, inspect the resulting execution with the documented CLI commands from `AGENTS.md` (for example `npx --yes n8nac execution list --workflow-id <workflowId> --limit 5 --json` then `npx --yes n8nac execution get <executionId> --include-data --json`).
- For GET/HEAD webhooks, prefer `n8nac test --query <json>` when the workflow reads from `$json.query`. Do not invent flags like `--query` unless they are documented in the current `--help`.

## 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.