/n8n-architect

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 n8n-as-code in the current context root.

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 `npx --yes n8nac` as the primary interface. Use `npx --yes @n8n-as-code/n8n-manager` 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`.
• Generated context root hint: not embedded. Use the shell launch directory or the workspace path explicitly given by the user.
• Before any n8n work, first run `npx --yes n8nac 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 `npx --yes n8nac env ...`, `npx --yes n8nac workspace ...`, `npx --yes n8nac 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:

npx --yes n8nac 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:

npx --yes n8nac 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.
• 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 `npx --yes n8nac env ...`.

Bootstrap Order

1. `cd` to the context root. 2. Run `npx --yes n8nac update-ai`, then read `AGENTS.md`. 3. Run `npx --yes n8nac env status --json`. 4. If the context root is not ready, inspect managed local instances with `npx --yes @n8n-as-code/n8n-manager instance list`. 5. Reuse an existing environment or managed local instance when suitable. 6. If no suitable environment exists, stop and ask the user whether they want to connect a remote n8n URL or create/reuse a managed local n8n instance. Do not create infrastructure by default. If the user chooses a managed local instance, ask separately whether they want a public tunnel. 7. Ask for host/API key only for an explicitly remote n8n environment. 8. Configure the environment with:

npx --yes n8nac env add <name> --base-url <url> --workflows-path workflows/<name>
npx --yes n8nac env auth set <name> --api-key-stdin
npx --yes n8nac env use <name>

For a managed local instance:

npx --yes n8nac env add Local --managed-instance <id> --workflows-path workflows/local
npx --yes n8nac env use Local

9. Run `npx --yes n8nac update-ai` after changing environments when the facade does not do it automatically.

Environments

Use `npx --yes n8nac env ...` for workspace environments, remote URLs, active environment, API-key binding, projects, and workflow paths.

npx --yes n8nac env status --json
npx --yes n8nac env list
npx --yes n8nac env add <name> --base-url <url> --workflows-path workflows/<name>
npx --yes n8nac env auth set <name> --api-key-stdin
npx --yes n8nac env use <name>

• Prefer `--api-key-stdin` for API keys.
• Do not pass secrets inline in shell arguments.
• `env auth set` binds the key to one environment, so several environments may share a base URL with one key each. Run it once per environment; `apiKeySource` in `env status --json` is `workspace-environment` when the environment uses its own key.
• Do not ask for host/API key when the user wants a managed local Docker instance.
• Do not print API keys or credential secret values back to the user.
• If a command or flag is unfamiliar, run `npx --yes n8nac env --help` or `npx --yes n8nac env <subcommand> --help`.

Attach a managed local instance to the workspace with `npx --yes n8nac env ...`:

npx --yes n8nac env add Local --managed-instance <id> --workflows-path workflows/local
npx --yes n8nac env use Local

Managed Local Runtime

Use `npx --yes @n8n-as-code/n8n-manager` only for local managed instance lifecycle, tunnels, and workflow presentation commands that are part of the local runtime layer.

Inspect existing managed instances before changing local machine state:

npx --yes @n8n-as-code/n8n-manager instance list
npx --yes @n8n-as-code/n8n-manager instance --help
npx --yes @n8n-as-code/n8n-manager config get

Do not invent n8n-manager subcommands. Use `npx --yes @n8n-as-code/n8n-manager <subcommand> --help` when unsure.

When the context root is not configured and no suitable existing instance is available, stop and ask the user to choose. Do not create infrastructure by default.

Present these choices clearly:

• use an ex