/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.
• 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 `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`. If it resolves with `accessStatus: "ready"`, the workspace is ready — skip steps 4-9. A resolution with `missing-api-key` or `invalid-api-key` means only the credential is missing: go to step 7. 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.
• Prefer `env add --pin` to create and pin the default environment in one process instead of a separate `env use`.
• 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