Initial commit
This commit is contained in:
Zhongwei Li
290
skills/n8n-validation-expert/README.md
Normal file
290
skills/n8n-validation-expert/README.md
Normal file
@@ -0,0 +1,290 @@
|
||||
# n8n Validation Expert
|
||||
|
||||
Expert guidance for interpreting and fixing n8n validation errors.
|
||||
|
||||
## Overview
|
||||
|
||||
**Skill Name**: n8n Validation Expert
|
||||
**Priority**: Medium
|
||||
**Purpose**: Interpret validation errors and guide systematic fixing through the validation loop
|
||||
|
||||
## The Problem This Solves
|
||||
|
||||
Validation errors are common:
|
||||
|
||||
- Validation often requires iteration (79% lead to feedback loops)
|
||||
- **7,841 validate → fix cycles** (avg 23s thinking + 58s fixing)
|
||||
- **2-3 iterations** average to achieve valid configuration
|
||||
|
||||
**Key insight**: Validation is an iterative process, not a one-shot fix!
|
||||
|
||||
## What This Skill Teaches
|
||||
|
||||
### Core Concepts
|
||||
|
||||
1. **Error Severity Levels**
|
||||
- Errors (must fix) - Block execution
|
||||
- Warnings (should fix) - Don't block but indicate issues
|
||||
- Suggestions (optional) - Nice-to-have improvements
|
||||
|
||||
2. **The Validation Loop**
|
||||
- Configure → Validate → Read errors → Fix → Validate again
|
||||
- Average 2-3 iterations to success
|
||||
- 23 seconds thinking + 58 seconds fixing per cycle
|
||||
|
||||
3. **Validation Profiles**
|
||||
- `minimal` - Quick checks, most permissive
|
||||
- `runtime` - Recommended for most use cases
|
||||
- `ai-friendly` - Reduces false positives for AI workflows
|
||||
- `strict` - Maximum safety, many warnings
|
||||
|
||||
4. **Auto-Sanitization System**
|
||||
- Automatically fixes operator structure issues
|
||||
- Runs on every workflow save
|
||||
- Fixes binary/unary operator problems
|
||||
- Adds IF/Switch metadata
|
||||
|
||||
5. **False Positives**
|
||||
- Not all warnings need fixing
|
||||
- 40% of warnings are acceptable in context
|
||||
- Use `ai-friendly` profile to reduce by 60%
|
||||
- Document accepted warnings
|
||||
|
||||
## File Structure
|
||||
|
||||
```
|
||||
n8n-validation-expert/
|
||||
├── SKILL.md (690 lines)
|
||||
│ Core validation concepts and workflow
|
||||
│ - Validation philosophy
|
||||
│ - Error severity levels
|
||||
│ - The validation loop pattern
|
||||
│ - Validation profiles
|
||||
│ - Common error types
|
||||
│ - Auto-sanitization system
|
||||
│ - Workflow validation
|
||||
│ - Recovery strategies
|
||||
│ - Best practices
|
||||
│
|
||||
├── ERROR_CATALOG.md (865 lines)
|
||||
│ Complete error reference with examples
|
||||
│ - 9 error types with real examples
|
||||
│ - missing_required (45% of errors)
|
||||
│ - invalid_value (28%)
|
||||
│ - type_mismatch (12%)
|
||||
│ - invalid_expression (8%)
|
||||
│ - invalid_reference (5%)
|
||||
│ - operator_structure (2%, auto-fixed)
|
||||
│ - Recovery patterns
|
||||
│ - Summary with frequencies
|
||||
│
|
||||
├── FALSE_POSITIVES.md (669 lines)
|
||||
│ When warnings are acceptable
|
||||
│ - Philosophy of warning acceptance
|
||||
│ - 6 common false positive types
|
||||
│ - When acceptable vs when to fix
|
||||
│ - Validation profile strategies
|
||||
│ - Decision framework
|
||||
│ - Documentation template
|
||||
│ - Known n8n issues (#304, #306, #338)
|
||||
│
|
||||
└── README.md (this file)
|
||||
Skill metadata and statistics
|
||||
```
|
||||
|
||||
**Total**: ~2,224 lines across 4 files
|
||||
|
||||
## Common Error Types
|
||||
|
||||
| Error Type | Priority | Auto-Fix | Severity |
|
||||
|---|---|---|---|
|
||||
| missing_required | Highest | ❌ | Error |
|
||||
| invalid_value | High | ❌ | Error |
|
||||
| type_mismatch | Medium | ❌ | Error |
|
||||
| invalid_expression | Medium | ❌ | Error |
|
||||
| invalid_reference | Low | ❌ | Error |
|
||||
| operator_structure | Low | ✅ | Warning |
|
||||
|
||||
## Key Insights
|
||||
|
||||
### 1. Validation is Iterative
|
||||
Don't expect to get it right on the first try. Multiple validation cycles (typically 2-3) are normal and expected!
|
||||
|
||||
### 2. False Positives Exist
|
||||
Many validation warnings are acceptable in production workflows. This skill helps you recognize which ones to address vs. which to ignore.
|
||||
|
||||
### 3. Auto-Sanitization Works
|
||||
Certain error types (like operator structure issues) are automatically fixed by n8n. Don't waste time manually fixing these!
|
||||
|
||||
### 4. Profile Matters
|
||||
- `ai-friendly` reduces false positives by 60%
|
||||
- `runtime` is the sweet spot for most use cases
|
||||
- `strict` has value pre-production but is noisy
|
||||
|
||||
### 5. Error Messages Help
|
||||
Validation errors include fix guidance - read them carefully!
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Example 1: Basic Validation Loop
|
||||
|
||||
```javascript
|
||||
// Iteration 1
|
||||
let config = {
|
||||
resource: "channel",
|
||||
operation: "create"
|
||||
};
|
||||
|
||||
const result1 = validate_node_operation({
|
||||
nodeType: "nodes-base.slack",
|
||||
config,
|
||||
profile: "runtime"
|
||||
});
|
||||
// → Error: Missing "name"
|
||||
|
||||
// Iteration 2
|
||||
config.name = "general";
|
||||
const result2 = validate_node_operation({...});
|
||||
// → Valid! ✅
|
||||
```
|
||||
|
||||
### Example 2: Handling False Positives
|
||||
|
||||
```javascript
|
||||
// Run validation
|
||||
const result = validate_node_operation({
|
||||
nodeType: "nodes-base.slack",
|
||||
config,
|
||||
profile: "runtime"
|
||||
});
|
||||
|
||||
// Fix errors (must fix)
|
||||
if (!result.valid) {
|
||||
result.errors.forEach(error => {
|
||||
console.log(`MUST FIX: ${error.message}`);
|
||||
});
|
||||
}
|
||||
|
||||
// Review warnings (context-dependent)
|
||||
result.warnings.forEach(warning => {
|
||||
if (warning.type === 'best_practice' && isDevWorkflow) {
|
||||
console.log(`ACCEPTABLE: ${warning.message}`);
|
||||
} else {
|
||||
console.log(`SHOULD FIX: ${warning.message}`);
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
### Example 3: Using Auto-Fix
|
||||
|
||||
```javascript
|
||||
// Check what can be auto-fixed
|
||||
const preview = n8n_autofix_workflow({
|
||||
id: "workflow-id",
|
||||
applyFixes: false // Preview mode
|
||||
});
|
||||
|
||||
console.log(`Can auto-fix: ${preview.fixCount} issues`);
|
||||
|
||||
// Apply fixes
|
||||
if (preview.fixCount > 0) {
|
||||
n8n_autofix_workflow({
|
||||
id: "workflow-id",
|
||||
applyFixes: true
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
## When This Skill Activates
|
||||
|
||||
**Trigger phrases**:
|
||||
- "validation error"
|
||||
- "validation failing"
|
||||
- "what does this error mean"
|
||||
- "false positive"
|
||||
- "validation loop"
|
||||
- "operator structure"
|
||||
- "validation profile"
|
||||
|
||||
**Common scenarios**:
|
||||
- Encountering validation errors
|
||||
- Stuck in validation feedback loops
|
||||
- Wondering if warnings need fixing
|
||||
- Choosing the right validation profile
|
||||
- Understanding auto-sanitization
|
||||
|
||||
## Integration with Other Skills
|
||||
|
||||
### Works With:
|
||||
- **n8n MCP Tools Expert** - How to use validation tools correctly
|
||||
- **n8n Expression Syntax** - Fix invalid_expression errors
|
||||
- **n8n Node Configuration** - Understand required fields
|
||||
- **n8n Workflow Patterns** - Validate pattern implementations
|
||||
|
||||
### Complementary:
|
||||
- Use MCP Tools Expert to call validation tools
|
||||
- Use Expression Syntax to fix expression errors
|
||||
- Use Node Configuration to understand dependencies
|
||||
- Use Workflow Patterns to validate structure
|
||||
|
||||
## Testing
|
||||
|
||||
**Evaluations**: 4 test scenarios
|
||||
|
||||
1. **eval-001-missing-required-field.json**
|
||||
- Tests error interpretation
|
||||
- Guides to get_node_essentials
|
||||
- References ERROR_CATALOG.md
|
||||
|
||||
2. **eval-002-false-positive.json**
|
||||
- Tests warning vs error distinction
|
||||
- Explains false positives
|
||||
- References FALSE_POSITIVES.md
|
||||
- Suggests ai-friendly profile
|
||||
|
||||
3. **eval-003-auto-sanitization.json**
|
||||
- Tests auto-sanitization understanding
|
||||
- Explains operator structure fixes
|
||||
- Advises trusting auto-fix
|
||||
|
||||
4. **eval-004-validation-loop.json**
|
||||
- Tests iterative validation process
|
||||
- Explains 2-3 iteration pattern
|
||||
- Provides systematic approach
|
||||
|
||||
## Success Metrics
|
||||
|
||||
**Before this skill**:
|
||||
- Users confused by validation errors
|
||||
- Multiple failed attempts to fix
|
||||
- Frustration with "validation loops"
|
||||
- Fixing issues that auto-fix handles
|
||||
- Fixing all warnings unnecessarily
|
||||
|
||||
**After this skill**:
|
||||
- Systematic error resolution
|
||||
- Understanding of iteration process
|
||||
- Recognition of false positives
|
||||
- Trust in auto-sanitization
|
||||
- Context-aware warning handling
|
||||
- 94% success within 3 iterations
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- **n8n-mcp MCP Server**: Provides validation tools
|
||||
- **n8n Validation API**: validate_node_operation, validate_workflow, n8n_autofix_workflow
|
||||
- **n8n Issues**: #304 (IF metadata), #306 (Switch branches), #338 (credentials)
|
||||
|
||||
## Version History
|
||||
|
||||
- **v1.0** (2025-10-20): Initial implementation
|
||||
- SKILL.md with core concepts
|
||||
- ERROR_CATALOG.md with 9 error types
|
||||
- FALSE_POSITIVES.md with 6 false positive patterns
|
||||
- 4 evaluation scenarios
|
||||
|
||||
## Author
|
||||
|
||||
Conceived by Romuald Członkowski - [www.aiadvisors.pl/en](https://www.aiadvisors.pl/en)
|
||||
|
||||
Part of the n8n-skills meta-skill collection.
|
||||
Reference in New Issue
Block a user