n8n-skills/docs/DEVELOPMENT.md

# Development Guide

Guidelines for contributing to n8n-skills and developing new skills.

---

## Development Philosophy

### 1. Evaluation-Driven Development (EDD)

Write tests **before** writing skills!

**Process**:
```
1. Create 3+ evaluation scenarios
2. Test baseline (without skill)
3. Write minimal SKILL.md
4. Test against evaluations
5. Iterate until 100% pass
6. Add reference files as needed
```

**Why**: Ensures skills solve real problems and can be tested objectively.

### 2. MCP-Informed Content

All content based on **real MCP tool responses**, not assumptions.

**Process**:
```
1. Test MCP tools thoroughly
2. Document actual responses
3. Use real examples in skills
4. Verify all code snippets work
```

**See**: [MCP_TESTING_LOG.md](MCP_TESTING_LOG.md) for reference data.

### 3. Keep Skills Concise

**Guideline**: SKILL.md should be under 500 lines

**Why**: Longer skills are harder to maintain and slower to load.

**Solution**: Split complex content into reference files:
- SKILL.md: Core concepts and quick reference
- REFERENCE_*.md: Detailed information
- EXAMPLES.md: Working examples

### 4. Real Examples Only

**Never** invent examples. Always use:
- Real templates from n8n-mcp
- Actual MCP tool responses
- Verified node configurations

---

## Repository Structure

```
n8n-skills/
├── skills/                    # Skill implementations
│   ├── n8n-expression-syntax/
│   │   ├── SKILL.md          # Main skill content (< 500 lines)
│   │   ├── COMMON_MISTAKES.md
│   │   ├── EXAMPLES.md
│   │   └── README.md         # Skill metadata
│   └── ...
├── evaluations/               # Test scenarios
│   ├── expression-syntax/
│   │   ├── eval-001-*.json
│   │   └── ...
│   └── ...
├── docs/                      # Documentation
│   ├── INSTALLATION.md
│   ├── USAGE.md
│   ├── DEVELOPMENT.md (this file)
│   └── MCP_TESTING_LOG.md    # Real MCP responses
├── README.md                  # Project overview
├── LICENSE                    # MIT License
└── .gitignore
```

---

## Creating a New Skill

### Step 1: Define Scope

**Questions to answer**:
- What problem does this skill solve?
- When should it activate?
- What MCP tools will it teach?
- What are 3 key examples?

**Document in**: `skills/[skill-name]/README.md`

### Step 2: Create Evaluations

**Create**: `evaluations/[skill-name]/eval-001-description.json`

**Format**:
```json
{
  "id": "skill-001",
  "skills": ["skill-name"],
  "query": "User question or scenario",
  "expected_behavior": [
    "Skill should identify X",
    "Skill should provide Y guidance",
    "Skill should reference Z content"
  ],
  "baseline_without_skill": {
    "likely_response": "Generic answer",
    "expected_quality": "Low"
  },
  "with_skill_expected": {
    "response_quality": "High",
    "uses_skill_content": true,
    "provides_correct_guidance": true
  }
}
```

**Create at least 3 evaluations** covering:
1. Basic usage
2. Common mistake
3. Advanced scenario

### Step 3: Test MCP Tools

**Document tool responses** in `docs/MCP_TESTING_LOG.md`:

```markdown
## [Your Skill Name] - MCP Testing

### Tool: tool_name

**Test**:
```javascript
tool_name({param: "value"})
```

**Response**:
```json
{actual response}
```

**Key Insights**:
- Finding 1
- Finding 2
```

### Step 4: Write SKILL.md

**Required frontmatter**:
```markdown
---
name: Skill Name
description: When to use this skill. Use when [trigger conditions].
---
```

**Recommended structure**:
```markdown
# Skill Name

## Quick Reference
[Table or list of most common patterns]

## Core Concepts
[Essential knowledge]

## Common Patterns
[Real examples with code]

## Common Mistakes
[Errors and fixes]

## Advanced Topics
[Link to reference files]

## Related Skills
[Cross-references]
```

**Guidelines**:
- Under 500 lines for SKILL.md
- Use real examples from MCP testing
- Include quick fixes table
- Link to reference files
- Cross-reference other skills

### Step 5: Add Reference Files

