n8n-architect

n8n Architect

Use this skill for all n8n-as-code work: workspace readiness, environments, managed local instances, tunnels, workflow authoring, validation, sync, push, and pull.

Use {{N8NAC_CMD}} as the primary interface. Use {{N8N_MANAGER_CMD}} only for local managed runtime lifecycle, tunnels, and workflow presentation commands that are explicitly exposed by n8n-manager.

Context Root Protocol

• Treat the current context root as the directory containing n8nac-config.json, AGENTS.md, .agents/skills, and the configured workflowsPath.
• {{N8NAC_CONTEXT_ROOT_HINT}}
• Before any n8n work, first run {{N8NAC_CMD}} update-ai from the context root, then read AGENTS.md. update-ai is designed to create or refresh the n8n-as-code block without destroying existing user or agent instructions.
• Use the exact n8nac command and n8n-manager command listed in AGENTS.md. Those context-root commands override the portable examples in this skill.
• Run every {{N8NAC_CMD}} env ..., {{N8NAC_CMD}} workspace ..., {{N8NAC_CMD}} list, pull, push, validate, test, and update-ai command from the context root unless the user explicitly gives another context root.
• AGENTS.md is bootstrap context only, not a source of configuration truth.
• Do not infer environment, project, or workflowsPath from AGENTS.md.
• Before n8n work, resolve the effective context from the backend:

{{N8NAC_CMD}} env status --json

• Use the returned workflowsPath for workflow files. It is the configured workflow directory for the active environment.
• Do not reconstruct workflowsPath from environment name/id, instanceIdentifier, instanceUserIdentifier, projectId, projectName, or legacy sync fields.
• Never write n8nac-config.json, ~/.n8n-manager, or n8n-manager secret files by hand.

Workspace Readiness

Resolve the effective environment through the backend before workflow work:

{{N8NAC_CMD}} env status --json

• Treat env status --json as the source of effective workspace readiness.
• Do not infer readiness from raw files, generated agent docs, or directory names.
• A workspace .env holding N8N_HOST (plus any of N8N_API_KEY, N8N_NATIVE_MCP_URL, N8N_NATIVE_MCP_TOKEN) configures the default environment on first use: env status --json then resolves with no env add, env auth set, env use, or native-mcp configure.
• If env status --json fails because the workspace is not configured, use env add, env auth set, and env use to create or select a V4 workspace environment.
• Managed local instances remain machine-global runtime resources.
• Workspace environments remain workspace-scoped and are managed through {{N8NAC_CMD}} env ....