n8n Studio

Plugin de automatizacion guiada para n8n que cubre el ciclo completo: levanta requerimientos con un wizard interactivo, genera Automation Specs, construye workflows via API con agentes especializados, ejecuta pruebas de aceptacion y gestiona deployment entre ambientes (dev a prod). Disenado para el equipo tecnico o PM que necesite automatizar procesos con n8n sin escribir JSON manualmente.

Prerequisitos

• Claude Code con soporte de plugins
• n8n MCP (n8n-mcp) configurado como servidor MCP remoto -- obligatorio para todo el pipeline
• Acceso a instancia n8n de desarrollo (dev) y opcionalmente produccion (prod)
• API Key de n8n generada en Settings > API de la instancia n8n
• Engram para persistencia de estado entre agentes del pipeline

Configuracion del MCP (obligatorio, una sola vez)

claude mcp add --transport http n8n-mcp https://n8n-mcp.codetrain.cloud/mcp \
  --header "Authorization: Bearer <token>" \
  --scope user

Verificar con /mcp dentro de Claude Code. El health check esta en https://n8n-mcp.codetrain.cloud/health.

Nota: Este plugin NO tiene .claude-plugin/plugin.json individual (excepcion documentada). La version se registra directamente en el marketplace.json de la raiz.

Skills

El plugin expone tres skills que cubren todo el ciclo de vida de una automatizacion: un wizard para capturar requerimientos, un orquestador que coordina la construccion, y un gestor de deployment para promover a produccion.

Skill	Descripcion	Invocacion	Tools permitidos
automation-wizard	Wizard interactivo de 8 fases (5 de negocio + 3 auto-tecnicas). Entrevista al usuario sobre objetivo, sistemas, datos, reglas y errores. Valida nodos contra n8n MCP. Genera un Automation Spec (.md).	/n8n-studio:automation-wizard [descripcion]	(no declarados en frontmatter -- hereda del plugin; usa n8n-mcp: search_nodes, get_node, search_templates, tools_documentation)
n8n-orchestrator	Orquestador del pipeline de construccion. Delega a 4 agentes especializados en secuencia: analyst -> builder -> tester -> reviewer. Soporta fix cycles (max 2).	/n8n-studio:n8n-orchestrator [ruta-spec.md]	Read, Grep, Glob, Agent
n8n-deploy	Gestiona deployment de workflows entre ambientes. Exporta de dev, importa en prod, verifica. Si solo hay un ambiente, exporta como JSON para import manual. Requiere invocacion manual explicita.	/n8n-studio:n8n-deploy [workflow-id]	Read, Grep, Glob, mcp__n8n-mcp__n8n_get_workflow, mcp__n8n-mcp__n8n_create_workflow, mcp__n8n-mcp__n8n_validate_workflow, mcp__n8n-mcp__n8n_list_workflows, mcp__n8n-mcp__n8n_health_check

Notas de frontmatter: - n8n-deploy tiene disable-model-invocation: true -- solo se activa por invocacion manual, no por auto-activacion. - n8n-orchestrator soporta subcomandos: test <id>, review <id>, rebuild <id>.

Agentes

El orquestador delega cada fase del pipeline a un agente especializado. El analyst prepara el contexto tecnico, el builder construye el workflow via API, el tester ejecuta criterios de aceptacion, y el reviewer valida buenas practicas antes del deploy.

Agente	Rol	Modelo	Tools	maxTurns
n8n-analyst	Lee el Automation Spec, valida nodos con search_nodes/get_node, busca templates, genera Build Plan.	sonnet	Read, Grep, Glob, n8n-mcp: search_nodes, get_node, search_templates, get_template, tools_documentation, n8n_list_workflows (disallowed: Write, Edit, Agent, n8n_create/update/delete_workflow)	No especificado
n8n-builder	Construye workflows via n8n API. Configura nodos, conexiones, error handling. Valida y autofix.	inherit	Read, Grep, Glob, n8n-mcp: n8n_create_workflow, n8n_get_workflow, n8n_update_full_workflow, n8n_update_partial_workflow, n8n_validate_workflow, n8n_autofix_workflow, n8n_deploy_template, get_node, search_nodes, tools_documentation (disallowed: Agent, n8n_delete_workflow)	No especificado
n8n-tester	Ejecuta criterios de aceptacion del spec contra el workflow en n8n dev. Genera Test Report con PASS/FAIL por cada AC.	sonnet	Read, Grep, Glob, Bash, n8n-mcp: n8n_test_workflow, n8n_get_workflow, n8n_executions, n8n_validate_workflow, n8n_update_partial_workflow, get_node (disallowed: Edit, Agent, n8n_create/delete_workflow)	No especificado
n8n-reviewer	Revisa workflow contra checklist de buenas practicas: error handling, naming, performance, seguridad, robustez. Genera Review Report con veredicto.	sonnet	Read, Grep, Glob, n8n-mcp: n8n_get_workflow, n8n_validate_workflow, get_node, tools_documentation (disallowed: Write, Edit, Agent, n8n_create/update/delete_workflow)	No especificado

Flujo de trabajo