Create as needed:
- `COMMON_MISTAKES.md` - Error catalog
- `EXAMPLES.md` - Working examples
- `PATTERNS.md` - Common patterns
- `ADVANCED.md` - Deep dive topics

**Each file**:
- Should be focused on one topic
- Under 200 lines
- Real examples only
- Cross-linked from SKILL.md

### Step 6: Test Against Evaluations

**Process**:
1. Run evaluation scenarios with Claude
2. Check if expected behaviors occur
3. Document results
4. Iterate SKILL.md if needed
5. Repeat until 100% pass

**Success criteria**:
- All evaluations pass
- Skill activates correctly
- Content is accurate
- Examples work

### Step 7: Document Metadata

**Create**: `skills/[skill-name]/README.md`

```markdown
# Skill Name

**Purpose**: One-sentence description

**Activates on**: keyword1, keyword2, keyword3

**File Count**: X files, ~Y lines

**Dependencies**:
- n8n-mcp tools: tool1, tool2
- Other skills: skill1, skill2

**Coverage**:
- Topic 1
- Topic 2
- Topic 3

**Evaluations**: X scenarios (X% pass rate)

**Last Updated**: YYYY-MM-DD
```

---

## Evaluation Guidelines

### Good Evaluations

**Characteristics**:
- Specific, measurable expected behavior
- Based on real user queries
- Cover common and edge cases
- Include baseline comparison

**Example**:
```json
{
  "id": "expr-001",
  "query": "Why is {{$json.email}} undefined in my webhook workflow?",
  "expected_behavior": [
    "Identifies webhook data structure issue",
    "Explains data is under $json.body",
    "Provides corrected expression: {{$json.body.email}}",
    "References webhook structure documentation"
  ]
}
```

### Bad Evaluations

**Avoid**:
- Vague expected behaviors
- Unrealistic scenarios
- No baseline comparison
- Too simple or too complex

---

## Testing

### Manual Testing

```
1. Start Claude Code
2. Load skill
3. Ask evaluation query
4. Verify expected behaviors
5. Document results
```

### Automated Testing

*Coming soon: Evaluation framework*

---

## MCP Tool Testing Guidelines

### Before Writing Skills

**Test these tools**:
```javascript
// Node discovery
search_nodes({query: "keyword"})
list_nodes({category: "trigger"})
get_node_essentials({nodeType: "nodes-base.webhook"})

// Validation
validate_node_minimal({nodeType: "nodes-base.slack", config: {}})
validate_node_operation({nodeType: "nodes-base.slack", config: {...}, profile: "runtime"})

// Templates
search_templates({query: "webhook"})
get_template({templateId: 2947, mode: "structure"})

// Workflow management (if API available)
n8n_create_workflow({...})
n8n_update_partial_workflow({...})
n8n_validate_workflow({...})
```

### Document Findings

**In MCP_TESTING_LOG.md**:
- Actual responses
- Performance (timing)
- Gotchas discovered
- Format differences
- Error messages

### Use Real Data

**Extract from tools**:
- Node structures
- Template examples
- Validation errors
- Property dependencies

**Use in skills**:
- Real node configurations
- Actual error messages
- Working template IDs
- Proven patterns

---

## Code Standards

### Markdown

**Formatting**:
```markdown
# H1 - Skill Title
## H2 - Major Sections
### H3 - Subsections

**Bold** for emphasis
`code` for inline code
\`\`\`language for code blocks
```

**Code blocks**:
```javascript
// Always specify language
// Include comments
// Use real, working examples
```

### JSON (Evaluations)

**Format**:
```json
{
  "id": "kebab-case-id",
  "skills": ["exact-skill-name"],
  "query": "Natural user question",
  "expected_behavior": [
    "Specific measurable behavior"
  ]
}
```

---

## Git Workflow

### Branching

```bash
# Feature branch
git checkout -b skill/skill-name

# Bug fix
git checkout -b fix/issue-description
```

### Commits

**Format**:
```
type(scope): brief description

Longer description if needed.

Refs: #issue-number
```

**Types**:
- `feat`: New skill or feature
- `fix`: Bug fix
- `docs`: Documentation
- `test`: Evaluations
- `refactor`: Code improvement

