From cafdb175d9b2c2f7c6a53b66972bf68f844b5bce Mon Sep 17 00:00:00 2001 From: czlonkowski <56956555+czlonkowski@users.noreply.github.com> Date: Mon, 20 Oct 2025 09:43:09 +0200 Subject: [PATCH] Add MCP configuration and project guidelines MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add .gitignore to exclude docs/ and .mcp.json - Add .mcp.json.example as template for n8n-mcp server configuration - Add CLAUDE.md with comprehensive project instructions for AI assistants πŸ€– Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Conceived by Romuald CzΕ‚onkowski - https://www.aiadvisors.pl/en --- .gitignore | 2 + .mcp.json.example | 15 ++++ CLAUDE.md | 205 ++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 222 insertions(+) create mode 100644 .gitignore create mode 100644 .mcp.json.example create mode 100644 CLAUDE.md diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..7ee1eb8 --- /dev/null +++ b/.gitignore @@ -0,0 +1,2 @@ +docs/ +.mcp.json diff --git a/.mcp.json.example b/.mcp.json.example new file mode 100644 index 0000000..323f742 --- /dev/null +++ b/.mcp.json.example @@ -0,0 +1,15 @@ +{ + "mcpServers": { + "n8n-mcp": { + "command": "npx", + "args": ["n8n-mcp"], + "env": { + "MCP_MODE": "stdio", + "LOG_LEVEL": "error", + "DISABLE_CONSOLE_OUTPUT": "true", + "N8N_API_URL": "https://your-n8n-instance.com", + "N8N_API_KEY": "your-api-key-here" + } + } + } +} diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..a2db069 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,205 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Project Overview + +This is the **n8n-skills** repository - a collection of Claude Code skills designed to teach AI assistants how to build flawless n8n workflows using the n8n-mcp MCP server. + +**Repository**: https://github.com/czlonkowski/n8n-skills + +**Purpose**: Create 5 complementary meta-skills that provide expert guidance on using n8n-mcp MCP tools effectively for building n8n workflows. + +**Architecture**: +- **n8n-mcp MCP Server**: Provides data access (525 nodes, validation, templates) +- **Claude Skills**: Provides expert guidance on HOW to use MCP tools +- **Together**: Expert workflow builder with progressive disclosure + +## Repository Structure + +``` +n8n-skills/ +β”œβ”€β”€ README.md # Project overview +β”œβ”€β”€ LICENSE # MIT License +β”œβ”€β”€ skills/ # (To be created) Individual skill implementations +β”‚ β”œβ”€β”€ n8n-expression-syntax/ +β”‚ β”œβ”€β”€ n8n-mcp-tools-expert/ +β”‚ β”œβ”€β”€ n8n-workflow-patterns/ +β”‚ β”œβ”€β”€ n8n-validation-expert/ +β”‚ └── n8n-node-configuration/ +β”œβ”€β”€ evaluations/ # (To be created) Test scenarios for each skill +β”œβ”€β”€ docs/ # Documentation +β”‚ └── SKILLS_IMPLEMENTATION_GUIDE.md # Complete implementation guide +└── .gitignore # Git ignore (excludes docs/) +``` + +## Implementation Timeline + +- **Week 1**: n8n Expression Syntax (PoC - 4 files, ~350 lines) +- **Week 2**: n8n MCP Tools Expert + n8n Workflow Patterns +- **Week 3**: n8n Validation Expert + n8n Node Configuration +- **Week 4**: Testing, refinement, documentation +- **Week 5-6**: Distribution, plugin packaging + +## Five Skills to Implement + +### 1. n8n Expression Syntax +**Priority**: Foundation (Week 1) +- Teaches correct n8n expression syntax ({{}} patterns) +- Covers common mistakes and fixes +- Files: SKILL.md, COMMON_MISTAKES.md, EXAMPLES.md + +### 2. n8n MCP Tools Expert +**Priority**: Highest (fixes 20% failure rate) +- Teaches how to use n8n-mcp MCP tools effectively +- Covers node discovery, validation, workflow management +- Files: SKILL.md, SEARCH_GUIDE.md, VALIDATION_GUIDE.md, WORKFLOW_GUIDE.md + +### 3. n8n Workflow Patterns +**Priority**: High (addresses 813 webhook searches) +- Teaches proven workflow architectural patterns +- 5 patterns from 31,917 real workflows +- Files: SKILL.md + 5 pattern files (webhook, http, database, ai, scheduled) + +### 4. n8n Validation Expert +**Priority**: Medium +- Interprets validation errors and guides fixing +- Handles false positives and validation loops +- Files: SKILL.md, ERROR_CATALOG.md, FALSE_POSITIVES.md + +### 5. n8n Node Configuration +**Priority**: Medium +- Operation-aware node configuration guidance +- Property dependencies and common patterns +- Files: SKILL.md, DEPENDENCIES.md, OPERATION_PATTERNS.md + +## Data-Driven Design + +These skills are based on telemetry analysis of: +- 447,557 real MCP tool usage events +- 31,917 workflows created +- 19,113 validation errors +- 15,107 validation feedback loops + +## Skill Structure + +Each skill follows this format: + +```markdown +--- +name: Skill Name +description: When to use this skill. Use when [trigger conditions]. +--- + +# Skill Name + +## [Content organized in sections] +``` + +## Development Approach + +**Evaluation-Driven Development**: +1. Create 3+ evaluations FIRST for each skill +2. Establish baseline (test without skill) +3. Write minimal SKILL.md (under 500 lines) +4. Test against evaluations +5. Iterate until 100% pass +6. Add reference files as needed + +## Key Implementation Guidelines + +### File Organization +- Keep SKILL.md files under 500 lines +- Split complex content into reference files +- Use markdown with clear sections +- Link between related files + +### Skill Activation +Skills activate automatically when queries match their description triggers: +- "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 + +### Cross-Skill Integration +Skills are designed to work together: +- Use n8n Workflow Patterns to identify structure +- Use n8n MCP Tools Expert to find nodes +- Use n8n Node Configuration for setup +- Use n8n Expression Syntax for data mapping +- Use n8n Validation Expert to validate + +## Important Patterns from Telemetry + +### Most Common Tool Usage Pattern +``` +search_nodes β†’ get_node_essentials (9,835 occurrences, 18s avg) +``` + +### Most Common Validation Pattern +``` +n8n_update_partial_workflow β†’ n8n_validate_workflow (7,841 occurrences) +Avg 23s thinking, 58s fixing +``` + +### Most Used Tool +``` +n8n_update_partial_workflow (38,287 uses, 99.0% success) +Avg 56 seconds between edits +``` + +## Working with This Repository + +### When Adding New Skills +1. Create skill directory under `skills/` +2. Follow the structure in `docs/SKILLS_IMPLEMENTATION_GUIDE.md` +3. Write SKILL.md with frontmatter +4. Add reference files as needed +5. Create 3+ evaluations in `evaluations/` +6. Test thoroughly before committing + +### When Creating Evaluations +Place in `evaluations/[skill-name]/eval-NNN-description.json` + +Format: +```json +{ + "id": "skill-NNN", + "skills": ["skill-name"], + "query": "User question or scenario", + "expected_behavior": [ + "List of expected behaviors", + "What skill should do", + "What content it should reference" + ] +} +``` + +### Git Workflow +- Work on feature branches +- Commit frequently with clear messages +- Test skills before pushing +- Keep main branch stable + +## Requirements + +- n8n-mcp MCP server installed and configured +- Claude Code, Claude.ai, or Claude API access +- Understanding of n8n workflow concepts + +## Distribution + +Final distribution will be: +1. **GitHub Repository**: Full source code and documentation +2. **Claude Code Plugin**: Packaged skills with plugin.json +3. **Individual Skill Uploads**: For Claude.ai users + +## Credits + +Conceived by Romuald CzΕ‚onkowski - [www.aiadvisors.pl/en](https://www.aiadvisors.pl/en) + +Part of the n8n-mcp project. + +## License + +MIT License - See LICENSE file for details. +- Add to every commit and PR: Concieved by Romuald CzΕ‚onkowski - and then link to www.aiadvisors.pl/en. Don't add it in conversations \ No newline at end of file