El pipeline sigue un DAG lineal con un ciclo de correccion opcional. El wizard es independiente y se ejecuta antes; el orquestador toma su output como input.

1. Automation Wizard (/n8n-studio:automation-wizard) -- Wizard interactivo de 8 fases. Fases 1-5 son de negocio (Claude pregunta, usuario responde): objetivo y trigger, sistemas e integraciones, flujo de datos, reglas de negocio, error handling. Fases 6-8 son auto-tecnicas (Claude genera, usuario confirma): workflow design con nodos validados, criterios de aceptacion, assembly del Automation Spec. Guarda patrones en Engram para reutilizar.
2. Analisis (n8n-analyst) -- Lee el Automation Spec, valida cada nodo con search_nodes y get_node, busca templates relevantes, genera Build Plan con nodos, conexiones, configuracion y credenciales necesarias.
3. Construccion (n8n-builder) -- Construye workflow completo en n8n via API siguiendo el Build Plan. Agrega error handling obligatorio (Error Trigger + notificacion). Valida y autofix. Reporta credenciales faltantes.
4. Checkpoint de Credenciales (orquestador, interactivo) -- OBLIGATORIO antes de testing. Muestra lista de credenciales pendientes con instrucciones para configurarlas en n8n UI. Pausa el pipeline hasta confirmacion del usuario.
5. Testing (n8n-tester) -- Ejecuta cada criterio de aceptacion del spec. Si >70% pasan, continua. Si no, activa fix cycle (max 2). Genera Test Report.
6. Review (n8n-reviewer) -- Revisa buenas practicas: error handling, naming, performance, seguridad, robustez. Veredicto: APPROVED, NEEDS_CHANGES o BLOCKED.
7. Deploy (/n8n-studio:n8n-deploy) -- Invocacion manual separada. Exporta workflow de dev, importa en prod, verifica. Si solo hay un ambiente, exporta como JSON.

Contratos de datos

Engram

El estado del pipeline se persiste bajo el proyecto n8n-studio en Engram:

Topic Key	Contenido	Escrito por
pipeline/automation-spec	Ruta al Automation Spec	Orquestador
pipeline/build-plan	Build Plan del analyst	n8n-analyst
pipeline/workflow-id	ID del workflow creado	n8n-builder
pipeline/test-report	Resultados de tests	n8n-tester
pipeline/review-report	Review de calidad	n8n-reviewer
pipeline/state	Estado actual del DAG	Orquestador
patterns/[tipo]	Patrones de automatizacion reutilizables	automation-wizard

GitHub

Sin contrato formal documentado. El plugin no interactua directamente con GitHub; los Automation Specs se guardan como archivos locales en el directorio del proyecto.

Hooks

El plugin incluye hooks para garantizar calidad en la creacion y deployment de workflows.

Evento	Matcher	Tipo	Descripcion
PostToolUse	mcp__n8n-mcp__n8n_create_workflow	command	Ejecuta workflow-validate.sh despues de crear un workflow para validacion adicional
PreToolUse	mcp__n8n-mcp__n8n_deploy_template	prompt	Antes de deployar: verifica que el workflow tenga test report aprobado en Engram. Si no existe o los tests fallaron, BLOQUEA la accion.

Configuracion para proyectos

Copiar plugins/n8n-studio/examples/CLAUDE.md a la raiz del proyecto. La configuracion incluye:

engram_project: "[nombre-proyecto]-n8n"
n8n_dev_url: "[url-de-tu-n8n-dev]"
n8n_prod_url: "[url-de-tu-n8n-prod]"

Ademas: - Configurar el MCP n8n-mcp en ~/.claude.json con tipo HTTP y token de autorizacion - Crear directorio automation-specs/ para almacenar los specs generados - Convenciones: workflows con prefijo [N8N-STUDIO], specs con nombre automation-spec-[nombre].md - Credenciales se configuran manualmente en n8n UI antes de ejecutar tests

Integración con Doc-Gen

Después de crear y desplegar workflows con n8n-orchestrator, se recomienda correr doc-gen para mantener la documentación del proyecto actualizada.

Cuándo	Comando
Después de crear y desplegar workflows con n8n-orchestrator	/doc-gen:doc-modulo {path-del-proyecto}
Verificación periódica	/doc-gen:doc-sync

Limitaciones conocidas

• Sin plugin.json individual -- excepcion documentada; la version se gestiona solo en marketplace.json
• Sesiones de MCP tienen timeout de 60 min -- wizards largos pueden requerir reconexion
• Un solo ambiente por MCP -- para multi-ambiente (dev/prod) se necesitan dos MCPs o multi-tenant habilitado
• Credenciales no se gestionan via API -- el usuario debe configurarlas manualmente en la UI de n8n
• n8n_test_workflow solo funciona con triggers webhook/form/chat -- para otros triggers, el tester agrega un webhook temporal
• Max 2 fix cycles -- si despues de 2 iteraciones los tests siguen fallando, el pipeline se detiene para decision manual
• No tiene docs/ propios -- la documentacion tecnica de nodos y gotchas vive dentro de los agents/*.md
• Los agentes no tienen maxTurns definido -- dependen del orquestador para control de flujo