**Examples**:
```
feat(expression-syntax): add webhook data structure guide
fix(mcp-tools): correct nodeType format examples
docs(usage): add cross-skill composition examples
test(validation): add auto-sanitization evaluation
```

### Pull Requests

**Include**:
- Description of changes
- Evaluation results (if new skill)
- MCP testing performed
- Documentation updated

**Template**:
```markdown
## Description
[What changed and why]

## Evaluations
- [ ] eval-001: PASS
- [ ] eval-002: PASS
- [ ] eval-003: PASS

## MCP Testing
- Tested tools: [list]
- New findings: [list]

## Documentation
- [ ] SKILL.md updated
- [ ] README.md updated
- [ ] MCP_TESTING_LOG.md updated

## Checklist
- [ ] SKILL.md under 500 lines
- [ ] Real examples only
- [ ] All evaluations pass
- [ ] Cross-references added
```

---

## File Naming Conventions

### Skills

```
skills/skill-name/
  SKILL.md              # Main content
  COMMON_MISTAKES.md    # Error catalog
  EXAMPLES.md           # Working examples
  README.md             # Metadata
  [optional files].md   # Additional references
```

### Evaluations

```
evaluations/skill-name/
  eval-001-short-description.json
  eval-002-short-description.json
  eval-003-short-description.json
```

**Naming**: `eval-NNN-kebab-case-description.json`

---

## Documentation Standards

### SKILL.md Frontmatter

**Required**:
```yaml
---
name: Exact Skill Name
description: When this skill activates. Use when [triggers]. Include specific keywords.
---
```

### Cross-References

**Link to**:
- Related skills
- Reference files
- MCP tool documentation
- Real templates

**Format**:
```markdown
See [n8n MCP Tools Expert](../n8n-mcp-tools-expert/SKILL.md)
See [COMMON_MISTAKES.md](COMMON_MISTAKES.md)
See template #2947 for example
```

---

## Quality Checklist

Before submitting a skill:

### Content Quality
- [ ] All examples tested with real MCP tools
- [ ] No invented/fake examples
- [ ] SKILL.md under 500 lines
- [ ] Clear, actionable guidance
- [ ] Real error messages included

### Testing
- [ ] 3+ evaluations created
- [ ] All evaluations pass
- [ ] Baseline comparison documented
- [ ] Cross-skill integration tested

### Documentation
- [ ] Frontmatter correct
- [ ] README.md metadata complete
- [ ] MCP_TESTING_LOG.md updated
- [ ] Cross-references added
- [ ] Examples documented

### Code Standards
- [ ] Markdown properly formatted
- [ ] Code blocks have language specified
- [ ] Consistent naming conventions
- [ ] Proper git commits

---

## Common Pitfalls

### ❌ Don't

- Invent examples or data
- Exceed 500 lines in SKILL.md
- Skip MCP tool testing
- Write skills without evaluations
- Use generic error messages
- Assume tool behavior

### ✅ Do

- Test tools and document responses
- Use real templates and configurations
- Write evaluations first
- Keep skills concise
- Cross-reference related skills
- Verify all code works

---

## Release Process

### Version Numbering

**Format**: `MAJOR.MINOR.PATCH`

- **MAJOR**: New skills added
- **MINOR**: Skill improvements
- **PATCH**: Bug fixes, typos

### Changelog

Update `CHANGELOG.md`:
```markdown
## [1.1.0] - 2025-10-20

### Added
- New skill: n8n Expression Syntax
- 3 evaluations for expression syntax

### Changed
- Improved MCP Tools Expert validation guidance

### Fixed
- Corrected nodeType format in examples
```

---

## Support

### Getting Help

- **Issues**: https://github.com/czlonkowski/n8n-skills/issues
- **Discussions**: https://github.com/czlonkowski/n8n-skills/discussions
- **n8n-mcp**: https://github.com/romualdczlonkowski/n8n-mcp

### Reporting Bugs

**Include**:
- Skill name and version
- Evaluation that fails
- Expected vs actual behavior
- MCP tool versions

---

## License

All contributions must be compatible with MIT License.

---

**Happy developing!** 🚀

---

Conceived by Romuald Członkowski - [www.aiadvisors.pl/en](https://www.aiadvisors.pl/en)