abbibo/N8N-Workflow-Builder-Agent-skills-N8N
n8n-agent-skill-system
VerifiedPrimary engineering skill for designing, generating, validating, and delivering complete, importable, production-ready n8n workflows using Antigravity and Agentic IDEs. Implements 131 automated validation rules, comprehensive node catalogs, Luxon DateTime verification, AI agent architectures, and modular subworkflows.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 3.0 KB |
| references/code-node-recipes.md | markdown | 2.6 KB |
| references/expression-syntax-guide.md | markdown | 2.6 KB |
| references/node-catalog.json | config | 95.9 KB |
| references/node-catalog.md | markdown | 5.1 KB |
| references/validation-rules-131.json | config | 15.9 KB |
| references/validation-rules-131.md | markdown | 13.1 KB |
| scripts/inspect_workflow.py | script | 1.0 KB |
| scripts/scaffold_workflow.py | script | 1.9 KB |
| scripts/validate_workflow.py | script | 21.7 KB |
| templates/ai-agent-rag-tools.json | config | 3.1 KB |
| templates/claudecode-bug-fixer.json | config | 3.6 KB |
| templates/error-trigger-handler.json | config | 2.6 KB |
| templates/paginated-api-ingestion.json | config | 3.7 KB |
| templates/scheduled-db-sync.json | config | 4.4 KB |
| templates/subworkflow-modular-child.json | config | 1.5 KB |
| templates/subworkflow-modular-parent.json | config | 2.5 KB |
| templates/webhook-crm-pipeline.json | config | 5.5 KB |
scripts/validate_workflow.py
View on GitHub#!/usr/bin/env python3
"""
N8N Workflow 131-Rule Comprehensive Validation Engine
Consolidated from Kairos, Official n8n, and Antigravity specifications.
Validates:
- JSON structure and forbidden creation fields (Rule 1, 2, 9, 12, 13)
- Node IDs, unique names, positions, valid node types (Rule 3, 4, 5, 6, 7, 8, 15, 16, 126)
- Safe typeVersions and required parameter checks (Rule 6, 41, 44, 65, 66, 71, 75, 76, 88, 95, 98, 100, 102, 117, 118, 119, 120)
- Connections graph (Main & AI ports: ai_languageModel, ai_tool, ai_memory, ai_outputParser, ai_embedding, ai_retriever) (Rule 10, 18, 20, 45, 89, 96, 97, 111)
- Expression syntax (Luxon DateTime methods, Moment.js traps, trigger expression rules) (Rule 24, 25, 26, 92, 93, 107, 112, 114, 122, 125)
- Operational logic (SplitInBatches loops, Webhook responseMode, Merge node topologies, error port wiring, Switch fallback) (Rule 42, 43, 47, 53, 56, 63, 70, 77, 80, 81, 82, 87, 90, 91, 106, 113, 115, 128)
- Credentials shape and sensitive parameter leaks (Rule 17, 46, 54, 58, 85)
"""
import sys
import os
import json
import re
from typing import Dict, List, Any, Optional
if hasattr(sys.stdout, 'reconfigure'):
try:
sys.stdout.reconfigure(encoding='utf-8')
except Exception:
pass
TRIGGER_PATTERNS = [re.compile(r'trigger', re.I), re.compile(r'Trigger$')]
NODE_TYPE_PATTERN = re.compile(r'^(@[a-z0-9-]+/[a-z0-9-]+\.|n8n-nodes-[a-z0-9-]+\.)[a-zA-Z][a-zA-Z0-9-]+$')
UUID_PATTERN = re.compile(r'^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$', re.I)
FORBIDDEN_ROOT_FIELDS = ['id', 'active', 'createdAt', 'updatedAt', 'versionId', 'meta', 'tags']
DEFAULT_CATALOG = {
"n8n-nodes-base.manualTrigger": {"safeTypeVersions": [1], "requiredParams": [], "isTrigger": True},
"n8n-nodes-base.scheduleTrigger": {"safeTypeVersions": [1, 1.1, 1.2], "requiredParams": [], "isTrigger": True},
"n8n-nodes-base.webhook": {"safeTypeVersions": [1, 1.1, 2], "requiredParams": ["httpMethod", "path"], "isTrigger": True},
"n8n-nodes-base.formTrigger": {"safeTypeVersions": [1, 2, 2.1, 2.2], "requiredParams": [], "isTrigger": True},
"n8n-nodes-base.errorTrigger": {"safeTypeVersions": [1], "requiredParams": [], "isTrigger": True},
"n8n-nodes-base.executeWorkflowTrigger": {"safeTypeVersions": [1, 1.1], "requiredParams": [], "isTrigger": True},
"@n8n/n8n-nodes-langchain.chatTrigger": {"safeTypeVersions": [1, 1.1], "requiredParams": [], "isTrigger": True},
"n8n-nodes-base.httpRequest": {"safeTypeVersions": [4.1, 4.2], "requiredParams": ["url"], "isTrigger": False},
"n8n-nodes-base.set": {"safeTypeVersions": [1, 2, 3, 3.1, 3.2, 3.3, 3.4], "requiredParams": [], "isTrigger": False},
"n8n-nodes-base.code": {"safeTypeVersions": [1, 2], "requiredParams": [], "isTrigger": False},
"n8n-nodes-base.if": {"safeTypeVersions": [1, 2, 2.1, 2.2], "requiredParams": [], "isTrigger": False},
"n8n-nodes-base.switch": {"safeTypeVersions": [1, 2, 3, 3.1, 3.2], "requiredParams": [], "isTrigger": False},
"n8n-nodes-base.filter": {"safeTypeVersions": [1, 2, 2.1, 2.2], "requiredParams": [], "isTrigger": False},
"n8n-nodes-base.merge": {"safeTypeVersions": [1, 2, 2.1, 3], "requiredParams": [], "isTrigger": False},
"n8n-nodes-base.splitInBatches": {"safeTypeVersions": [1, 2, 3], "requiredParams": [], "isTrigger": False},
"n8n-nodes-base.respondToWebhook": {"safeTypeVersions": [1, 1.1], "requiredParams": [], "isTrigger": False},
"n8n-nodes-base.executeWorkflow": {"safeTypeVersions": [1, 1.1, 1.2], "requiredParams": [], "isTrigger": False},
"n8n-nodes-base.postgres": {"safeTypeVersions": [1, 2, 2.1, 2.2, 2.3, 2.4, 2.5], "requiredParams": [], "credentialType": "postgres", "isTrigger": False},
"n8n-nodes-base.mySql": {"safeTypeVersions": [1, 2, 2.1, 2.2, 2.3, 2.4], "requiredParams": [], "credentialType": "mySql", "isTrigger": False},
"n8n-nodes-base.slack": {"safeTypeVersions": [1, 2, 2.1, 2.2], "requiredParams": [], "credentialType": "slackApi", "isTrigger": False},
"n8n-nodes-base.gmail": {"safeTypeVersions": [1, 2, 2.1], "requiredParams": [], "credentialType": "gmailOAuth2", "isTrigger": False},
"n8n-nodes-base.telegram": {"safeTypeVersions": [1, 1.1, 1.2], "requiredParams": [], "credentialType": "telegramApi", "isTrigger": False},
"@n8n/n8n-nodes-langchain.agent": {"safeTypeVersions": [1, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7], "requiredParams": [], "isTrigger": False},
"@n8n/n8n-nodes-langchain.chainLlm": {"safeTypeVersions": [1, 1.1, 1.2, 1.3, 1.4, 1.5], "requiredParams": [], "isTrigger": False},
"@n8n/n8n-nodes-langchain.lmChatOpenAi": {"safeTypeVersions": [1, 1.1, 1.2], "requiredParams": ["model"], "credentialType": "openAiApi", "isTrigger": False},
"@n8n/n8n-nodes-langchain.lmChatAnthropic": {"safeTypeVersions": [1, 1.1, 1.2], "requiredParams": ["model"], "credentialType": "anthropicApi", "isTrigger": False},
"@n8n/n8n-nodes-langchain.lmChatGoogleGemini": {"safeTypeVersions": [1], "requiredParams": ["modelName"], "credentialType": "googlePalmApi", "isTrigger": False},
"@n8n/n8n-nodes-langchain.memoryBufferWindow": {"safeTypeVersions": [1, 1.1, 1.2, 1.3], "requiredParams": [], "isTrigger": False},
"@n8n/n8n-nodes-langchain.toolHttpRequest": {"safeTypeVersions": [1, 1.1], "requiredParams": ["url"], "isTrigger": False},
"@n8n/n8n-nodes-langchain.toolCode": {"safeTypeVersions": [1, 1.1], "requiredParams": [], "isTrigger": False},
"@n8n/n8n-nodes-langchain.toolWorkflow": {"safeTypeVersions": [1, 1.1, 1.2], "requiredParams": [], "isTrigger": False},
"@n8n/n8n-nodes-langchain.outputParserStructured": {"safeTypeVersions": [1, 1.1, 1.2], "requiredParams": ["jsonSchema"], "isTrigger": False},
"@n8n/n8n-nodes-langchain.vectorStorePinecone": {"safeTypeVersions": [1, 1.1], "requiredParams": ["pineconeIndex"], "credentialType": "pineconeApi", "isTrigger": False},
"@n8n/n8n-nodes-langchain.embeddingsOpenAi": {"safeTypeVersions": [1, 1.1], "requiredParams": [], "credentialType": "openAiApi", "isTrigger": False},
"n8n-nodes-claudecode.claudeCode": {"safeTypeVersions": [1], "requiredParams": ["prompt"], "credentialType": "claudeCodeApi", "isTrigger": False}
}
class ValidationIssue:
def __init__(self, rule_id: int, severity: str, message: str, node_name: Optional[str] = None):
self.rule_id = rule_id
self.severity = severity.lower()
self.message = message
self.node_name = node_name
def to_dict(self):
return {
'ruleId': self.rule_id,
'severity': self.severity,
'message': self.message,
'nodeName': self.node_name
}
def __str__(self):
prefix = f"[Rule {self.rule_id:03d}][{self.severity.upper()}]"
node_part = f" (Node: '{self.node_name}')" if self.node_name else ""
return f"{prefix}{node_part} {self.message}"
class N8nWorkflowValidator:
def __init__(self, catalog_path: Optional[str] = None):
self.catalog = DEFAULT_CATALOG.copy()
if catalog_path and os.path.exists(catalog_path):
try:
with open(catalog_path, 'r', encoding='utf-8') as f:
cat_json = json.load(f)
for item in cat_json.get('registry', []):
self.catalog[item['type']] = item
except Exception:
pass
def validate(self, workflow: Dict[str, Any]) -> List[ValidationIssue]:
issues: List[ValidationIssue] = []
nodes = workflow.get('nodes', [])
connections = workflow.get('connections', {})
settings = workflow.get('settings', {})
# Rule 1: name is a non-empty string
if not workflow.get('name') or not isinstance(workflow.get('name'), str) or not workflow.get('name').strip():
issues.append(ValidationIssue(1, 'error', "Workflow 'name' must be a non-empty string."))
# Rule 2: nodes is array with >= 1 element
if not isinstance(nodes, list) or len(nodes) == 0:
issues.append(ValidationIssue(2, 'error', "Workflow must contain a non-empty 'nodes' array."))
return issues
# Rule 9: connections is a plain dict
if not isinstance(connections, dict):
issues.append(ValidationIssue(9, 'error', "Workflow 'connections' must be a plain object."))
# Rule 12: forbidden fields absent on creation
for field in FORBIDDEN_ROOT_FIELDS:
if field in workflow and workflow[field] is not None:
issues.append(ValidationIssue(12, 'warn', f"Forbidden or system-managed field '{field}' found at workflow root."))
# Rule 13: settings object
if 'settings' in workflow and not isinstance(settings, dict):
issues.append(ValidationIssue(13, 'error', "'settings' property must be an object."))
node_ids = set()
node_names = set()
has_trigger = False
webhook_endpoints = set()
has_respond_to_webhook = False
has_webhook_response_mode = False
for node in nodes:
name = node.get('name')
nid = node.get('id')
ntype = node.get('type')
tver = node.get('typeVersion')
pos = node.get('position')
params = node.get('parameters', {}) or {}
creds = node.get('credentials', {}) or {}
# Rule 3: every node has non-empty id
if not nid or not isinstance(nid, str):
issues.append(ValidationIssue(3, 'error', "Node is missing a valid 'id'.", name))
else:
# Rule 4: node ids are unique
if nid in node_ids:
issues.append(ValidationIssue(4, 'error', f"Duplicate node ID '{nid}'.", name))
node_ids.add(nid)
# Rule 126: Node ID UUID v4 format
if not UUID_PATTERN.match(nid):
issues.append(ValidationIssue(126, 'warn', f"Node id '{nid}' is not a standard UUID v4 string.", name))
# Rule 8: non-empty name
if not name or not isinstance(name, str) or not name.strip():
issues.append(ValidationIssue(8, 'error', "Node is missing a non-empty 'name'."))
else:
# Rule 16: unique node names
if name in node_names:
issues.append(ValidationIssue(16, 'error', f"Duplicate node name '{name}'. Names must be unique.", name))
node_names.add(name)
# Rule 5: non-empty type
if not ntype or not isinstance(ntype, str):
issues.append(ValidationIssue(5, 'error', "Node is missing a 'type'.", name))
else:
# Rule 15: valid node type string pattern
if not NODE_TYPE_PATTERN.match(ntype):
issues.append(ValidationIssue(15, 'error', f"Invalid node type syntax '{ntype}'.", name))
# Rule 6: positive typeVersion
if tver is None or not (isinstance(tver, (int, float))) or tver <= 0:
issues.append(ValidationIssue(6, 'error', f"Node typeVersion '{tver}' must be a positive number.", name))
# Rule 7: valid [x, y] position
if not isinstance(pos, list) or len(pos) != 2 or not all(isinstance(p, (int, float)) for p in pos):
issues.append(ValidationIssue(7, 'error', "Node 'position' must be an array of two numbers [x, y].", name))
# Check Trigger status
cat_entry = self.catalog.get(ntype, {})
is_trigger = cat_entry.get('isTrigger', False) or any(p.search(ntype or '') for p in TRIGGER_PATTERNS)
if is_trigger:
has_trigger = True
# Rule 17: credentials shape
if isinstance(creds, dict):
for cred_key, cred_val in creds.items():
if isinstance(cred_val, dict):
if 'id' not in cred_val or 'name' not in cred_val:
issues.append(ValidationIssue(17, 'error', f"Credential entry '{cred_key}' must contain 'id' and 'name'.", name))
else:
issues.append(ValidationIssue(17, 'error', f"Credential entry '{cred_key}' must be an object.", name))
# Rule 58: credential type check
expected_cred = cat_entry.get('credentialType')
expected_creds = cat_entry.get('credentialTypes') or ([expected_cred] if expected_cred else [])
if expected_creds and creds:
for k in creds.keys():
if k not in expected_creds:
issues.append(ValidationIssue(58, 'warn', f"Credential key '{k}' might not match expected credential types for this node.", name))
# Rule 63: Webhook path + method collision
if ntype == 'n8n-nodes-base.webhook':
method = params.get('httpMethod', 'GET')
path = params.get('path', '')
if params.get('responseMode') == 'responseNode':
has_webhook_response_mode = True
key = f"{method}:{path}"
if key in webhook_endpoints:
issues.append(ValidationIssue(63, 'error', f"Duplicate Webhook path '{path}' and method '{method}'.", name))
webhook_endpoints.add(key)
if ntype == 'n8n-nodes-base.respondToWebhook':
has_respond_to_webhook = True
# Rule 65: SplitInBatches batchSize
if ntype == 'n8n-nodes-base.splitInBatches':
bs = params.get('batchSize', 10)
if isinstance(bs, (int, float)) and bs <= 0:
issues.append(ValidationIssue(65, 'error', f"SplitInBatches batchSize must be > 0 (got {bs}).", name))
# Rule 66: HTTP Request URL prefix
if ntype == 'n8n-nodes-base.httpRequest':
url = str(params.get('url', ''))
if url and not url.startswith('http://') and not url.startswith('https://') and not url.startswith('='):
issues.append(ValidationIssue(66, 'error', f"HTTP Request URL '{url}' missing http:// or https:// protocol prefix.", name))
if 'webhook-test' in url:
issues.append(ValidationIssue(79, 'warn', f"HTTP Request URL contains temporary test endpoint 'webhook-test'.", name))
# Rule 127: Code node language mismatch
if ntype == 'n8n-nodes-base.code':
lang = params.get('language', 'javaScript')
if lang == 'javaScript' and 'pythonCode' in params and not params.get('jsCode'):
issues.append(ValidationIssue(127, 'warn', "Code node language is JavaScript but contains 'pythonCode' instead of 'jsCode'.", name))
elif lang == 'python' and 'jsCode' in params and not params.get('pythonCode'):
issues.append(ValidationIssue(127, 'warn', "Code node language is Python but contains 'jsCode' instead of 'pythonCode'.", name))
# Rule 128: onError continueErrorOutput requires error port wiring
on_error = node.get('onError')
if on_error == 'continueErrorOutput':
main_conns = connections.get(name, {}).get('main', [])
if len(main_conns) < 2 or not main_conns[1]:
issues.append(ValidationIssue(128, 'warn', "onError is set to 'continueErrorOutput' but dedicated error output port (index 1) has no outgoing connection.", name))
self._validate_expressions(params, name, is_trigger, issues)
# Rule 14: At least one trigger present
if not has_trigger:
issues.append(ValidationIssue(14, 'warn', "Workflow has no trigger node (e.g. Schedule, Webhook, Chat, Manual)."))
# Rule 90: respondToWebhook pairing check
if has_respond_to_webhook and not has_webhook_response_mode:
issues.append(ValidationIssue(90, 'error', "respondToWebhook node is present but no Webhook trigger has responseMode='responseNode'."))
self._validate_connections(connections, nodes, node_names, issues)
return issues
def _validate_expressions(self, obj: Any, node_name: str, is_trigger: bool, issues: List[ValidationIssue]):
if isinstance(obj, str):
if '{{' in obj or obj.startswith('='):
expr_text = obj
if is_trigger and re.search(r'\$json\b', expr_text):
issues.append(ValidationIssue(107, 'warn', "Trigger node expression references '$json' which is undefined at trigger time.", node_name))
if re.search(r'(\$now|\$today|DateTime)(\.[a-zA-Z0-9_]+)*\.toISOString\(', expr_text):
issues.append(ValidationIssue(92, 'error', "Expression calls .toISOString() on Luxon DateTime. Use .toISO() instead.", node_name))
if re.search(r'(\$now|\$today|DateTime)(\.[a-zA-Z0-9_]+)*\.format\(', expr_text):
issues.append(ValidationIssue(93, 'warn', "Expression calls Moment.js method .format(). Use Luxon's .toFormat() instead.", node_name))
if re.search(r'(\$now|\$today|DateTime)(\.[a-zA-Z0-9_]+)*\.(add|subtract)\(', expr_text):
issues.append(ValidationIssue(112, 'error', "Expression calls Moment.js method .add()/.subtract(). Use Luxon's .plus()/.minus() instead.", node_name))
if re.search(r'(\$now|\$today|DateTime)(\.[a-zA-Z0-9_]+)*\.(plus|minus)\(\s*\d+\s*,', expr_text):
issues.append(ValidationIssue(122, 'warn', "Luxon .plus()/.minus() expects object argument e.g. {days: 1}, not positional parameters (n, 'days').", node_name))
if re.search(r'\.toFormat\([\'"][^\'"]*(YYYY|DD)[^\'"]*[\'"]\)', expr_text):
issues.append(ValidationIssue(125, 'warn', "Luxon .toFormat() uses uppercase 'YYYY' or 'DD'. Use lowercase 'yyyy' and 'dd'.", node_name))
elif isinstance(obj, dict):
for k, v in obj.items():
self._validate_expressions(v, node_name, is_trigger, issues)
elif isinstance(obj, list):
for item in obj:
self._validate_expressions(item, node_name, is_trigger, issues)
def _validate_connections(self, connections: Dict[str, Any], nodes: List[Dict[str, Any]], node_names: set, issues: List[ValidationIssue]):
for src_name, conns in connections.items():
if src_name not in node_names:
issues.append(ValidationIssue(10, 'error', f"Connection source node '{src_name}' does not exist in workflow nodes."))
continue
if isinstance(conns, dict):
for conn_type, outputs in conns.items():
if not isinstance(outputs, list):
continue
for output_index, targets in enumerate(outputs):
if not isinstance(targets, list):
continue
for target_spec in targets:
target_name = target_spec.get('node')
if not target_name:
issues.append(ValidationIssue(10, 'error', "Connection entry missing destination 'node' name.", src_name))
continue
if target_name not in node_names:
issues.append(ValidationIssue(10, 'error', f"Connection target node '{target_name}' does not exist in workflow nodes.", src_name))
for node in nodes:
ntype = node.get('type', '')
nname = node.get('name', '')
if ntype in ['@n8n/n8n-nodes-langchain.agent', '@n8n/n8n-nodes-langchain.chainLlm']:
has_lm = False
for src_name, conns in connections.items():
lm_conns = conns.get('ai_languageModel', [])
for group in lm_conns:
for target in group:
if target.get('node') == nname:
has_lm = True
break
if not has_lm:
issues.append(ValidationIssue(45, 'error', f"AI Agent / Chain node '{nname}' has no ai_languageModel sub-node connected.", nname))
def main():
if len(sys.argv) < 2:
print("Usage: python validate_workflow.py <path_to_workflow_json> [--json]")
sys.exit(1)
json_output = '--json' in sys.argv
file_path = [arg for arg in sys.argv[1:] if arg != '--json'][0]
if not os.path.exists(file_path):
print(f"Error: File not found: {file_path}")
sys.exit(1)
with open(file_path, 'r', encoding='utf-8') as f:
try:
workflow = json.load(f)
except Exception as e:
print(f"JSON Parse Error: {e}")
sys.exit(1)
catalog_path = os.path.join(os.path.dirname(__file__), '..', 'references', 'node-catalog.json')
validator = N8nWorkflowValidator(catalog_path if os.path.exists(catalog_path) else None)
issues = validator.validate(workflow)
errors = [i for i in issues if i.severity == 'error']
warns = [i for i in issues if i.severity == 'warn']
if json_output:
res = {
'valid': len(errors) == 0,
'errorCount': len(errors),
'warnCount': len(warns),
'issues': [i.to_dict() for i in issues]
}
print(json.dumps(res, indent=2))
else:
print("=" * 70)
print(f"N8N WORKFLOW VALIDATION REPORT: {os.path.basename(file_path)}")
print("=" * 70)
status_text = "[PASSED]" if len(errors) == 0 else "[FAILED]"
print(f"Status: {status_text}")
print(f"Errors: {len(errors)} | Warnings: {len(warns)}\n")
if issues:
print("Issues identified:")
for issue in issues:
print(f" {issue}")
else:
print(" [OK] No issues found! Workflow conforms to all 131 validation rules.")
print("=" * 70)
if errors:
sys.exit(1)
sys.exit(0)
if __name__ == '__main__':
main()
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |