Contributing

Development Philosophy

All contributions to n8n-skills follow five core principles that ensure every skill is accurate, testable, and useful:

Evaluation-First

Write test scenarios before writing any skill content. Evaluations define success criteria upfront.

MCP-Informed

All content is based on real MCP tool responses, not assumptions. Test tools first, then document.

Iterative

Test against evaluations, iterate on SKILL.md, and repeat until every scenario passes at 100%.

Concise

Keep SKILL.md under 500 lines. Split complex content into focused reference files.

Real Examples Only

Never invent examples. Use real templates from n8n-mcp, actual MCP tool responses, and verified node configurations.

Adding a New Skill

Define Scope

Before writing any code, answer these questions:

What problem does this skill solve?
When should it activate?
What MCP tools will it teach?
What are 3 key examples?

Document your answers in skills/[skill-name]/README.md.

Create Evaluations

Create at least 3 evaluation scenarios in evaluations/[skill-name]/ before writing the skill.Cover these cases:

Basic usage
A common mistake
An advanced scenario

See the Testing page for the full evaluation file format and examples.

Test MCP Tools

Run the relevant MCP tools and document real responses in docs/MCP_TESTING_LOG.md:

// Node discovery
search_nodes({query: "keyword"})
get_node({nodeType: "nodes-base.webhook"})
get_node({nodeType: "nodes-base.webhook", mode: "docs"})

// Validation
validate_node({nodeType: "nodes-base.slack", config: {}, mode: "minimal"})
validate_node({nodeType: "nodes-base.slack", config: {...}, profile: "runtime"})

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

Record actual responses, performance timings, gotchas discovered, and real error messages.

Write SKILL.md

Create skills/[skill-name]/SKILL.md with the required frontmatter and recommended structure.Required frontmatter:

---
name: Skill Name
description: When to use this skill. Use when [trigger conditions].
---

Recommended structure:

# 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]

Keep SKILL.md under 500 lines. Move detailed content to reference files.

Add Reference Files

Create focused reference files in the skill directory as needed:

File	Purpose
`COMMON_MISTAKES.md`	Error catalog with fixes
`EXAMPLES.md`	Working, tested examples
`PATTERNS.md`	Common usage patterns
`ADVANCED.md`	Deep-dive topics

Each file should be focused on one topic, under 200 lines, and cross-linked from SKILL.md.

Test Against Evaluations

Run each evaluation scenario manually:

Start Claude Code with the skill loaded
Ask the evaluation query
Check whether all expected behaviors occur
Document results
Iterate on SKILL.md if behaviors are missing
Repeat until 100% of scenarios pass

Document Metadata

Update skills/[skill-name]/README.md with complete metadata:

# 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

Skill File Structure

skills/skill-name/
  SKILL.md              # Main content (under 500 lines)
  COMMON_MISTAKES.md    # Error catalog
  EXAMPLES.md           # Working examples
  README.md             # Metadata
  [optional].md         # Additional references

Evaluations live separately:

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

Evaluation files follow the naming pattern eval-NNN-kebab-case-description.json.

SKILL.md Frontmatter

Every SKILL.md must begin with valid YAML frontmatter containing two required fields:

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

The description field drives automatic activation — it must contain the specific keywords and trigger phrases that match real user queries. Activation examples from the existing 7 skills:

Query	Skill Activated
”How do I write n8n expressions?“	n8n Expression Syntax
”Find me a Slack node”	n8n MCP Tools Expert
”Build a webhook workflow”	n8n Workflow Patterns
”Why is validation failing?“	n8n Validation Expert
”How do I configure the HTTP Request node?“	n8n Node Configuration
”How do I access webhook data in a Code node?“	n8n Code JavaScript
”Can I use pandas in Python Code node?“	n8n Code Python

Cross-Skill Integration

Skills are designed to work together. When writing a new skill, consider how it composes with the existing seven:

n8n Workflow Patterns — identifies the right architectural structure
n8n MCP Tools Expert — finds and validates nodes
n8n Node Configuration — guides operation-aware setup
n8n Expression Syntax — handles data mapping in expression nodes
n8n Code JavaScript / Python — covers custom logic in Code nodes
n8n Validation Expert — validates the final workflow

Add cross-references in SKILL.md using relative links:

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

Code Style Guidelines

Markdown formatting

# H1 - Skill Title
## H2 - Major Sections
### H3 - Subsections

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

Always specify the language on code blocks and include comments. Use real, working examples sourced from MCP tool testing.

JSON (Evaluations)

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

Quality Checklist

Before submitting a skill, verify all of the following:

Content Quality

All examples tested with real MCP tools
No invented or 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 (name and description fields present)
README.md metadata complete
MCP_TESTING_LOG.md updated
Cross-references to related skills added
Examples documented

Code Standards

Markdown properly formatted
Code blocks have language specified
Consistent naming conventions
Proper git commits

Git Workflow

Branch naming

# New skill
git checkout -b skill/skill-name

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

Commit message format

type(scope): brief description

Longer description if needed.

Refs: #issue-number

Commit types: feat (new skill/feature), fix (bug fix), docs (documentation), test (evaluations), refactor (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 request template

Include evaluation results, MCP testing performed, and confirm documentation is updated:

## 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

Common Pitfalls

Never invent examples or data. If you cannot verify it with a real MCP tool call, do not include it in a skill.

If SKILL.md is approaching 500 lines, move detailed content into a focused reference file (e.g., ADVANCED.md) and link to it from SKILL.md.

Avoid:

Exceeding 500 lines in SKILL.md
Writing skills without evaluations
Using generic error messages instead of real ones
Skipping MCP tool testing
Assuming tool behavior without verification

Do:

Test tools and document responses in MCP_TESTING_LOG.md
Use real templates and configurations
Write evaluations first, then the skill
Cross-reference related skills
Verify all code examples actually work

Get Started

Skills

Guides

Development

Development Philosophy

Evaluation-First

MCP-Informed

Iterative

Concise

Real Examples Only

Adding a New Skill

Skill File Structure

SKILL.md Frontmatter

Cross-Skill Integration

Code Style Guidelines

Markdown formatting

JSON (Evaluations)

Quality Checklist

Git Workflow

Branch naming

Commit message format

Pull request template

Common Pitfalls

Get Help

GitHub Issues

GitHub Discussions

Build docs developers (and LLMs) love

Get Started

Skills

Guides

Development

Documentation Index

​Development Philosophy

Evaluation-First

MCP-Informed

Iterative

Concise

Real Examples Only

​Adding a New Skill

​Skill File Structure

​SKILL.md Frontmatter

​Cross-Skill Integration

​Code Style Guidelines

​Markdown formatting

​JSON (Evaluations)

​Quality Checklist

​Git Workflow

​Branch naming

​Commit message format

​Pull request template

​Common Pitfalls

​Get Help

GitHub Issues

GitHub Discussions

Build docs developers (and LLMs) love

Development Philosophy

Adding a New Skill

Skill File Structure

SKILL.md Frontmatter

Cross-Skill Integration

Code Style Guidelines

Markdown formatting

JSON (Evaluations)

Quality Checklist

Git Workflow

Branch naming

Commit message format

Pull request template

Common Pitfalls

Get Help