Browse All Skills
n8n MCP Tools Expert
# n8n MCP Tools Expert Master guide for using n8n-mcp MCP server tools to build workflows. --- ## Tool Categories n8n-mcp provides **40+ tools** organized into categories: 1. **Node Discovery** → [SEARCH_GUIDE.md](SEARCH_GUIDE.md) 2. **Configuration Validation** → [VALIDATION_GUIDE.md](VALIDATION_GUIDE.md) 3. **Workflow Management** → [WORKFLOW_GUIDE.md](WORKFLOW_GUIDE.md) 4. **Template Library** - Search and access 2,653 real workflows 5. **Documentation** - Get tool and node documentation --- ## Quick Reference ### Most Used Tools (by success rate) | Tool | Use When | Success Rate | Speed | |------|----------|--------------|-------| | `search_nodes` | Finding nodes by keyword | 99.9% | <20ms | | `get_node_essentials` | Understanding node operations | 91.7% | <10ms | | `validate_node_operation` | Checking configurations | Varies | <100ms | | `n8n_create_workflow` | Creating workflows | 96.8% | 100-500ms | | `n8n_update_partial_workflow` | Editing workflows (MOST USED!) | 99.0% | 50-200ms | | `validate_workflow` | Checking complete workflow | 95.5% | 100-500ms | --- ## Tool Selection Guide ### Finding the Right Node **Workflow**: ``` 1. search_nodes({query: "keyword"}) 2. get_node_essentials({nodeType: "nodes-base.name"}) 3. [Optional] get_node_documentation({nodeType: "nodes-base.name"}) ``` **Example**: ```javascript // Step 1: Search search_nodes({query: "slack"}) // Returns: nodes-base.slack // Step 2: Get details (18s avg between steps) get_node_essentials({nodeType: "nodes-base.slack"}) // Returns: operations, properties, examples ``` **Common pattern**: search → essentials (18s average) ### Validating Configuration **Workflow**: ``` 1. validate_node_minimal({nodeType, config: {}}) - Check required fields 2. validate_node_operation({nodeType, config, profile: "runtime"}) - Full validation 3. [Repeat] Fix errors, validate again ``` **Common pattern**: validate → fix → validate (23s thinking, 58s fixing per cycle) ### Managing Workflows **Workflow**: ``` 1. n8n_create_workflow({name, nodes, connections}) 2. n8n_validate_workflow({id}) 3. n8n_update_partial_workflow({id, operations: [...]}) 4. n8n_validate_workflow({id}) again ``` **Common pattern**: iterative updates (56s average between edits) --- ## Critical: nodeType Formats **Two different formats** for different tools! ### Format 1: Search/Validate Tools ```javascript // Use SHORT prefix "nodes-base.slack" "nodes-base.httpRequest" "nodes-base.webhook" "nodes-langchain.agent" ``` **Tools that use this**: - search_nodes (returns this format) - get_node_essentials - get_node_info - validate_node_minimal - validate_node_operation - get_property_dependencies ### Format 2: Workflow Tools ```javascript // Use FULL prefix "n8n-nodes-base.slack" "n8n-nodes-base.httpRequest" "n8n-nodes-base.webhook" "@n8n/n8n-nodes-langchain.agent" ``` **Tools that use this**: - n8n_create_workflow - n8n_update_partial_workflow - list_node_templates ### Conversion ```javascript // search_nodes returns BOTH formats { "nodeType": "nodes-base.slack", // For search/validate tools "workflowNodeType": "n8n-nodes-base.slack" // For workflow tools } ``` --- ## Common Mistakes ### ❌ Mistake 1: Wrong nodeType Format **Problem**: "Node not found" error ```javascript ❌ get_node_essentials({nodeType: "slack"}) // Missing prefix ❌ get_node_essentials({nodeType: "n8n-nodes-base.slack"}) // Wrong prefix ✅ get_node_essentials({nodeType: "nodes-base.slack"}) // Correct! ``` ### ❌ Mistake 2: Using get_node_info Instead of get_node_essentials **Problem**: 20% failure rate, slow response, huge payload ```javascript ❌ get_node_info({nodeType: "nodes-base.slack"}) // Returns: 100KB+ data, 20% chance of failure ✅ get_node_essentials({nodeType: "nodes-base.slack"}) // Returns: 5KB focused data, 91.7% success, <10ms ``` **When to use get_node_info**: - Debugging complex configuration issues - Need complete property schema - Exploring advanced features **Better alternatives**: 1. get_node_essentials - for operations list 2. get_node_documentation - for readable docs 3. search_node_properties - for specific property ### ❌ Mistake 3: Not Using Validation Profiles **Problem**: Too many false positives OR missing real errors **Profiles**: - `minimal` - Only required fields (fast, permissive) - `runtime` - Values + types (recommended for pre-deployment) - `ai-friendly` - Reduce false positives (for AI configuration) - `strict` - Maximum validation (for production) ```javascript ❌ validate_node_operation({nodeType, config}) // Uses default ✅ validate_node_operation({nodeType, config, profile: "runtime"}) // Explicit ``` ### ❌ Mistake 4: Ignoring Auto-Sanitization **What happens**: ALL nodes sanitized on ANY workflow update **Auto-fixes**: - Binary operators (equals, contains) → removes singleValue - Unary operators (isEmpty, isNotEmpty) → adds singleValue: true - IF/Switch nodes → adds missing metadata **Cannot fix**: - Broken connections - Branch count mismatches - Paradoxical corrupt states ```javascript // After ANY update, auto-sanitization runs on ALL nodes n8n_update_partial_workflow({id, operations: [...]}) // → Automatically fixes operator structures ``` ### ❌ Mistake 5: Not Using Smart Parameters **Problem**: Complex sourceIndex calculations for multi-output nodes **Old way** (manual): ```javascript // IF node connection { type: "addConnection", source: "IF", target: "Handler", sourceIndex: 0 // Which output? Hard to remember! } ``` **New way** (smart parameters): ```javascript // IF node - semantic branch names { type: "addConnection", source: "IF", target: "True Handler", branch: "true" // Clear and readable! } { type: "addConnection", source: "IF", target: "False Handler", branch: "false" } // Switch node - semantic case numbers { type: "addConnection", source: "Switch", target: "Handler A", case: 0 } ``` --- ## Tool Usage Patterns ### Pattern 1: Node Discovery (Most Common) **Common workflow**: 18s average between steps ```javascript // Step 1: Search (fast!) const results = await search_nodes({ query: "slack", mode: "OR", // Default: any word matches limit: 20 }); // → Returns: nodes-base.slack, nodes-base.slackTrigger // Step 2: Get details (~18s later, user reviewing results) const details = await get_node_essentials({ nodeType: "nodes-base.slack", includeExamples: true // Get real template configs }); // → Returns: operations, properties, metadata ``` ### Pattern 2: Validation Loop **Typical cycle**: 23s thinking, 58s fixing ```javascript // Step 1: Validate const result = await validate_node_operation({ nodeType: "nodes-base.slack", config: { resource: "channel", operation: "create" }, profile: "runtime" }); // Step 2: Check errors (~23s thinking) if (!result.valid) { console.log(result.errors); // "Missing required field: name" } // Step 3: Fix config (~58s fixing) config.name = "general"; // Step 4: Validate again await validate_node_operation({...}); // Repeat until clean ``` ### Pattern 3: Workflow Editing **Most used update tool**: 99.0% success rate, 56s average between edits ```javascript // Iterative workflow building (NOT one-shot!) // Edit 1 await n8n_update_partial_workflow({ id: "workflow-id", operations: [{type: "addNode", node: {...}}] }); // ~56s later... // Edit 2 await n8n_update_partial_workflow({ id: "workflow-id", operations: [{type: "addConnection", source: "...", target: "..."}] }); // ~56s later... // Edit 3 (validation) await n8n_validate_workflow({id: "workflow-id"}); ``` --- ## Detailed Guides ### Node Discovery Tools See [SEARCH_GUIDE.md](SEARCH_GUIDE.md) for: - search_nodes (99.9% success) - get_node_essentials vs get_node_info - list_nodes by category - search_node_properties for specific fields ### Validation Tools See [VALIDATION_GUIDE.md](VALIDATION_GUIDE.md) for: - Validation profiles explained - validate_node_minimal vs validate_node_operation - validate_workflow complete structure - Auto-sanitization system - Handling validation errors ### Workflow Management See [WORKFLOW_GUIDE.md](WORKFLOW_GUIDE.md) for: - n8n_create_workflow - n8n_update_partial_workflow (15 operation types!) - Smart parameters (branch, case) - AI connection types (8 types) - cleanStaleConnections recovery --- ## Template Usage ### Search Templates ```javascript // Search by keyword search_templates({ query: "webhook slack", limit: 20 }); // → Returns: 1,085 templates with metadata // Get template details get_template({ templateId: 2947, // Weather to Slack mode: "structure" // or "full" for complete JSON }); ``` ### Template Metadata Templates include: - Complexity (simple, medium, complex) - Setup time estimate - Required services - Categories and use cases - View counts (popularity) --- ## Self-Help Tools ### Get Tool Documentation ```javascript // List all tools tools_documentation() // Specific tool details tools_documentation({ topic: "search_nodes", depth: "full" }) ``` ### Health Check ```javascript // Verify MCP server connectivity n8n_health_check() // → Returns: status, features, API availability, version ``` ### Database Statistics ```javascript get_database_statistics() // → Returns: 537 nodes, 270 AI tools, 2,653 templates ``` --- ## Tool Availability **Always Available** (no n8n API needed): - search_nodes, list_nodes, get_node_essentials ✅ - validate_node_minimal, validate_node_operation ✅ - validate_workflow, get_property_dependencies ✅ - search_templates, get_template, list_tasks ✅ - tools_documentation, get_database_statistics ✅ **Requires n8n API** (N8N_API_URL + N8N_API_KEY): - n8n_create_workflow ⚠️ - n8n_update_partial_workflow ⚠️ - n8n_validate_workflow (by ID) ⚠️ - n8n_list_workflows, n8n_get_workflow ⚠️ - n8n_trigger_webhook_workflow ⚠️ If API tools unavailable, use templates and validation-only workflows. --- ## Performance Characteristics | Tool | Response Time | Payload Size | Reliability | |------|---------------|--------------|-------------| | search_nodes | <20ms | Small | 99.9% | | list_nodes | <20ms | Small | 99.6% | | get_node_essentials | <10ms | ~5KB | 91.7% | | get_node_info | Varies | 100KB+ | 80% ⚠️ | | validate_node_minimal | <100ms | Small | 97.4% | | validate_node_operation | <100ms | Medium | Varies | | validate_workflow | 100-500ms | Medium | 95.5% | | n8n_create_workflow | 100-500ms | Medium | 96.8% | | n8n_update_partial_workflow | 50-200ms | Small | 99.0% | --- ## Best Practices ### ✅ Do - Use get_node_essentials over get_node_info (91.7% vs 80%) - Specify validation profile explicitly - Use smart parameters (branch, case) for clarity - Follow search → essentials → validate workflow - Iterate workflows (avg 56s between edits) - Validate after every significant change - Use includeExamples: true for real configs ### ❌ Don't - Use get_node_info unless necessary (20% failure rate!) - Forget nodeType prefix (nodes-base.*) - Skip validation profiles (use "runtime") - Try to build workflows in one shot (iterate!) - Ignore auto-sanitization behavior - Use full prefix (n8n-nodes-base.*) with search tools --- ## Summary **Most Important**: 1. Use **get_node_essentials**, not get_node_info (5KB vs 100KB, 91.7% vs 80%) 2. nodeType formats differ: `nodes-base.*` (search) vs `n8n-nodes-base.*` (workflows) 3. Specify **validation profiles** (runtime recommended) 4. Use **smart parameters** (branch="true", case=0) 5. **Auto-sanitization** runs on ALL nodes during updates 6. Workflows are built **iteratively** (56s avg between edits) **Common Workflow**: 1. search_nodes → find node 2. get_node_essentials → understand config 3. validate_node_operation → check config 4. n8n_create_workflow → build 5. n8n_validate_workflow → verify 6. n8n_update_partial_workflow → iterate For details, see: - [SEARCH_GUIDE.md](SEARCH_GUIDE.md) - Node discovery - [VALIDATION_GUIDE.md](VALIDATION_GUIDE.md) - Configuration validation - [WORKFLOW_GUIDE.md](WORKFLOW_GUIDE.md) - Workflow management --- **Related Skills**: - n8n Expression Syntax - Write expressions in workflow fields - n8n Workflow Patterns - Architectural patterns from templates - n8n Validation Expert - Interpret validation errors - n8n Node Configuration - Operation-specific requirements
n8n Validation Expert
# n8n Validation Expert Expert guide for interpreting and fixing n8n validation errors. --- ## Validation Philosophy **Validate early, validate often** Validation is typically iterative: - Expect validation feedback loops - Usually 2-3 validate → fix cycles - Average: 23s thinking about errors, 58s fixing them **Key insight**: Validation is an iterative process, not one-shot! --- ## Error Severity Levels ### 1. Errors (Must Fix) **Blocks workflow execution** - Must be resolved before activation **Types**: - `missing_required` - Required field not provided - `invalid_value` - Value doesn't match allowed options - `type_mismatch` - Wrong data type (string instead of number) - `invalid_reference` - Referenced node doesn't exist - `invalid_expression` - Expression syntax error **Example**: ```json { "type": "missing_required", "property": "channel", "message": "Channel name is required", "fix": "Provide a channel name (lowercase, no spaces, 1-80 characters)" } ``` ### 2. Warnings (Should Fix) **Doesn't block execution** - Workflow can be activated but may have issues **Types**: - `best_practice` - Recommended but not required - `deprecated` - Using old API/feature - `performance` - Potential performance issue **Example**: ```json { "type": "best_practice", "property": "errorHandling", "message": "Slack API can have rate limits", "suggestion": "Add onError: 'continueRegularOutput' with retryOnFail" } ``` ### 3. Suggestions (Optional) **Nice to have** - Improvements that could enhance workflow **Types**: - `optimization` - Could be more efficient - `alternative` - Better way to achieve same result --- ## The Validation Loop ### Pattern from Telemetry **7,841 occurrences** of this pattern: ``` 1. Configure node ↓ 2. validate_node_operation (23 seconds thinking about errors) ↓ 3. Read error messages carefully ↓ 4. Fix errors ↓ 5. validate_node_operation again (58 seconds fixing) ↓ 6. Repeat until valid (usually 2-3 iterations) ``` ### Example ```javascript // Iteration 1 let config = { resource: "channel", operation: "create" }; const result1 = validate_node_operation({ nodeType: "nodes-base.slack", config, profile: "runtime" }); // → Error: Missing "name" // ⏱️ 23 seconds thinking... // Iteration 2 config.name = "general"; const result2 = validate_node_operation({ nodeType: "nodes-base.slack", config, profile: "runtime" }); // → Error: Missing "text" // ⏱️ 58 seconds fixing... // Iteration 3 config.text = "Hello!"; const result3 = validate_node_operation({ nodeType: "nodes-base.slack", config, profile: "runtime" }); // → Valid! ✅ ``` **This is normal!** Don't be discouraged by multiple iterations. --- ## Validation Profiles Choose the right profile for your stage: ### minimal **Use when**: Quick checks during editing **Validates**: - Only required fields - Basic structure **Pros**: Fastest, most permissive **Cons**: May miss issues ### runtime (RECOMMENDED) **Use when**: Pre-deployment validation **Validates**: - Required fields - Value types - Allowed values - Basic dependencies **Pros**: Balanced, catches real errors **Cons**: Some edge cases missed **This is the recommended profile for most use cases** ### ai-friendly **Use when**: AI-generated configurations **Validates**: - Same as runtime - Reduces false positives - More tolerant of minor issues **Pros**: Less noisy for AI workflows **Cons**: May allow some questionable configs ### strict **Use when**: Production deployment, critical workflows **Validates**: - Everything - Best practices - Performance concerns - Security issues **Pros**: Maximum safety **Cons**: Many warnings, some false positives --- ## Common Error Types ### 1. missing_required **What it means**: A required field is not provided **How to fix**: 1. Use `get_node_essentials` to see required fields 2. Add the missing field to your configuration 3. Provide an appropriate value **Example**: ```javascript // Error { "type": "missing_required", "property": "channel", "message": "Channel name is required" } // Fix config.channel = "#general"; ``` ### 2. invalid_value **What it means**: Value doesn't match allowed options **How to fix**: 1. Check error message for allowed values 2. Use `get_node_essentials` to see options 3. Update to a valid value **Example**: ```javascript // Error { "type": "invalid_value", "property": "operation", "message": "Operation must be one of: post, update, delete", "current": "send" } // Fix config.operation = "post"; // Use valid operation ``` ### 3. type_mismatch **What it means**: Wrong data type for field **How to fix**: 1. Check expected type in error message 2. Convert value to correct type **Example**: ```javascript // Error { "type": "type_mismatch", "property": "limit", "message": "Expected number, got string", "current": "100" } // Fix config.limit = 100; // Number, not string ``` ### 4. invalid_expression **What it means**: Expression syntax error **How to fix**: 1. Use n8n Expression Syntax skill 2. Check for missing `{{}}` or typos 3. Verify node/field references **Example**: ```javascript // Error { "type": "invalid_expression", "property": "text", "message": "Invalid expression: $json.name", "current": "$json.name" } // Fix config.text = "={{$json.name}}"; // Add {{}} ``` ### 5. invalid_reference **What it means**: Referenced node doesn't exist **How to fix**: 1. Check node name spelling 2. Verify node exists in workflow 3. Update reference to correct name **Example**: ```javascript // Error { "type": "invalid_reference", "property": "expression", "message": "Node 'HTTP Requets' does not exist", "current": "={{$node['HTTP Requets'].json.data}}" } // Fix - correct typo config.expression = "={{$node['HTTP Request'].json.data}}"; ``` --- ## Auto-Sanitization System ### What It Does **Automatically fixes common operator structure issues** on ANY workflow update **Runs when**: - `n8n_create_workflow` - `n8n_update_partial_workflow` - Any workflow save operation ### What It Fixes #### 1. Binary Operators (Two Values) **Operators**: equals, notEquals, contains, notContains, greaterThan, lessThan, startsWith, endsWith **Fix**: Removes `singleValue` property (binary operators compare two values) **Before**: ```javascript { "type": "boolean", "operation": "equals", "singleValue": true // ❌ Wrong! } ``` **After** (automatic): ```javascript { "type": "boolean", "operation": "equals" // singleValue removed ✅ } ``` #### 2. Unary Operators (One Value) **Operators**: isEmpty, isNotEmpty, true, false **Fix**: Adds `singleValue: true` (unary operators check single value) **Before**: ```javascript { "type": "boolean", "operation": "isEmpty" // Missing singleValue ❌ } ``` **After** (automatic): ```javascript { "type": "boolean", "operation": "isEmpty", "singleValue": true // ✅ Added } ``` #### 3. IF/Switch Metadata **Fix**: Adds complete `conditions.options` metadata for IF v2.2+ and Switch v3.2+ ### What It CANNOT Fix #### 1. Broken Connections References to non-existent nodes **Solution**: Use `cleanStaleConnections` operation in `n8n_update_partial_workflow` #### 2. Branch Count Mismatches 3 Switch rules but only 2 output connections **Solution**: Add missing connections or remove extra rules #### 3. Paradoxical Corrupt States API returns corrupt data but rejects updates **Solution**: May require manual database intervention --- ## False Positives ### What Are They? Validation warnings that are technically "wrong" but acceptable in your use case ### Common False Positives #### 1. "Missing error handling" **Warning**: No error handling configured **When acceptable**: - Simple workflows where failures are obvious - Testing/development workflows - Non-critical notifications **When to fix**: Production workflows handling important data #### 2. "No retry logic" **Warning**: Node doesn't retry on failure **When acceptable**: - APIs with their own retry logic - Idempotent operations - Manual trigger workflows **When to fix**: Flaky external services, production automation #### 3. "Missing rate limiting" **Warning**: No rate limiting for API calls **When acceptable**: - Internal APIs with no limits - Low-volume workflows - APIs with server-side rate limiting **When to fix**: Public APIs, high-volume workflows #### 4. "Unbounded query" **Warning**: SELECT without LIMIT **When acceptable**: - Small known datasets - Aggregation queries - Development/testing **When to fix**: Production queries on large tables ### Reducing False Positives **Use `ai-friendly` profile**: ```javascript validate_node_operation({ nodeType: "nodes-base.slack", config: {...}, profile: "ai-friendly" // Fewer false positives }) ``` --- ## Validation Result Structure ### Complete Response ```javascript { "valid": false, "errors": [ { "type": "missing_required", "property": "channel", "message": "Channel name is required", "fix": "Provide a channel name (lowercase, no spaces)" } ], "warnings": [ { "type": "best_practice", "property": "errorHandling", "message": "Slack API can have rate limits", "suggestion": "Add onError: 'continueRegularOutput'" } ], "suggestions": [ { "type": "optimization", "message": "Consider using batch operations for multiple messages" } ], "summary": { "hasErrors": true, "errorCount": 1, "warningCount": 1, "suggestionCount": 1 } } ``` ### How to Read It #### 1. Check `valid` field ```javascript if (result.valid) { // ✅ Configuration is valid } else { // ❌ Has errors - must fix before deployment } ``` #### 2. Fix errors first ```javascript result.errors.forEach(error => { console.log(`Error in ${error.property}: ${error.message}`); console.log(`Fix: ${error.fix}`); }); ``` #### 3. Review warnings ```javascript result.warnings.forEach(warning => { console.log(`Warning: ${warning.message}`); console.log(`Suggestion: ${warning.suggestion}`); // Decide if you need to address this }); ``` #### 4. Consider suggestions ```javascript // Optional improvements // Not required but may enhance workflow ``` --- ## Workflow Validation ### validate_workflow (Structure) **Validates entire workflow**, not just individual nodes **Checks**: 1. **Node configurations** - Each node valid 2. **Connections** - No broken references 3. **Expressions** - Syntax and references valid 4. **Flow** - Logical workflow structure **Example**: ```javascript validate_workflow({ workflow: { nodes: [...], connections: {...} }, options: { validateNodes: true, validateConnections: true, validateExpressions: true, profile: "runtime" } }) ``` ### Common Workflow Errors #### 1. Broken Connections ```json { "error": "Connection from 'Transform' to 'NonExistent' - target node not found" } ``` **Fix**: Remove stale connection or create missing node #### 2. Circular Dependencies ```json { "error": "Circular dependency detected: Node A → Node B → Node A" } ``` **Fix**: Restructure workflow to remove loop #### 3. Multiple Start Nodes ```json { "warning": "Multiple trigger nodes found - only one will execute" } ``` **Fix**: Remove extra triggers or split into separate workflows #### 4. Disconnected Nodes ```json { "warning": "Node 'Transform' is not connected to workflow flow" } ``` **Fix**: Connect node or remove if unused --- ## Recovery Strategies ### Strategy 1: Start Fresh **When**: Configuration is severely broken **Steps**: 1. Note required fields from `get_node_essentials` 2. Create minimal valid configuration 3. Add features incrementally 4. Validate after each addition ### Strategy 2: Binary Search **When**: Workflow validates but executes incorrectly **Steps**: 1. Remove half the nodes 2. Validate and test 3. If works: problem is in removed nodes 4. If fails: problem is in remaining nodes 5. Repeat until problem isolated ### Strategy 3: Clean Stale Connections **When**: "Node not found" errors **Steps**: ```javascript n8n_update_partial_workflow({ id: "workflow-id", operations: [{ type: "cleanStaleConnections" }] }) ``` ### Strategy 4: Use Auto-fix **When**: Operator structure errors **Steps**: ```javascript n8n_autofix_workflow({ id: "workflow-id", applyFixes: false // Preview first }) // Review fixes, then apply n8n_autofix_workflow({ id: "workflow-id", applyFixes: true }) ``` --- ## Best Practices ### ✅ Do - Validate after every significant change - Read error messages completely - Fix errors iteratively (one at a time) - Use `runtime` profile for pre-deployment - Check `valid` field before assuming success - Trust auto-sanitization for operator issues - Use `get_node_essentials` when unclear about requirements - Document false positives you accept ### ❌ Don't - Skip validation before activation - Try to fix all errors at once - Ignore error messages - Use `strict` profile during development (too noisy) - Assume validation passed (always check result) - Manually fix auto-sanitization issues - Deploy with unresolved errors - Ignore all warnings (some are important!) --- ## Detailed Guides For comprehensive error catalogs and false positive examples: - **[ERROR_CATALOG.md](ERROR_CATALOG.md)** - Complete list of error types with examples - **[FALSE_POSITIVES.md](FALSE_POSITIVES.md)** - When warnings are acceptable --- ## Summary **Key Points**: 1. **Validation is iterative** (avg 2-3 cycles, 23s + 58s) 2. **Errors must be fixed**, warnings are optional 3. **Auto-sanitization** fixes operator structures automatically 4. **Use runtime profile** for balanced validation 5. **False positives exist** - learn to recognize them 6. **Read error messages** - they contain fix guidance **Validation Process**: 1. Validate → Read errors → Fix → Validate again 2. Repeat until valid (usually 2-3 iterations) 3. Review warnings and decide if acceptable 4. Deploy with confidence **Related Skills**: - n8n MCP Tools Expert - Use validation tools correctly - n8n Expression Syntax - Fix expression errors - n8n Node Configuration - Understand required fields
Skill Creator
# Skill Creator This skill provides guidance for creating effective skills. ## About Skills Skills are modular, self-contained packages that extend Claude's capabilities by providing specialized knowledge, workflows, and tools. Think of them as "onboarding guides" for specific domains or tasks—they transform Claude from a general-purpose agent into a specialized agent equipped with procedural knowledge that no model can fully possess. ### What Skills Provide 1. Specialized workflows - Multi-step procedures for specific domains 2. Tool integrations - Instructions for working with specific file formats or APIs 3. Domain expertise - Company-specific knowledge, schemas, business logic 4. Bundled resources - Scripts, references, and assets for complex and repetitive tasks ### Anatomy of a Skill Every skill consists of a required SKILL.md file and optional bundled resources: ``` skill-name/ ├── SKILL.md (required) │ ├── YAML frontmatter metadata (required) │ │ ├── name: (required) │ │ └── description: (required) │ └── Markdown instructions (required) └── Bundled Resources (optional) ├── scripts/ - Executable code (Python/Bash/etc.) ├── references/ - Documentation intended to be loaded into context as needed └── assets/ - Files used in output (templates, icons, fonts, etc.) ``` #### SKILL.md (required) **Metadata Quality:** The `name` and `description` in YAML frontmatter determine when Claude will use the skill. Be specific about what the skill does and when to use it. Use the third-person (e.g. "This skill should be used when..." instead of "Use this skill when..."). #### Bundled Resources (optional) ##### Scripts (`scripts/`) Executable code (Python/Bash/etc.) for tasks that require deterministic reliability or are repeatedly rewritten. - **When to include**: When the same code is being rewritten repeatedly or deterministic reliability is needed - **Example**: `scripts/rotate_pdf.py` for PDF rotation tasks - **Benefits**: Token efficient, deterministic, may be executed without loading into context - **Note**: Scripts may still need to be read by Claude for patching or environment-specific adjustments ##### References (`references/`) Documentation and reference material intended to be loaded as needed into context to inform Claude's process and thinking. - **When to include**: For documentation that Claude should reference while working - **Examples**: `references/finance.md` for financial schemas, `references/mnda.md` for company NDA template, `references/policies.md` for company policies, `references/api_docs.md` for API specifications - **Use cases**: Database schemas, API documentation, domain knowledge, company policies, detailed workflow guides - **Benefits**: Keeps SKILL.md lean, loaded only when Claude determines it's needed - **Best practice**: If files are large (>10k words), include grep search patterns in SKILL.md - **Avoid duplication**: Information should live in either SKILL.md or references files, not both. Prefer references files for detailed information unless it's truly core to the skill—this keeps SKILL.md lean while making information discoverable without hogging the context window. Keep only essential procedural instructions and workflow guidance in SKILL.md; move detailed reference material, schemas, and examples to references files. ##### Assets (`assets/`) Files not intended to be loaded into context, but rather used within the output Claude produces. - **When to include**: When the skill needs files that will be used in the final output - **Examples**: `assets/logo.png` for brand assets, `assets/slides.pptx` for PowerPoint templates, `assets/frontend-template/` for HTML/React boilerplate, `assets/font.ttf` for typography - **Use cases**: Templates, images, icons, boilerplate code, fonts, sample documents that get copied or modified - **Benefits**: Separates output resources from documentation, enables Claude to use files without loading them into context ### Progressive Disclosure Design Principle Skills use a three-level loading system to manage context efficiently: 1. **Metadata (name + description)** - Always in context (~100 words) 2. **SKILL.md body** - When skill triggers (<5k words) 3. **Bundled resources** - As needed by Claude (Unlimited*) *Unlimited because scripts can be executed without reading into context window. ## Skill Creation Process To create a skill, follow the "Skill Creation Process" in order, skipping steps only if there is a clear reason why they are not applicable. ### Step 1: Understanding the Skill with Concrete Examples Skip this step only when the skill's usage patterns are already clearly understood. It remains valuable even when working with an existing skill. To create an effective skill, clearly understand concrete examples of how the skill will be used. This understanding can come from either direct user examples or generated examples that are validated with user feedback. For example, when building an image-editor skill, relevant questions include: - "What functionality should the image-editor skill support? Editing, rotating, anything else?" - "Can you give some examples of how this skill would be used?" - "I can imagine users asking for things like 'Remove the red-eye from this image' or 'Rotate this image'. Are there other ways you imagine this skill being used?" - "What would a user say that should trigger this skill?" To avoid overwhelming users, avoid asking too many questions in a single message. Start with the most important questions and follow up as needed for better effectiveness. Conclude this step when there is a clear sense of the functionality the skill should support. ### Step 2: Planning the Reusable Skill Contents To turn concrete examples into an effective skill, analyze each example by: 1. Considering how to execute on the example from scratch 2. Identifying what scripts, references, and assets would be helpful when executing these workflows repeatedly Example: When building a `pdf-editor` skill to handle queries like "Help me rotate this PDF," the analysis shows: 1. Rotating a PDF requires re-writing the same code each time 2. A `scripts/rotate_pdf.py` script would be helpful to store in the skill Example: When designing a `frontend-webapp-builder` skill for queries like "Build me a todo app" or "Build me a dashboard to track my steps," the analysis shows: 1. Writing a frontend webapp requires the same boilerplate HTML/React each time 2. An `assets/hello-world/` template containing the boilerplate HTML/React project files would be helpful to store in the skill Example: When building a `big-query` skill to handle queries like "How many users have logged in today?" the analysis shows: 1. Querying BigQuery requires re-discovering the table schemas and relationships each time 2. A `references/schema.md` file documenting the table schemas would be helpful to store in the skill To establish the skill's contents, analyze each concrete example to create a list of the reusable resources to include: scripts, references, and assets. ### Step 3: Initializing the Skill At this point, it is time to actually create the skill. Skip this step only if the skill being developed already exists, and iteration or packaging is needed. In this case, continue to the next step. When creating a new skill from scratch, always run the `init_skill.py` script. The script conveniently generates a new template skill directory that automatically includes everything a skill requires, making the skill creation process much more efficient and reliable. Usage: ```bash scripts/init_skill.py <skill-name> --path <output-directory> ``` The script: - Creates the skill directory at the specified path - Generates a SKILL.md template with proper frontmatter and TODO placeholders - Creates example resource directories: `scripts/`, `references/`, and `assets/` - Adds example files in each directory that can be customized or deleted After initialization, customize or remove the generated SKILL.md and example files as needed. ### Step 4: Edit the Skill When editing the (newly-generated or existing) skill, remember that the skill is being created for another instance of Claude to use. Focus on including information that would be beneficial and non-obvious to Claude. Consider what procedural knowledge, domain-specific details, or reusable assets would help another Claude instance execute these tasks more effectively. #### Start with Reusable Skill Contents To begin implementation, start with the reusable resources identified above: `scripts/`, `references/`, and `assets/` files. Note that this step may require user input. For example, when implementing a `brand-guidelines` skill, the user may need to provide brand assets or templates to store in `assets/`, or documentation to store in `references/`. Also, delete any example files and directories not needed for the skill. The initialization script creates example files in `scripts/`, `references/`, and `assets/` to demonstrate structure, but most skills won't need all of them. #### Update SKILL.md **Writing Style:** Write the entire skill using **imperative/infinitive form** (verb-first instructions), not second person. Use objective, instructional language (e.g., "To accomplish X, do Y" rather than "You should do X" or "If you need to do X"). This maintains consistency and clarity for AI consumption. To complete SKILL.md, answer the following questions: 1. What is the purpose of the skill, in a few sentences? 2. When should the skill be used? 3. In practice, how should Claude use the skill? All reusable skill contents developed above should be referenced so that Claude knows how to use them. ### Step 5: Packaging a Skill Once the skill is ready, it should be packaged into a distributable zip file that gets shared with the user. The packaging process automatically validates the skill first to ensure it meets all requirements: ```bash scripts/package_skill.py <path/to/skill-folder> ``` Optional output directory specification: ```bash scripts/package_skill.py <path/to/skill-folder> ./dist ``` The packaging script will: 1. **Validate** the skill automatically, checking: - YAML frontmatter format and required fields - Skill naming conventions and directory structure - Description completeness and quality - File organization and resource references 2. **Package** the skill if validation passes, creating a zip file named after the skill (e.g., `my-skill.zip`) that includes all files and maintains the proper directory structure for distribution. If validation fails, the script will report the errors and exit without creating a package. Fix any validation errors and run the packaging command again. ### Step 6: Iterate After testing the skill, users may request improvements. Often this happens right after using the skill, with fresh context of how the skill performed. **Iteration workflow:** 1. Use the skill on real tasks 2. Notice struggles or inefficiencies 3. Identify how SKILL.md or bundled resources should be updated 4. Implement changes and test again
JavaScript Code Node
# JavaScript Code Node Expert guidance for writing JavaScript code in n8n Code nodes. --- ## Quick Start ```javascript // Basic template for Code nodes const items = $input.all(); // Process data const processed = items.map(item => ({ json: { ...item.json, processed: true, timestamp: new Date().toISOString() } })); return processed; ``` ### Essential Rules 1. **Choose "Run Once for All Items" mode** (recommended for most use cases) 2. **Access data**: `$input.all()`, `$input.first()`, or `$input.item` 3. **CRITICAL**: Must return `[{json: {...}}]` format 4. **CRITICAL**: Webhook data is under `$json.body` (not `$json` directly) 5. **Built-ins available**: $helpers.httpRequest(), DateTime (Luxon), $jmespath() --- ## Mode Selection Guide The Code node offers two execution modes. Choose based on your use case: ### Run Once for All Items (Recommended - Default) **Use this mode for:** 95% of use cases - **How it works**: Code executes **once** regardless of input count - **Data access**: `$input.all()` or `items` array - **Best for**: Aggregation, filtering, batch processing, transformations, API calls with all data - **Performance**: Faster for multiple items (single execution) ```javascript // Example: Calculate total from all items const allItems = $input.all(); const total = allItems.reduce((sum, item) => sum + (item.json.amount || 0), 0); return [{ json: { total, count: allItems.length, average: total / allItems.length } }]; ``` **When to use:** - ✅ Comparing items across the dataset - ✅ Calculating totals, averages, or statistics - ✅ Sorting or ranking items - ✅ Deduplication - ✅ Building aggregated reports - ✅ Combining data from multiple items ### Run Once for Each Item **Use this mode for:** Specialized cases only - **How it works**: Code executes **separately** for each input item - **Data access**: `$input.item` or `$item` - **Best for**: Item-specific logic, independent operations, per-item validation - **Performance**: Slower for large datasets (multiple executions) ```javascript // Example: Add processing timestamp to each item const item = $input.item; return [{ json: { ...item.json, processed: true, processedAt: new Date().toISOString() } }]; ``` **When to use:** - ✅ Each item needs independent API call - ✅ Per-item validation with different error handling - ✅ Item-specific transformations based on item properties - ✅ When items must be processed separately for business logic **Decision Shortcut:** - **Need to look at multiple items?** → Use "All Items" mode - **Each item completely independent?** → Use "Each Item" mode - **Not sure?** → Use "All Items" mode (you can always loop inside) --- ## Data Access Patterns ### Pattern 1: $input.all() - Most Common **Use when**: Processing arrays, batch operations, aggregations ```javascript // Get all items from previous node const allItems = $input.all(); // Filter, map, reduce as needed const valid = allItems.filter(item => item.json.status === 'active'); const mapped = valid.map(item => ({ json: { id: item.json.id, name: item.json.name } })); return mapped; ``` ### Pattern 2: $input.first() - Very Common **Use when**: Working with single objects, API responses, first-in-first-out ```javascript // Get first item only const firstItem = $input.first(); const data = firstItem.json; return [{ json: { result: processData(data), processedAt: new Date().toISOString() } }]; ``` ### Pattern 3: $input.item - Each Item Mode Only **Use when**: In "Run Once for Each Item" mode ```javascript // Current item in loop (Each Item mode only) const currentItem = $input.item; return [{ json: { ...currentItem.json, itemProcessed: true } }]; ``` ### Pattern 4: $node - Reference Other Nodes **Use when**: Need data from specific nodes in workflow ```javascript // Get output from specific node const webhookData = $node["Webhook"].json; const httpData = $node["HTTP Request"].json; return [{ json: { combined: { webhook: webhookData, api: httpData } } }]; ``` **See**: [DATA_ACCESS.md](DATA_ACCESS.md) for comprehensive guide --- ## Critical: Webhook Data Structure **MOST COMMON MISTAKE**: Webhook data is nested under `.body` ```javascript // ❌ WRONG - Will return undefined const name = $json.name; const email = $json.email; // ✅ CORRECT - Webhook data is under .body const name = $json.body.name; const email = $json.body.email; // Or with $input const webhookData = $input.first().json.body; const name = webhookData.name; ``` **Why**: Webhook node wraps all request data under `body` property. This includes POST data, query parameters, and JSON payloads. **See**: [DATA_ACCESS.md](DATA_ACCESS.md) for full webhook structure details --- ## Return Format Requirements **CRITICAL RULE**: Always return array of objects with `json` property ### Correct Return Formats ```javascript // ✅ Single result return [{ json: { field1: value1, field2: value2 } }]; // ✅ Multiple results return [ {json: {id: 1, data: 'first'}}, {json: {id: 2, data: 'second'}} ]; // ✅ Transformed array const transformed = $input.all() .filter(item => item.json.valid) .map(item => ({ json: { id: item.json.id, processed: true } })); return transformed; // ✅ Empty result (when no data to return) return []; // ✅ Conditional return if (shouldProcess) { return [{json: processedData}]; } else { return []; } ``` ### Incorrect Return Formats ```javascript // ❌ WRONG: Object without array wrapper return { json: {field: value} }; // ❌ WRONG: Array without json wrapper return [{field: value}]; // ❌ WRONG: Plain string return "processed"; // ❌ WRONG: Raw data without mapping return $input.all(); // Missing .map() // ❌ WRONG: Incomplete structure return [{data: value}]; // Should be {json: value} ``` **Why it matters**: Next nodes expect array format. Incorrect format causes workflow execution to fail. **See**: [ERROR_PATTERNS.md](ERROR_PATTERNS.md) #3 for detailed error solutions --- ## Common Patterns Overview Based on production workflows, here are the most useful patterns: ### 1. Multi-Source Data Aggregation Combine data from multiple APIs, webhooks, or nodes ```javascript const allItems = $input.all(); const results = []; for (const item of allItems) { const sourceName = item.json.name || 'Unknown'; // Parse source-specific structure if (sourceName === 'API1' && item.json.data) { results.push({ json: { title: item.json.data.title, source: 'API1' } }); } } return results; ``` ### 2. Filtering with Regex Extract patterns, mentions, or keywords from text ```javascript const pattern = /\b([A-Z]{2,5})\b/g; const matches = {}; for (const item of $input.all()) { const text = item.json.text; const found = text.match(pattern); if (found) { found.forEach(match => { matches[match] = (matches[match] || 0) + 1; }); } } return [{json: {matches}}]; ``` ### 3. Data Transformation & Enrichment Map fields, normalize formats, add computed fields ```javascript const items = $input.all(); return items.map(item => { const data = item.json; const nameParts = data.name.split(' '); return { json: { first_name: nameParts[0], last_name: nameParts.slice(1).join(' '), email: data.email, created_at: new Date().toISOString() } }; }); ``` ### 4. Top N Filtering & Ranking Sort and limit results ```javascript const items = $input.all(); const topItems = items .sort((a, b) => (b.json.score || 0) - (a.json.score || 0)) .slice(0, 10); return topItems.map(item => ({json: item.json})); ``` ### 5. Aggregation & Reporting Sum, count, group data ```javascript const items = $input.all(); const total = items.reduce((sum, item) => sum + (item.json.amount || 0), 0); return [{ json: { total, count: items.length, average: total / items.length, timestamp: new Date().toISOString() } }]; ``` **See**: [COMMON_PATTERNS.md](COMMON_PATTERNS.md) for 10 detailed production patterns --- ## Error Prevention - Top 5 Mistakes ### #1: Empty Code or Missing Return (Most Common) ```javascript // ❌ WRONG: No return statement const items = $input.all(); // ... processing code ... // Forgot to return! // ✅ CORRECT: Always return data const items = $input.all(); // ... processing ... return items.map(item => ({json: item.json})); ``` ### #2: Expression Syntax Confusion ```javascript // ❌ WRONG: Using n8n expression syntax in code const value = "{{ $json.field }}"; // ✅ CORRECT: Use JavaScript template literals const value = `${$json.field}`; // ✅ CORRECT: Direct access const value = $input.first().json.field; ``` ### #3: Incorrect Return Wrapper ```javascript // ❌ WRONG: Returning object instead of array return {json: {result: 'success'}}; // ✅ CORRECT: Array wrapper required return [{json: {result: 'success'}}]; ``` ### #4: Missing Null Checks ```javascript // ❌ WRONG: Crashes if field doesn't exist const value = item.json.user.email; // ✅ CORRECT: Safe access with optional chaining const value = item.json?.user?.email || 'no-email@example.com'; // ✅ CORRECT: Guard clause if (!item.json.user) { return []; } const value = item.json.user.email; ``` ### #5: Webhook Body Nesting ```javascript // ❌ WRONG: Direct access to webhook data const email = $json.email; // ✅ CORRECT: Webhook data under .body const email = $json.body.email; ``` **See**: [ERROR_PATTERNS.md](ERROR_PATTERNS.md) for comprehensive error guide --- ## Built-in Functions & Helpers ### $helpers.httpRequest() Make HTTP requests from within code: ```javascript const response = await $helpers.httpRequest({ method: 'GET', url: 'https://api.example.com/data', headers: { 'Authorization': 'Bearer token', 'Content-Type': 'application/json' } }); return [{json: {data: response}}]; ``` ### DateTime (Luxon) Date and time operations: ```javascript // Current time const now = DateTime.now(); // Format dates const formatted = now.toFormat('yyyy-MM-dd'); const iso = now.toISO(); // Date arithmetic const tomorrow = now.plus({days: 1}); const lastWeek = now.minus({weeks: 1}); return [{ json: { today: formatted, tomorrow: tomorrow.toFormat('yyyy-MM-dd') } }]; ``` ### $jmespath() Query JSON structures: ```javascript const data = $input.first().json; // Filter array const adults = $jmespath(data, 'users[?age >= `18`]'); // Extract fields const names = $jmespath(data, 'users[*].name'); return [{json: {adults, names}}]; ``` **See**: [BUILTIN_FUNCTIONS.md](BUILTIN_FUNCTIONS.md) for complete reference --- ## Best Practices ### 1. Always Validate Input Data ```javascript const items = $input.all(); // Check if data exists if (!items || items.length === 0) { return []; } // Validate structure if (!items[0].json) { return [{json: {error: 'Invalid input format'}}]; } // Continue processing... ``` ### 2. Use Try-Catch for Error Handling ```javascript try { const response = await $helpers.httpRequest({ url: 'https://api.example.com/data' }); return [{json: {success: true, data: response}}]; } catch (error) { return [{ json: { success: false, error: error.message } }]; } ``` ### 3. Prefer Array Methods Over Loops ```javascript // ✅ GOOD: Functional approach const processed = $input.all() .filter(item => item.json.valid) .map(item => ({json: {id: item.json.id}})); // ❌ SLOWER: Manual loop const processed = []; for (const item of $input.all()) { if (item.json.valid) { processed.push({json: {id: item.json.id}}); } } ``` ### 4. Filter Early, Process Late ```javascript // ✅ GOOD: Filter first to reduce processing const processed = $input.all() .filter(item => item.json.status === 'active') // Reduce dataset first .map(item => expensiveTransformation(item)); // Then transform // ❌ WASTEFUL: Transform everything, then filter const processed = $input.all() .map(item => expensiveTransformation(item)) // Wastes CPU .filter(item => item.json.status === 'active'); ``` ### 5. Use Descriptive Variable Names ```javascript // ✅ GOOD: Clear intent const activeUsers = $input.all().filter(item => item.json.active); const totalRevenue = activeUsers.reduce((sum, user) => sum + user.json.revenue, 0); // ❌ BAD: Unclear purpose const a = $input.all().filter(item => item.json.active); const t = a.reduce((s, u) => s + u.json.revenue, 0); ``` ### 6. Debug with console.log() ```javascript // Debug statements appear in browser console const items = $input.all(); console.log(`Processing ${items.length} items`); for (const item of items) { console.log('Item data:', item.json); // Process... } return result; ``` --- ## When to Use Code Node Use Code node when: - ✅ Complex transformations requiring multiple steps - ✅ Custom calculations or business logic - ✅ Recursive operations - ✅ API response parsing with complex structure - ✅ Multi-step conditionals - ✅ Data aggregation across items Consider other nodes when: - ❌ Simple field mapping → Use **Set** node - ❌ Basic filtering → Use **Filter** node - ❌ Simple conditionals → Use **IF** or **Switch** node - ❌ HTTP requests only → Use **HTTP Request** node **Code node excels at**: Complex logic that would require chaining many simple nodes --- ## Integration with Other Skills ### Works With: **n8n Expression Syntax**: - Expressions use `{{ }}` syntax in other nodes - Code nodes use JavaScript directly (no `{{ }}`) - When to use expressions vs code **n8n MCP Tools Expert**: - How to find Code node: `search_nodes({query: "code"})` - Get configuration help: `get_node_essentials("nodes-base.code")` - Validate code: `validate_node_operation()` **n8n Node Configuration**: - Mode selection (All Items vs Each Item) - Language selection (JavaScript vs Python) - Understanding property dependencies **n8n Workflow Patterns**: - Code nodes in transformation step - Webhook → Code → API pattern - Error handling in workflows **n8n Validation Expert**: - Validate Code node configuration - Handle validation errors - Auto-fix common issues --- ## Quick Reference Checklist Before deploying Code nodes, verify: - [ ] **Code is not empty** - Must have meaningful logic - [ ] **Return statement exists** - Must return array of objects - [ ] **Proper return format** - Each item: `{json: {...}}` - [ ] **Data access correct** - Using `$input.all()`, `$input.first()`, or `$input.item` - [ ] **No n8n expressions** - Use JavaScript template literals: `` `${value}` `` - [ ] **Error handling** - Guard clauses for null/undefined inputs - [ ] **Webhook data** - Access via `.body` if from webhook - [ ] **Mode selection** - "All Items" for most cases - [ ] **Performance** - Prefer map/filter over manual loops - [ ] **Output consistent** - All code paths return same structure --- ## Additional Resources ### Related Files - [DATA_ACCESS.md](DATA_ACCESS.md) - Comprehensive data access patterns - [COMMON_PATTERNS.md](COMMON_PATTERNS.md) - 10 production-tested patterns - [ERROR_PATTERNS.md](ERROR_PATTERNS.md) - Top 5 errors and solutions - [BUILTIN_FUNCTIONS.md](BUILTIN_FUNCTIONS.md) - Complete built-in reference ### n8n Documentation - Code Node Guide: https://docs.n8n.io/code/code-node/ - Built-in Methods: https://docs.n8n.io/code-examples/methods-variables-reference/ - Luxon Documentation: https://moment.github.io/luxon/ --- **Ready to write JavaScript in n8n Code nodes!** Start with simple transformations, use the error patterns guide to avoid common mistakes, and reference the pattern library for production-ready examples.
Skill Creator
# Skill Creator This skill provides guidance for creating effective skills. ## About Skills Skills are modular, self-contained packages that extend Claude's capabilities by providing specialized knowledge, workflows, and tools. Think of them as "onboarding guides" for specific domains or tasks—they transform Claude from a general-purpose agent into a specialized agent equipped with procedural knowledge that no model can fully possess. ### What Skills Provide 1. Specialized workflows - Multi-step procedures for specific domains 2. Tool integrations - Instructions for working with specific file formats or APIs 3. Domain expertise - Company-specific knowledge, schemas, business logic 4. Bundled resources - Scripts, references, and assets for complex and repetitive tasks ### Anatomy of a Skill Every skill consists of a required SKILL.md file and optional bundled resources: ``` skill-name/ ├── SKILL.md (required) │ ├── YAML frontmatter metadata (required) │ │ ├── name: (required) │ │ └── description: (required) │ └── Markdown instructions (required) └── Bundled Resources (optional) ├── scripts/ - Executable code (Python/Bash/etc.) ├── references/ - Documentation intended to be loaded into context as needed └── assets/ - Files used in output (templates, icons, fonts, etc.) ``` #### SKILL.md (required) **Metadata Quality:** The `name` and `description` in YAML frontmatter determine when Claude will use the skill. Be specific about what the skill does and when to use it. Use the third-person (e.g. "This skill should be used when..." instead of "Use this skill when..."). #### Bundled Resources (optional) ##### Scripts (`scripts/`) Executable code (Python/Bash/etc.) for tasks that require deterministic reliability or are repeatedly rewritten. - **When to include**: When the same code is being rewritten repeatedly or deterministic reliability is needed - **Example**: `scripts/rotate_pdf.py` for PDF rotation tasks - **Benefits**: Token efficient, deterministic, may be executed without loading into context - **Note**: Scripts may still need to be read by Claude for patching or environment-specific adjustments ##### References (`references/`) Documentation and reference material intended to be loaded as needed into context to inform Claude's process and thinking. - **When to include**: For documentation that Claude should reference while working - **Examples**: `references/finance.md` for financial schemas, `references/mnda.md` for company NDA template, `references/policies.md` for company policies, `references/api_docs.md` for API specifications - **Use cases**: Database schemas, API documentation, domain knowledge, company policies, detailed workflow guides - **Benefits**: Keeps SKILL.md lean, loaded only when Claude determines it's needed - **Best practice**: If files are large (>10k words), include grep search patterns in SKILL.md - **Avoid duplication**: Information should live in either SKILL.md or references files, not both. Prefer references files for detailed information unless it's truly core to the skill—this keeps SKILL.md lean while making information discoverable without hogging the context window. Keep only essential procedural instructions and workflow guidance in SKILL.md; move detailed reference material, schemas, and examples to references files. ##### Assets (`assets/`) Files not intended to be loaded into context, but rather used within the output Claude produces. - **When to include**: When the skill needs files that will be used in the final output - **Examples**: `assets/logo.png` for brand assets, `assets/slides.pptx` for PowerPoint templates, `assets/frontend-template/` for HTML/React boilerplate, `assets/font.ttf` for typography - **Use cases**: Templates, images, icons, boilerplate code, fonts, sample documents that get copied or modified - **Benefits**: Separates output resources from documentation, enables Claude to use files without loading them into context ### Progressive Disclosure Design Principle Skills use a three-level loading system to manage context efficiently: 1. **Metadata (name + description)** - Always in context (~100 words) 2. **SKILL.md body** - When skill triggers (<5k words) 3. **Bundled resources** - As needed by Claude (Unlimited*) *Unlimited because scripts can be executed without reading into context window. ## Skill Creation Process To create a skill, follow the "Skill Creation Process" in order, skipping steps only if there is a clear reason why they are not applicable. ### Step 1: Understanding the Skill with Concrete Examples Skip this step only when the skill's usage patterns are already clearly understood. It remains valuable even when working with an existing skill. To create an effective skill, clearly understand concrete examples of how the skill will be used. This understanding can come from either direct user examples or generated examples that are validated with user feedback. For example, when building an image-editor skill, relevant questions include: - "What functionality should the image-editor skill support? Editing, rotating, anything else?" - "Can you give some examples of how this skill would be used?" - "I can imagine users asking for things like 'Remove the red-eye from this image' or 'Rotate this image'. Are there other ways you imagine this skill being used?" - "What would a user say that should trigger this skill?" To avoid overwhelming users, avoid asking too many questions in a single message. Start with the most important questions and follow up as needed for better effectiveness. Conclude this step when there is a clear sense of the functionality the skill should support. ### Step 2: Planning the Reusable Skill Contents To turn concrete examples into an effective skill, analyze each example by: 1. Considering how to execute on the example from scratch 2. Identifying what scripts, references, and assets would be helpful when executing these workflows repeatedly Example: When building a `pdf-editor` skill to handle queries like "Help me rotate this PDF," the analysis shows: 1. Rotating a PDF requires re-writing the same code each time 2. A `scripts/rotate_pdf.py` script would be helpful to store in the skill Example: When designing a `frontend-webapp-builder` skill for queries like "Build me a todo app" or "Build me a dashboard to track my steps," the analysis shows: 1. Writing a frontend webapp requires the same boilerplate HTML/React each time 2. An `assets/hello-world/` template containing the boilerplate HTML/React project files would be helpful to store in the skill Example: When building a `big-query` skill to handle queries like "How many users have logged in today?" the analysis shows: 1. Querying BigQuery requires re-discovering the table schemas and relationships each time 2. A `references/schema.md` file documenting the table schemas would be helpful to store in the skill To establish the skill's contents, analyze each concrete example to create a list of the reusable resources to include: scripts, references, and assets. ### Step 3: Initializing the Skill At this point, it is time to actually create the skill. Skip this step only if the skill being developed already exists, and iteration or packaging is needed. In this case, continue to the next step. When creating a new skill from scratch, always run the `init_skill.py` script. The script conveniently generates a new template skill directory that automatically includes everything a skill requires, making the skill creation process much more efficient and reliable. Usage: ```bash scripts/init_skill.py <skill-name> --path <output-directory> ``` The script: - Creates the skill directory at the specified path - Generates a SKILL.md template with proper frontmatter and TODO placeholders - Creates example resource directories: `scripts/`, `references/`, and `assets/` - Adds example files in each directory that can be customized or deleted After initialization, customize or remove the generated SKILL.md and example files as needed. ### Step 4: Edit the Skill When editing the (newly-generated or existing) skill, remember that the skill is being created for another instance of Claude to use. Focus on including information that would be beneficial and non-obvious to Claude. Consider what procedural knowledge, domain-specific details, or reusable assets would help another Claude instance execute these tasks more effectively. #### Start with Reusable Skill Contents To begin implementation, start with the reusable resources identified above: `scripts/`, `references/`, and `assets/` files. Note that this step may require user input. For example, when implementing a `brand-guidelines` skill, the user may need to provide brand assets or templates to store in `assets/`, or documentation to store in `references/`. Also, delete any example files and directories not needed for the skill. The initialization script creates example files in `scripts/`, `references/`, and `assets/` to demonstrate structure, but most skills won't need all of them. #### Update SKILL.md **Writing Style:** Write the entire skill using **imperative/infinitive form** (verb-first instructions), not second person. Use objective, instructional language (e.g., "To accomplish X, do Y" rather than "You should do X" or "If you need to do X"). This maintains consistency and clarity for AI consumption. To complete SKILL.md, answer the following questions: 1. What is the purpose of the skill, in a few sentences? 2. When should the skill be used? 3. In practice, how should Claude use the skill? All reusable skill contents developed above should be referenced so that Claude knows how to use them. ### Step 5: Packaging a Skill Once the skill is ready, it should be packaged into a distributable zip file that gets shared with the user. The packaging process automatically validates the skill first to ensure it meets all requirements: ```bash scripts/package_skill.py <path/to/skill-folder> ``` Optional output directory specification: ```bash scripts/package_skill.py <path/to/skill-folder> ./dist ``` The packaging script will: 1. **Validate** the skill automatically, checking: - YAML frontmatter format and required fields - Skill naming conventions and directory structure - Description completeness and quality - File organization and resource references 2. **Package** the skill if validation passes, creating a zip file named after the skill (e.g., `my-skill.zip`) that includes all files and maintains the proper directory structure for distribution. If validation fails, the script will report the errors and exit without creating a package. Fix any validation errors and run the packaging command again. ### Step 6: Iterate After testing the skill, users may request improvements. Often this happens right after using the skill, with fresh context of how the skill performed. **Iteration workflow:** 1. Use the skill on real tasks 2. Notice struggles or inefficiencies 3. Identify how SKILL.md or bundled resources should be updated 4. Implement changes and test again
Skill Creator 4
# Skill Creator This skill provides guidance for creating effective skills. ## About Skills Skills are modular, self-contained packages that extend Claude's capabilities by providing specialized knowledge, workflows, and tools. Think of them as "onboarding guides" for specific domains or tasks—they transform Claude from a general-purpose agent into a specialized agent equipped with procedural knowledge that no model can fully possess. ### What Skills Provide 1. Specialized workflows - Multi-step procedures for specific domains 2. Tool integrations - Instructions for working with specific file formats or APIs 3. Domain expertise - Company-specific knowledge, schemas, business logic 4. Bundled resources - Scripts, references, and assets for complex and repetitive tasks ### Anatomy of a Skill Every skill consists of a required SKILL.md file and optional bundled resources: ``` skill-name/ ├── SKILL.md (required) │ ├── YAML frontmatter metadata (required) │ │ ├── name: (required) │ │ └── description: (required) │ └── Markdown instructions (required) └── Bundled Resources (optional) ├── scripts/ - Executable code (Python/Bash/etc.) ├── references/ - Documentation intended to be loaded into context as needed └── assets/ - Files used in output (templates, icons, fonts, etc.) ``` #### SKILL.md (required) **Metadata Quality:** The `name` and `description` in YAML frontmatter determine when Claude will use the skill. Be specific about what the skill does and when to use it. Use the third-person (e.g. "This skill should be used when..." instead of "Use this skill when..."). #### Bundled Resources (optional) ##### Scripts (`scripts/`) Executable code (Python/Bash/etc.) for tasks that require deterministic reliability or are repeatedly rewritten. - **When to include**: When the same code is being rewritten repeatedly or deterministic reliability is needed - **Example**: `scripts/rotate_pdf.py` for PDF rotation tasks - **Benefits**: Token efficient, deterministic, may be executed without loading into context - **Note**: Scripts may still need to be read by Claude for patching or environment-specific adjustments ##### References (`references/`) Documentation and reference material intended to be loaded as needed into context to inform Claude's process and thinking. - **When to include**: For documentation that Claude should reference while working - **Examples**: `references/finance.md` for financial schemas, `references/mnda.md` for company NDA template, `references/policies.md` for company policies, `references/api_docs.md` for API specifications - **Use cases**: Database schemas, API documentation, domain knowledge, company policies, detailed workflow guides - **Benefits**: Keeps SKILL.md lean, loaded only when Claude determines it's needed - **Best practice**: If files are large (>10k words), include grep search patterns in SKILL.md - **Avoid duplication**: Information should live in either SKILL.md or references files, not both. Prefer references files for detailed information unless it's truly core to the skill—this keeps SKILL.md lean while making information discoverable without hogging the context window. Keep only essential procedural instructions and workflow guidance in SKILL.md; move detailed reference material, schemas, and examples to references files. ##### Assets (`assets/`) Files not intended to be loaded into context, but rather used within the output Claude produces. - **When to include**: When the skill needs files that will be used in the final output - **Examples**: `assets/logo.png` for brand assets, `assets/slides.pptx` for PowerPoint templates, `assets/frontend-template/` for HTML/React boilerplate, `assets/font.ttf` for typography - **Use cases**: Templates, images, icons, boilerplate code, fonts, sample documents that get copied or modified - **Benefits**: Separates output resources from documentation, enables Claude to use files without loading them into context ### Progressive Disclosure Design Principle Skills use a three-level loading system to manage context efficiently: 1. **Metadata (name + description)** - Always in context (~100 words) 2. **SKILL.md body** - When skill triggers (<5k words) 3. **Bundled resources** - As needed by Claude (Unlimited*) *Unlimited because scripts can be executed without reading into context window. ## Skill Creation Process To create a skill, follow the "Skill Creation Process" in order, skipping steps only if there is a clear reason why they are not applicable. ### Step 1: Understanding the Skill with Concrete Examples Skip this step only when the skill's usage patterns are already clearly understood. It remains valuable even when working with an existing skill. To create an effective skill, clearly understand concrete examples of how the skill will be used. This understanding can come from either direct user examples or generated examples that are validated with user feedback. For example, when building an image-editor skill, relevant questions include: - "What functionality should the image-editor skill support? Editing, rotating, anything else?" - "Can you give some examples of how this skill would be used?" - "I can imagine users asking for things like 'Remove the red-eye from this image' or 'Rotate this image'. Are there other ways you imagine this skill being used?" - "What would a user say that should trigger this skill?" To avoid overwhelming users, avoid asking too many questions in a single message. Start with the most important questions and follow up as needed for better effectiveness. Conclude this step when there is a clear sense of the functionality the skill should support. ### Step 2: Planning the Reusable Skill Contents To turn concrete examples into an effective skill, analyze each example by: 1. Considering how to execute on the example from scratch 2. Identifying what scripts, references, and assets would be helpful when executing these workflows repeatedly Example: When building a `pdf-editor` skill to handle queries like "Help me rotate this PDF," the analysis shows: 1. Rotating a PDF requires re-writing the same code each time 2. A `scripts/rotate_pdf.py` script would be helpful to store in the skill Example: When designing a `frontend-webapp-builder` skill for queries like "Build me a todo app" or "Build me a dashboard to track my steps," the analysis shows: 1. Writing a frontend webapp requires the same boilerplate HTML/React each time 2. An `assets/hello-world/` template containing the boilerplate HTML/React project files would be helpful to store in the skill Example: When building a `big-query` skill to handle queries like "How many users have logged in today?" the analysis shows: 1. Querying BigQuery requires re-discovering the table schemas and relationships each time 2. A `references/schema.md` file documenting the table schemas would be helpful to store in the skill To establish the skill's contents, analyze each concrete example to create a list of the reusable resources to include: scripts, references, and assets. ### Step 3: Initializing the Skill At this point, it is time to actually create the skill. Skip this step only if the skill being developed already exists, and iteration or packaging is needed. In this case, continue to the next step. When creating a new skill from scratch, always run the `init_skill.py` script. The script conveniently generates a new template skill directory that automatically includes everything a skill requires, making the skill creation process much more efficient and reliable. Usage: ```bash scripts/init_skill.py <skill-name> --path <output-directory> ``` The script: - Creates the skill directory at the specified path - Generates a SKILL.md template with proper frontmatter and TODO placeholders - Creates example resource directories: `scripts/`, `references/`, and `assets/` - Adds example files in each directory that can be customized or deleted After initialization, customize or remove the generated SKILL.md and example files as needed. ### Step 4: Edit the Skill When editing the (newly-generated or existing) skill, remember that the skill is being created for another instance of Claude to use. Focus on including information that would be beneficial and non-obvious to Claude. Consider what procedural knowledge, domain-specific details, or reusable assets would help another Claude instance execute these tasks more effectively. #### Start with Reusable Skill Contents To begin implementation, start with the reusable resources identified above: `scripts/`, `references/`, and `assets/` files. Note that this step may require user input. For example, when implementing a `brand-guidelines` skill, the user may need to provide brand assets or templates to store in `assets/`, or documentation to store in `references/`. Also, delete any example files and directories not needed for the skill. The initialization script creates example files in `scripts/`, `references/`, and `assets/` to demonstrate structure, but most skills won't need all of them. #### Update SKILL.md **Writing Style:** Write the entire skill using **imperative/infinitive form** (verb-first instructions), not second person. Use objective, instructional language (e.g., "To accomplish X, do Y" rather than "You should do X" or "If you need to do X"). This maintains consistency and clarity for AI consumption. To complete SKILL.md, answer the following questions: 1. What is the purpose of the skill, in a few sentences? 2. When should the skill be used? 3. In practice, how should Claude use the skill? All reusable skill contents developed above should be referenced so that Claude knows how to use them. ### Step 5: Packaging a Skill Once the skill is ready, it should be packaged into a distributable zip file that gets shared with the user. The packaging process automatically validates the skill first to ensure it meets all requirements: ```bash scripts/package_skill.py <path/to/skill-folder> ``` Optional output directory specification: ```bash scripts/package_skill.py <path/to/skill-folder> ./dist ``` The packaging script will: 1. **Validate** the skill automatically, checking: - YAML frontmatter format and required fields - Skill naming conventions and directory structure - Description completeness and quality - File organization and resource references 2. **Package** the skill if validation passes, creating a zip file named after the skill (e.g., `my-skill.zip`) that includes all files and maintains the proper directory structure for distribution. If validation fails, the script will report the errors and exit without creating a package. Fix any validation errors and run the packaging command again. ### Step 6: Iterate After testing the skill, users may request improvements. Often this happens right after using the skill, with fresh context of how the skill performed. **Iteration workflow:** 1. Use the skill on real tasks 2. Notice struggles or inefficiencies 3. Identify how SKILL.md or bundled resources should be updated 4. Implement changes and test again
Skill Creator 2
# Skill Creator This skill provides guidance for creating effective skills. ## About Skills Skills are modular, self-contained packages that extend Claude's capabilities by providing specialized knowledge, workflows, and tools. Think of them as "onboarding guides" for specific domains or tasks—they transform Claude from a general-purpose agent into a specialized agent equipped with procedural knowledge that no model can fully possess. ### What Skills Provide 1. Specialized workflows - Multi-step procedures for specific domains 2. Tool integrations - Instructions for working with specific file formats or APIs 3. Domain expertise - Company-specific knowledge, schemas, business logic 4. Bundled resources - Scripts, references, and assets for complex and repetitive tasks ### Anatomy of a Skill Every skill consists of a required SKILL.md file and optional bundled resources: ``` skill-name/ ├── SKILL.md (required) │ ├── YAML frontmatter metadata (required) │ │ ├── name: (required) │ │ └── description: (required) │ └── Markdown instructions (required) └── Bundled Resources (optional) ├── scripts/ - Executable code (Python/Bash/etc.) ├── references/ - Documentation intended to be loaded into context as needed └── assets/ - Files used in output (templates, icons, fonts, etc.) ``` #### SKILL.md (required) **Metadata Quality:** The `name` and `description` in YAML frontmatter determine when Claude will use the skill. Be specific about what the skill does and when to use it. Use the third-person (e.g. "This skill should be used when..." instead of "Use this skill when..."). #### Bundled Resources (optional) ##### Scripts (`scripts/`) Executable code (Python/Bash/etc.) for tasks that require deterministic reliability or are repeatedly rewritten. - **When to include**: When the same code is being rewritten repeatedly or deterministic reliability is needed - **Example**: `scripts/rotate_pdf.py` for PDF rotation tasks - **Benefits**: Token efficient, deterministic, may be executed without loading into context - **Note**: Scripts may still need to be read by Claude for patching or environment-specific adjustments ##### References (`references/`) Documentation and reference material intended to be loaded as needed into context to inform Claude's process and thinking. - **When to include**: For documentation that Claude should reference while working - **Examples**: `references/finance.md` for financial schemas, `references/mnda.md` for company NDA template, `references/policies.md` for company policies, `references/api_docs.md` for API specifications - **Use cases**: Database schemas, API documentation, domain knowledge, company policies, detailed workflow guides - **Benefits**: Keeps SKILL.md lean, loaded only when Claude determines it's needed - **Best practice**: If files are large (>10k words), include grep search patterns in SKILL.md - **Avoid duplication**: Information should live in either SKILL.md or references files, not both. Prefer references files for detailed information unless it's truly core to the skill—this keeps SKILL.md lean while making information discoverable without hogging the context window. Keep only essential procedural instructions and workflow guidance in SKILL.md; move detailed reference material, schemas, and examples to references files. ##### Assets (`assets/`) Files not intended to be loaded into context, but rather used within the output Claude produces. - **When to include**: When the skill needs files that will be used in the final output - **Examples**: `assets/logo.png` for brand assets, `assets/slides.pptx` for PowerPoint templates, `assets/frontend-template/` for HTML/React boilerplate, `assets/font.ttf` for typography - **Use cases**: Templates, images, icons, boilerplate code, fonts, sample documents that get copied or modified - **Benefits**: Separates output resources from documentation, enables Claude to use files without loading them into context ### Progressive Disclosure Design Principle Skills use a three-level loading system to manage context efficiently: 1. **Metadata (name + description)** - Always in context (~100 words) 2. **SKILL.md body** - When skill triggers (<5k words) 3. **Bundled resources** - As needed by Claude (Unlimited*) *Unlimited because scripts can be executed without reading into context window. ## Skill Creation Process To create a skill, follow the "Skill Creation Process" in order, skipping steps only if there is a clear reason why they are not applicable. ### Step 1: Understanding the Skill with Concrete Examples Skip this step only when the skill's usage patterns are already clearly understood. It remains valuable even when working with an existing skill. To create an effective skill, clearly understand concrete examples of how the skill will be used. This understanding can come from either direct user examples or generated examples that are validated with user feedback. For example, when building an image-editor skill, relevant questions include: - "What functionality should the image-editor skill support? Editing, rotating, anything else?" - "Can you give some examples of how this skill would be used?" - "I can imagine users asking for things like 'Remove the red-eye from this image' or 'Rotate this image'. Are there other ways you imagine this skill being used?" - "What would a user say that should trigger this skill?" To avoid overwhelming users, avoid asking too many questions in a single message. Start with the most important questions and follow up as needed for better effectiveness. Conclude this step when there is a clear sense of the functionality the skill should support. ### Step 2: Planning the Reusable Skill Contents To turn concrete examples into an effective skill, analyze each example by: 1. Considering how to execute on the example from scratch 2. Identifying what scripts, references, and assets would be helpful when executing these workflows repeatedly Example: When building a `pdf-editor` skill to handle queries like "Help me rotate this PDF," the analysis shows: 1. Rotating a PDF requires re-writing the same code each time 2. A `scripts/rotate_pdf.py` script would be helpful to store in the skill Example: When designing a `frontend-webapp-builder` skill for queries like "Build me a todo app" or "Build me a dashboard to track my steps," the analysis shows: 1. Writing a frontend webapp requires the same boilerplate HTML/React each time 2. An `assets/hello-world/` template containing the boilerplate HTML/React project files would be helpful to store in the skill Example: When building a `big-query` skill to handle queries like "How many users have logged in today?" the analysis shows: 1. Querying BigQuery requires re-discovering the table schemas and relationships each time 2. A `references/schema.md` file documenting the table schemas would be helpful to store in the skill To establish the skill's contents, analyze each concrete example to create a list of the reusable resources to include: scripts, references, and assets. ### Step 3: Initializing the Skill At this point, it is time to actually create the skill. Skip this step only if the skill being developed already exists, and iteration or packaging is needed. In this case, continue to the next step. When creating a new skill from scratch, always run the `init_skill.py` script. The script conveniently generates a new template skill directory that automatically includes everything a skill requires, making the skill creation process much more efficient and reliable. Usage: ```bash scripts/init_skill.py <skill-name> --path <output-directory> ``` The script: - Creates the skill directory at the specified path - Generates a SKILL.md template with proper frontmatter and TODO placeholders - Creates example resource directories: `scripts/`, `references/`, and `assets/` - Adds example files in each directory that can be customized or deleted After initialization, customize or remove the generated SKILL.md and example files as needed. ### Step 4: Edit the Skill When editing the (newly-generated or existing) skill, remember that the skill is being created for another instance of Claude to use. Focus on including information that would be beneficial and non-obvious to Claude. Consider what procedural knowledge, domain-specific details, or reusable assets would help another Claude instance execute these tasks more effectively. #### Start with Reusable Skill Contents To begin implementation, start with the reusable resources identified above: `scripts/`, `references/`, and `assets/` files. Note that this step may require user input. For example, when implementing a `brand-guidelines` skill, the user may need to provide brand assets or templates to store in `assets/`, or documentation to store in `references/`. Also, delete any example files and directories not needed for the skill. The initialization script creates example files in `scripts/`, `references/`, and `assets/` to demonstrate structure, but most skills won't need all of them. #### Update SKILL.md **Writing Style:** Write the entire skill using **imperative/infinitive form** (verb-first instructions), not second person. Use objective, instructional language (e.g., "To accomplish X, do Y" rather than "You should do X" or "If you need to do X"). This maintains consistency and clarity for AI consumption. To complete SKILL.md, answer the following questions: 1. What is the purpose of the skill, in a few sentences? 2. When should the skill be used? 3. In practice, how should Claude use the skill? All reusable skill contents developed above should be referenced so that Claude knows how to use them. ### Step 5: Packaging a Skill Once the skill is ready, it should be packaged into a distributable zip file that gets shared with the user. The packaging process automatically validates the skill first to ensure it meets all requirements: ```bash scripts/package_skill.py <path/to/skill-folder> ``` Optional output directory specification: ```bash scripts/package_skill.py <path/to/skill-folder> ./dist ``` The packaging script will: 1. **Validate** the skill automatically, checking: - YAML frontmatter format and required fields - Skill naming conventions and directory structure - Description completeness and quality - File organization and resource references 2. **Package** the skill if validation passes, creating a zip file named after the skill (e.g., `my-skill.zip`) that includes all files and maintains the proper directory structure for distribution. If validation fails, the script will report the errors and exit without creating a package. Fix any validation errors and run the packaging command again. ### Step 6: Iterate After testing the skill, users may request improvements. Often this happens right after using the skill, with fresh context of how the skill performed. **Iteration workflow:** 1. Use the skill on real tasks 2. Notice struggles or inefficiencies 3. Identify how SKILL.md or bundled resources should be updated 4. Implement changes and test again
Skill Creator
# Skill Creator This skill provides guidance for creating effective skills. ## About Skills Skills are modular, self-contained packages that extend Claude's capabilities by providing specialized knowledge, workflows, and tools. Think of them as "onboarding guides" for specific domains or tasks—they transform Claude from a general-purpose agent into a specialized agent equipped with procedural knowledge that no model can fully possess. ### What Skills Provide 1. Specialized workflows - Multi-step procedures for specific domains 2. Tool integrations - Instructions for working with specific file formats or APIs 3. Domain expertise - Company-specific knowledge, schemas, business logic 4. Bundled resources - Scripts, references, and assets for complex and repetitive tasks ### Anatomy of a Skill Every skill consists of a required SKILL.md file and optional bundled resources: ``` skill-name/ ├── SKILL.md (required) │ ├── YAML frontmatter metadata (required) │ │ ├── name: (required) │ │ └── description: (required) │ └── Markdown instructions (required) └── Bundled Resources (optional) ├── scripts/ - Executable code (Python/Bash/etc.) ├── references/ - Documentation intended to be loaded into context as needed └── assets/ - Files used in output (templates, icons, fonts, etc.) ``` #### SKILL.md (required) **Metadata Quality:** The `name` and `description` in YAML frontmatter determine when Claude will use the skill. Be specific about what the skill does and when to use it. Use the third-person (e.g. "This skill should be used when..." instead of "Use this skill when..."). #### Bundled Resources (optional) ##### Scripts (`scripts/`) Executable code (Python/Bash/etc.) for tasks that require deterministic reliability or are repeatedly rewritten. - **When to include**: When the same code is being rewritten repeatedly or deterministic reliability is needed - **Example**: `scripts/rotate_pdf.py` for PDF rotation tasks - **Benefits**: Token efficient, deterministic, may be executed without loading into context - **Note**: Scripts may still need to be read by Claude for patching or environment-specific adjustments ##### References (`references/`) Documentation and reference material intended to be loaded as needed into context to inform Claude's process and thinking. - **When to include**: For documentation that Claude should reference while working - **Examples**: `references/finance.md` for financial schemas, `references/mnda.md` for company NDA template, `references/policies.md` for company policies, `references/api_docs.md` for API specifications - **Use cases**: Database schemas, API documentation, domain knowledge, company policies, detailed workflow guides - **Benefits**: Keeps SKILL.md lean, loaded only when Claude determines it's needed - **Best practice**: If files are large (>10k words), include grep search patterns in SKILL.md - **Avoid duplication**: Information should live in either SKILL.md or references files, not both. Prefer references files for detailed information unless it's truly core to the skill—this keeps SKILL.md lean while making information discoverable without hogging the context window. Keep only essential procedural instructions and workflow guidance in SKILL.md; move detailed reference material, schemas, and examples to references files. ##### Assets (`assets/`) Files not intended to be loaded into context, but rather used within the output Claude produces. - **When to include**: When the skill needs files that will be used in the final output - **Examples**: `assets/logo.png` for brand assets, `assets/slides.pptx` for PowerPoint templates, `assets/frontend-template/` for HTML/React boilerplate, `assets/font.ttf` for typography - **Use cases**: Templates, images, icons, boilerplate code, fonts, sample documents that get copied or modified - **Benefits**: Separates output resources from documentation, enables Claude to use files without loading them into context ### Progressive Disclosure Design Principle Skills use a three-level loading system to manage context efficiently: 1. **Metadata (name + description)** - Always in context (~100 words) 2. **SKILL.md body** - When skill triggers (<5k words) 3. **Bundled resources** - As needed by Claude (Unlimited*) *Unlimited because scripts can be executed without reading into context window. ## Skill Creation Process To create a skill, follow the "Skill Creation Process" in order, skipping steps only if there is a clear reason why they are not applicable. ### Step 1: Understanding the Skill with Concrete Examples Skip this step only when the skill's usage patterns are already clearly understood. It remains valuable even when working with an existing skill. To create an effective skill, clearly understand concrete examples of how the skill will be used. This understanding can come from either direct user examples or generated examples that are validated with user feedback. For example, when building an image-editor skill, relevant questions include: - "What functionality should the image-editor skill support? Editing, rotating, anything else?" - "Can you give some examples of how this skill would be used?" - "I can imagine users asking for things like 'Remove the red-eye from this image' or 'Rotate this image'. Are there other ways you imagine this skill being used?" - "What would a user say that should trigger this skill?" To avoid overwhelming users, avoid asking too many questions in a single message. Start with the most important questions and follow up as needed for better effectiveness. Conclude this step when there is a clear sense of the functionality the skill should support. ### Step 2: Planning the Reusable Skill Contents To turn concrete examples into an effective skill, analyze each example by: 1. Considering how to execute on the example from scratch 2. Identifying what scripts, references, and assets would be helpful when executing these workflows repeatedly Example: When building a `pdf-editor` skill to handle queries like "Help me rotate this PDF," the analysis shows: 1. Rotating a PDF requires re-writing the same code each time 2. A `scripts/rotate_pdf.py` script would be helpful to store in the skill Example: When designing a `frontend-webapp-builder` skill for queries like "Build me a todo app" or "Build me a dashboard to track my steps," the analysis shows: 1. Writing a frontend webapp requires the same boilerplate HTML/React each time 2. An `assets/hello-world/` template containing the boilerplate HTML/React project files would be helpful to store in the skill Example: When building a `big-query` skill to handle queries like "How many users have logged in today?" the analysis shows: 1. Querying BigQuery requires re-discovering the table schemas and relationships each time 2. A `references/schema.md` file documenting the table schemas would be helpful to store in the skill To establish the skill's contents, analyze each concrete example to create a list of the reusable resources to include: scripts, references, and assets. ### Step 3: Initializing the Skill At this point, it is time to actually create the skill. Skip this step only if the skill being developed already exists, and iteration or packaging is needed. In this case, continue to the next step. When creating a new skill from scratch, always run the `init_skill.py` script. The script conveniently generates a new template skill directory that automatically includes everything a skill requires, making the skill creation process much more efficient and reliable. Usage: ```bash scripts/init_skill.py <skill-name> --path <output-directory> ``` The script: - Creates the skill directory at the specified path - Generates a SKILL.md template with proper frontmatter and TODO placeholders - Creates example resource directories: `scripts/`, `references/`, and `assets/` - Adds example files in each directory that can be customized or deleted After initialization, customize or remove the generated SKILL.md and example files as needed. ### Step 4: Edit the Skill When editing the (newly-generated or existing) skill, remember that the skill is being created for another instance of Claude to use. Focus on including information that would be beneficial and non-obvious to Claude. Consider what procedural knowledge, domain-specific details, or reusable assets would help another Claude instance execute these tasks more effectively. #### Start with Reusable Skill Contents To begin implementation, start with the reusable resources identified above: `scripts/`, `references/`, and `assets/` files. Note that this step may require user input. For example, when implementing a `brand-guidelines` skill, the user may need to provide brand assets or templates to store in `assets/`, or documentation to store in `references/`. Also, delete any example files and directories not needed for the skill. The initialization script creates example files in `scripts/`, `references/`, and `assets/` to demonstrate structure, but most skills won't need all of them. #### Update SKILL.md **Writing Style:** Write the entire skill using **imperative/infinitive form** (verb-first instructions), not second person. Use objective, instructional language (e.g., "To accomplish X, do Y" rather than "You should do X" or "If you need to do X"). This maintains consistency and clarity for AI consumption. To complete SKILL.md, answer the following questions: 1. What is the purpose of the skill, in a few sentences? 2. When should the skill be used? 3. In practice, how should Claude use the skill? All reusable skill contents developed above should be referenced so that Claude knows how to use them. ### Step 5: Packaging a Skill Once the skill is ready, it should be packaged into a distributable zip file that gets shared with the user. The packaging process automatically validates the skill first to ensure it meets all requirements: ```bash scripts/package_skill.py <path/to/skill-folder> ``` Optional output directory specification: ```bash scripts/package_skill.py <path/to/skill-folder> ./dist ``` The packaging script will: 1. **Validate** the skill automatically, checking: - YAML frontmatter format and required fields - Skill naming conventions and directory structure - Description completeness and quality - File organization and resource references 2. **Package** the skill if validation passes, creating a zip file named after the skill (e.g., `my-skill.zip`) that includes all files and maintains the proper directory structure for distribution. If validation fails, the script will report the errors and exit without creating a package. Fix any validation errors and run the packaging command again. ### Step 6: Iterate After testing the skill, users may request improvements. Often this happens right after using the skill, with fresh context of how the skill performed. **Iteration workflow:** 1. Use the skill on real tasks 2. Notice struggles or inefficiencies 3. Identify how SKILL.md or bundled resources should be updated 4. Implement changes and test again
Skill Creator
# Skill Creator This skill provides guidance for creating effective skills. ## About Skills Skills are modular, self-contained packages that extend Claude's capabilities by providing specialized knowledge, workflows, and tools. Think of them as "onboarding guides" for specific domains or tasks—they transform Claude from a general-purpose agent into a specialized agent equipped with procedural knowledge that no model can fully possess. ### What Skills Provide 1. Specialized workflows - Multi-step procedures for specific domains 2. Tool integrations - Instructions for working with specific file formats or APIs 3. Domain expertise - Company-specific knowledge, schemas, business logic 4. Bundled resources - Scripts, references, and assets for complex and repetitive tasks ### Anatomy of a Skill Every skill consists of a required SKILL.md file and optional bundled resources: ``` skill-name/ ├── SKILL.md (required) │ ├── YAML frontmatter metadata (required) │ │ ├── name: (required) │ │ └── description: (required) │ └── Markdown instructions (required) └── Bundled Resources (optional) ├── scripts/ - Executable code (Python/Bash/etc.) ├── references/ - Documentation intended to be loaded into context as needed └── assets/ - Files used in output (templates, icons, fonts, etc.) ``` #### SKILL.md (required) **Metadata Quality:** The `name` and `description` in YAML frontmatter determine when Claude will use the skill. Be specific about what the skill does and when to use it. Use the third-person (e.g. "This skill should be used when..." instead of "Use this skill when..."). #### Bundled Resources (optional) ##### Scripts (`scripts/`) Executable code (Python/Bash/etc.) for tasks that require deterministic reliability or are repeatedly rewritten. - **When to include**: When the same code is being rewritten repeatedly or deterministic reliability is needed - **Example**: `scripts/rotate_pdf.py` for PDF rotation tasks - **Benefits**: Token efficient, deterministic, may be executed without loading into context - **Note**: Scripts may still need to be read by Claude for patching or environment-specific adjustments ##### References (`references/`) Documentation and reference material intended to be loaded as needed into context to inform Claude's process and thinking. - **When to include**: For documentation that Claude should reference while working - **Examples**: `references/finance.md` for financial schemas, `references/mnda.md` for company NDA template, `references/policies.md` for company policies, `references/api_docs.md` for API specifications - **Use cases**: Database schemas, API documentation, domain knowledge, company policies, detailed workflow guides - **Benefits**: Keeps SKILL.md lean, loaded only when Claude determines it's needed - **Best practice**: If files are large (>10k words), include grep search patterns in SKILL.md - **Avoid duplication**: Information should live in either SKILL.md or references files, not both. Prefer references files for detailed information unless it's truly core to the skill—this keeps SKILL.md lean while making information discoverable without hogging the context window. Keep only essential procedural instructions and workflow guidance in SKILL.md; move detailed reference material, schemas, and examples to references files. ##### Assets (`assets/`) Files not intended to be loaded into context, but rather used within the output Claude produces. - **When to include**: When the skill needs files that will be used in the final output - **Examples**: `assets/logo.png` for brand assets, `assets/slides.pptx` for PowerPoint templates, `assets/frontend-template/` for HTML/React boilerplate, `assets/font.ttf` for typography - **Use cases**: Templates, images, icons, boilerplate code, fonts, sample documents that get copied or modified - **Benefits**: Separates output resources from documentation, enables Claude to use files without loading them into context ### Progressive Disclosure Design Principle Skills use a three-level loading system to manage context efficiently: 1. **Metadata (name + description)** - Always in context (~100 words) 2. **SKILL.md body** - When skill triggers (<5k words) 3. **Bundled resources** - As needed by Claude (Unlimited*) *Unlimited because scripts can be executed without reading into context window. ## Skill Creation Process To create a skill, follow the "Skill Creation Process" in order, skipping steps only if there is a clear reason why they are not applicable. ### Step 1: Understanding the Skill with Concrete Examples Skip this step only when the skill's usage patterns are already clearly understood. It remains valuable even when working with an existing skill. To create an effective skill, clearly understand concrete examples of how the skill will be used. This understanding can come from either direct user examples or generated examples that are validated with user feedback. For example, when building an image-editor skill, relevant questions include: - "What functionality should the image-editor skill support? Editing, rotating, anything else?" - "Can you give some examples of how this skill would be used?" - "I can imagine users asking for things like 'Remove the red-eye from this image' or 'Rotate this image'. Are there other ways you imagine this skill being used?" - "What would a user say that should trigger this skill?" To avoid overwhelming users, avoid asking too many questions in a single message. Start with the most important questions and follow up as needed for better effectiveness. Conclude this step when there is a clear sense of the functionality the skill should support. ### Step 2: Planning the Reusable Skill Contents To turn concrete examples into an effective skill, analyze each example by: 1. Considering how to execute on the example from scratch 2. Identifying what scripts, references, and assets would be helpful when executing these workflows repeatedly Example: When building a `pdf-editor` skill to handle queries like "Help me rotate this PDF," the analysis shows: 1. Rotating a PDF requires re-writing the same code each time 2. A `scripts/rotate_pdf.py` script would be helpful to store in the skill Example: When designing a `frontend-webapp-builder` skill for queries like "Build me a todo app" or "Build me a dashboard to track my steps," the analysis shows: 1. Writing a frontend webapp requires the same boilerplate HTML/React each time 2. An `assets/hello-world/` template containing the boilerplate HTML/React project files would be helpful to store in the skill Example: When building a `big-query` skill to handle queries like "How many users have logged in today?" the analysis shows: 1. Querying BigQuery requires re-discovering the table schemas and relationships each time 2. A `references/schema.md` file documenting the table schemas would be helpful to store in the skill To establish the skill's contents, analyze each concrete example to create a list of the reusable resources to include: scripts, references, and assets. ### Step 3: Initializing the Skill At this point, it is time to actually create the skill. Skip this step only if the skill being developed already exists, and iteration or packaging is needed. In this case, continue to the next step. When creating a new skill from scratch, always run the `init_skill.py` script. The script conveniently generates a new template skill directory that automatically includes everything a skill requires, making the skill creation process much more efficient and reliable. Usage: ```bash scripts/init_skill.py <skill-name> --path <output-directory> ``` The script: - Creates the skill directory at the specified path - Generates a SKILL.md template with proper frontmatter and TODO placeholders - Creates example resource directories: `scripts/`, `references/`, and `assets/` - Adds example files in each directory that can be customized or deleted After initialization, customize or remove the generated SKILL.md and example files as needed. ### Step 4: Edit the Skill When editing the (newly-generated or existing) skill, remember that the skill is being created for another instance of Claude to use. Focus on including information that would be beneficial and non-obvious to Claude. Consider what procedural knowledge, domain-specific details, or reusable assets would help another Claude instance execute these tasks more effectively. #### Start with Reusable Skill Contents To begin implementation, start with the reusable resources identified above: `scripts/`, `references/`, and `assets/` files. Note that this step may require user input. For example, when implementing a `brand-guidelines` skill, the user may need to provide brand assets or templates to store in `assets/`, or documentation to store in `references/`. Also, delete any example files and directories not needed for the skill. The initialization script creates example files in `scripts/`, `references/`, and `assets/` to demonstrate structure, but most skills won't need all of them. #### Update SKILL.md **Writing Style:** Write the entire skill using **imperative/infinitive form** (verb-first instructions), not second person. Use objective, instructional language (e.g., "To accomplish X, do Y" rather than "You should do X" or "If you need to do X"). This maintains consistency and clarity for AI consumption. To complete SKILL.md, answer the following questions: 1. What is the purpose of the skill, in a few sentences? 2. When should the skill be used? 3. In practice, how should Claude use the skill? All reusable skill contents developed above should be referenced so that Claude knows how to use them. ### Step 5: Packaging a Skill Once the skill is ready, it should be packaged into a distributable zip file that gets shared with the user. The packaging process automatically validates the skill first to ensure it meets all requirements: ```bash scripts/package_skill.py <path/to/skill-folder> ``` Optional output directory specification: ```bash scripts/package_skill.py <path/to/skill-folder> ./dist ``` The packaging script will: 1. **Validate** the skill automatically, checking: - YAML frontmatter format and required fields - Skill naming conventions and directory structure - Description completeness and quality - File organization and resource references 2. **Package** the skill if validation passes, creating a zip file named after the skill (e.g., `my-skill.zip`) that includes all files and maintains the proper directory structure for distribution. If validation fails, the script will report the errors and exit without creating a package. Fix any validation errors and run the packaging command again. ### Step 6: Iterate After testing the skill, users may request improvements. Often this happens right after using the skill, with fresh context of how the skill performed. **Iteration workflow:** 1. Use the skill on real tasks 2. Notice struggles or inefficiencies 3. Identify how SKILL.md or bundled resources should be updated 4. Implement changes and test again
MCP Server Development Guide
# MCP Server Development Guide ## Overview To create high-quality MCP (Model Context Protocol) servers that enable LLMs to effectively interact with external services, use this skill. An MCP server provides tools that allow LLMs to access external services and APIs. The quality of an MCP server is measured by how well it enables LLMs to accomplish real-world tasks using the tools provided. --- # Process ## 🚀 High-Level Workflow Creating a high-quality MCP server involves four main phases: ### Phase 1: Deep Research and Planning #### 1.1 Understand Agent-Centric Design Principles Before diving into implementation, understand how to design tools for AI agents by reviewing these principles: **Build for Workflows, Not Just API Endpoints:** - Don't simply wrap existing API endpoints - build thoughtful, high-impact workflow tools - Consolidate related operations (e.g., `schedule_event` that both checks availability and creates event) - Focus on tools that enable complete tasks, not just individual API calls - Consider what workflows agents actually need to accomplish **Optimize for Limited Context:** - Agents have constrained context windows - make every token count - Return high-signal information, not exhaustive data dumps - Provide "concise" vs "detailed" response format options - Default to human-readable identifiers over technical codes (names over IDs) - Consider the agent's context budget as a scarce resource **Design Actionable Error Messages:** - Error messages should guide agents toward correct usage patterns - Suggest specific next steps: "Try using filter='active_only' to reduce results" - Make errors educational, not just diagnostic - Help agents learn proper tool usage through clear feedback **Follow Natural Task Subdivisions:** - Tool names should reflect how humans think about tasks - Group related tools with consistent prefixes for discoverability - Design tools around natural workflows, not just API structure **Use Evaluation-Driven Development:** - Create realistic evaluation scenarios early - Let agent feedback drive tool improvements - Prototype quickly and iterate based on actual agent performance #### 1.3 Study MCP Protocol Documentation **Fetch the latest MCP protocol documentation:** Use WebFetch to load: `https://modelcontextprotocol.io/llms-full.txt` This comprehensive document contains the complete MCP specification and guidelines. #### 1.4 Study Framework Documentation **Load and read the following reference files:** - **MCP Best Practices**: [📋 View Best Practices](./reference/mcp_best_practices.md) - Core guidelines for all MCP servers **For Python implementations, also load:** - **Python SDK Documentation**: Use WebFetch to load `https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md` - [🐍 Python Implementation Guide](./reference/python_mcp_server.md) - Python-specific best practices and examples **For Node/TypeScript implementations, also load:** - **TypeScript SDK Documentation**: Use WebFetch to load `https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md` - [⚡ TypeScript Implementation Guide](./reference/node_mcp_server.md) - Node/TypeScript-specific best practices and examples #### 1.5 Exhaustively Study API Documentation To integrate a service, read through **ALL** available API documentation: - Official API reference documentation - Authentication and authorization requirements - Rate limiting and pagination patterns - Error responses and status codes - Available endpoints and their parameters - Data models and schemas **To gather comprehensive information, use web search and the WebFetch tool as needed.** #### 1.6 Create a Comprehensive Implementation Plan Based on your research, create a detailed plan that includes: **Tool Selection:** - List the most valuable endpoints/operations to implement - Prioritize tools that enable the most common and important use cases - Consider which tools work together to enable complex workflows **Shared Utilities and Helpers:** - Identify common API request patterns - Plan pagination helpers - Design filtering and formatting utilities - Plan error handling strategies **Input/Output Design:** - Define input validation models (Pydantic for Python, Zod for TypeScript) - Design consistent response formats (e.g., JSON or Markdown), and configurable levels of detail (e.g., Detailed or Concise) - Plan for large-scale usage (thousands of users/resources) - Implement character limits and truncation strategies (e.g., 25,000 tokens) **Error Handling Strategy:** - Plan graceful failure modes - Design clear, actionable, LLM-friendly, natural language error messages which prompt further action - Consider rate limiting and timeout scenarios - Handle authentication and authorization errors --- ### Phase 2: Implementation Now that you have a comprehensive plan, begin implementation following language-specific best practices. #### 2.1 Set Up Project Structure **For Python:** - Create a single `.py` file or organize into modules if complex (see [🐍 Python Guide](./reference/python_mcp_server.md)) - Use the MCP Python SDK for tool registration - Define Pydantic models for input validation **For Node/TypeScript:** - Create proper project structure (see [⚡ TypeScript Guide](./reference/node_mcp_server.md)) - Set up `package.json` and `tsconfig.json` - Use MCP TypeScript SDK - Define Zod schemas for input validation #### 2.2 Implement Core Infrastructure First **To begin implementation, create shared utilities before implementing tools:** - API request helper functions - Error handling utilities - Response formatting functions (JSON and Markdown) - Pagination helpers - Authentication/token management #### 2.3 Implement Tools Systematically For each tool in the plan: **Define Input Schema:** - Use Pydantic (Python) or Zod (TypeScript) for validation - Include proper constraints (min/max length, regex patterns, min/max values, ranges) - Provide clear, descriptive field descriptions - Include diverse examples in field descriptions **Write Comprehensive Docstrings/Descriptions:** - One-line summary of what the tool does - Detailed explanation of purpose and functionality - Explicit parameter types with examples - Complete return type schema - Usage examples (when to use, when not to use) - Error handling documentation, which outlines how to proceed given specific errors **Implement Tool Logic:** - Use shared utilities to avoid code duplication - Follow async/await patterns for all I/O - Implement proper error handling - Support multiple response formats (JSON and Markdown) - Respect pagination parameters - Check character limits and truncate appropriately **Add Tool Annotations:** - `readOnlyHint`: true (for read-only operations) - `destructiveHint`: false (for non-destructive operations) - `idempotentHint`: true (if repeated calls have same effect) - `openWorldHint`: true (if interacting with external systems) #### 2.4 Follow Language-Specific Best Practices **At this point, load the appropriate language guide:** **For Python: Load [🐍 Python Implementation Guide](./reference/python_mcp_server.md) and ensure the following:** - Using MCP Python SDK with proper tool registration - Pydantic v2 models with `model_config` - Type hints throughout - Async/await for all I/O operations - Proper imports organization - Module-level constants (CHARACTER_LIMIT, API_BASE_URL) **For Node/TypeScript: Load [⚡ TypeScript Implementation Guide](./reference/node_mcp_server.md) and ensure the following:** - Using `server.registerTool` properly - Zod schemas with `.strict()` - TypeScript strict mode enabled - No `any` types - use proper types - Explicit Promise<T> return types - Build process configured (`npm run build`) --- ### Phase 3: Review and Refine After initial implementation: #### 3.1 Code Quality Review To ensure quality, review the code for: - **DRY Principle**: No duplicated code between tools - **Composability**: Shared logic extracted into functions - **Consistency**: Similar operations return similar formats - **Error Handling**: All external calls have error handling - **Type Safety**: Full type coverage (Python type hints, TypeScript types) - **Documentation**: Every tool has comprehensive docstrings/descriptions #### 3.2 Test and Build **Important:** MCP servers are long-running processes that wait for requests over stdio/stdin or sse/http. Running them directly in your main process (e.g., `python server.py` or `node dist/index.js`) will cause your process to hang indefinitely. **Safe ways to test the server:** - Use the evaluation harness (see Phase 4) - recommended approach - Run the server in tmux to keep it outside your main process - Use a timeout when testing: `timeout 5s python server.py` **For Python:** - Verify Python syntax: `python -m py_compile your_server.py` - Check imports work correctly by reviewing the file - To manually test: Run server in tmux, then test with evaluation harness in main process - Or use the evaluation harness directly (it manages the server for stdio transport) **For Node/TypeScript:** - Run `npm run build` and ensure it completes without errors - Verify dist/index.js is created - To manually test: Run server in tmux, then test with evaluation harness in main process - Or use the evaluation harness directly (it manages the server for stdio transport) #### 3.3 Use Quality Checklist To verify implementation quality, load the appropriate checklist from the language-specific guide: - Python: see "Quality Checklist" in [🐍 Python Guide](./reference/python_mcp_server.md) - Node/TypeScript: see "Quality Checklist" in [⚡ TypeScript Guide](./reference/node_mcp_server.md) --- ### Phase 4: Create Evaluations After implementing your MCP server, create comprehensive evaluations to test its effectiveness. **Load [✅ Evaluation Guide](./reference/evaluation.md) for complete evaluation guidelines.** #### 4.1 Understand Evaluation Purpose Evaluations test whether LLMs can effectively use your MCP server to answer realistic, complex questions. #### 4.2 Create 10 Evaluation Questions To create effective evaluations, follow the process outlined in the evaluation guide: 1. **Tool Inspection**: List available tools and understand their capabilities 2. **Content Exploration**: Use READ-ONLY operations to explore available data 3. **Question Generation**: Create 10 complex, realistic questions 4. **Answer Verification**: Solve each question yourself to verify answers #### 4.3 Evaluation Requirements Each question must be: - **Independent**: Not dependent on other questions - **Read-only**: Only non-destructive operations required - **Complex**: Requiring multiple tool calls and deep exploration - **Realistic**: Based on real use cases humans would care about - **Verifiable**: Single, clear answer that can be verified by string comparison - **Stable**: Answer won't change over time #### 4.4 Output Format Create an XML file with this structure: ```xml <evaluation> <qa_pair> <question>Find discussions about AI model launches with animal codenames. One model needed a specific safety designation that uses the format ASL-X. What number X was being determined for the model named after a spotted wild cat?</question> <answer>3</answer> </qa_pair> <!-- More qa_pairs... --> </evaluation> ``` --- # Reference Files ## 📚 Documentation Library Load these resources as needed during development: ### Core MCP Documentation (Load First) - **MCP Protocol**: Fetch from `https://modelcontextprotocol.io/llms-full.txt` - Complete MCP specification - [📋 MCP Best Practices](./reference/mcp_best_practices.md) - Universal MCP guidelines including: - Server and tool naming conventions - Response format guidelines (JSON vs Markdown) - Pagination best practices - Character limits and truncation strategies - Tool development guidelines - Security and error handling standards ### SDK Documentation (Load During Phase 1/2) - **Python SDK**: Fetch from `https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md` - **TypeScript SDK**: Fetch from `https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md` ### Language-Specific Implementation Guides (Load During Phase 2) - [🐍 Python Implementation Guide](./reference/python_mcp_server.md) - Complete Python/FastMCP guide with: - Server initialization patterns - Pydantic model examples - Tool registration with `@mcp.tool` - Complete working examples - Quality checklist - [⚡ TypeScript Implementation Guide](./reference/node_mcp_server.md) - Complete TypeScript guide with: - Project structure - Zod schema patterns - Tool registration with `server.registerTool` - Complete working examples - Quality checklist ### Evaluation Guide (Load During Phase 4) - [✅ Evaluation Guide](./reference/evaluation.md) - Complete evaluation creation guide with: - Question creation guidelines - Answer verification strategies - XML format specifications - Example questions and answers - Running an evaluation with the provided scripts
mcp-builder
# MCP Server Development Guide ## Overview To create high-quality MCP (Model Context Protocol) servers that enable LLMs to effectively interact with external services, use this skill. An MCP server provides tools that allow LLMs to access external services and APIs. The quality of an MCP server is measured by how well it enables LLMs to accomplish real-world tasks using the tools provided. --- # Process ## 🚀 High-Level Workflow Creating a high-quality MCP server involves four main phases: ### Phase 1: Deep Research and Planning #### 1.1 Understand Agent-Centric Design Principles Before diving into implementation, understand how to design tools for AI agents by reviewing these principles: **Build for Workflows, Not Just API Endpoints:** - Don't simply wrap existing API endpoints - build thoughtful, high-impact workflow tools - Consolidate related operations (e.g., `schedule_event` that both checks availability and creates event) - Focus on tools that enable complete tasks, not just individual API calls - Consider what workflows agents actually need to accomplish **Optimize for Limited Context:** - Agents have constrained context windows - make every token count - Return high-signal information, not exhaustive data dumps - Provide "concise" vs "detailed" response format options - Default to human-readable identifiers over technical codes (names over IDs) - Consider the agent's context budget as a scarce resource **Design Actionable Error Messages:** - Error messages should guide agents toward correct usage patterns - Suggest specific next steps: "Try using filter='active_only' to reduce results" - Make errors educational, not just diagnostic - Help agents learn proper tool usage through clear feedback **Follow Natural Task Subdivisions:** - Tool names should reflect how humans think about tasks - Group related tools with consistent prefixes for discoverability - Design tools around natural workflows, not just API structure **Use Evaluation-Driven Development:** - Create realistic evaluation scenarios early - Let agent feedback drive tool improvements - Prototype quickly and iterate based on actual agent performance #### 1.3 Study MCP Protocol Documentation **Fetch the latest MCP protocol documentation:** Use WebFetch to load: `https://modelcontextprotocol.io/llms-full.txt` This comprehensive document contains the complete MCP specification and guidelines. #### 1.4 Study Framework Documentation **Load and read the following reference files:** - **MCP Best Practices**: [📋 View Best Practices](./reference/mcp_best_practices.md) - Core guidelines for all MCP servers **For Python implementations, also load:** - **Python SDK Documentation**: Use WebFetch to load `https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md` - [🐍 Python Implementation Guide](./reference/python_mcp_server.md) - Python-specific best practices and examples **For Node/TypeScript implementations, also load:** - **TypeScript SDK Documentation**: Use WebFetch to load `https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md` - [⚡ TypeScript Implementation Guide](./reference/node_mcp_server.md) - Node/TypeScript-specific best practices and examples #### 1.5 Exhaustively Study API Documentation To integrate a service, read through **ALL** available API documentation: - Official API reference documentation - Authentication and authorization requirements - Rate limiting and pagination patterns - Error responses and status codes - Available endpoints and their parameters - Data models and schemas **To gather comprehensive information, use web search and the WebFetch tool as needed.** #### 1.6 Create a Comprehensive Implementation Plan Based on your research, create a detailed plan that includes: **Tool Selection:** - List the most valuable endpoints/operations to implement - Prioritize tools that enable the most common and important use cases - Consider which tools work together to enable complex workflows **Shared Utilities and Helpers:** - Identify common API request patterns - Plan pagination helpers - Design filtering and formatting utilities - Plan error handling strategies **Input/Output Design:** - Define input validation models (Pydantic for Python, Zod for TypeScript) - Design consistent response formats (e.g., JSON or Markdown), and configurable levels of detail (e.g., Detailed or Concise) - Plan for large-scale usage (thousands of users/resources) - Implement character limits and truncation strategies (e.g., 25,000 tokens) **Error Handling Strategy:** - Plan graceful failure modes - Design clear, actionable, LLM-friendly, natural language error messages which prompt further action - Consider rate limiting and timeout scenarios - Handle authentication and authorization errors --- ### Phase 2: Implementation Now that you have a comprehensive plan, begin implementation following language-specific best practices. #### 2.1 Set Up Project Structure **For Python:** - Create a single `.py` file or organize into modules if complex (see [🐍 Python Guide](./reference/python_mcp_server.md)) - Use the MCP Python SDK for tool registration - Define Pydantic models for input validation **For Node/TypeScript:** - Create proper project structure (see [⚡ TypeScript Guide](./reference/node_mcp_server.md)) - Set up `package.json` and `tsconfig.json` - Use MCP TypeScript SDK - Define Zod schemas for input validation #### 2.2 Implement Core Infrastructure First **To begin implementation, create shared utilities before implementing tools:** - API request helper functions - Error handling utilities - Response formatting functions (JSON and Markdown) - Pagination helpers - Authentication/token management #### 2.3 Implement Tools Systematically For each tool in the plan: **Define Input Schema:** - Use Pydantic (Python) or Zod (TypeScript) for validation - Include proper constraints (min/max length, regex patterns, min/max values, ranges) - Provide clear, descriptive field descriptions - Include diverse examples in field descriptions **Write Comprehensive Docstrings/Descriptions:** - One-line summary of what the tool does - Detailed explanation of purpose and functionality - Explicit parameter types with examples - Complete return type schema - Usage examples (when to use, when not to use) - Error handling documentation, which outlines how to proceed given specific errors **Implement Tool Logic:** - Use shared utilities to avoid code duplication - Follow async/await patterns for all I/O - Implement proper error handling - Support multiple response formats (JSON and Markdown) - Respect pagination parameters - Check character limits and truncate appropriately **Add Tool Annotations:** - `readOnlyHint`: true (for read-only operations) - `destructiveHint`: false (for non-destructive operations) - `idempotentHint`: true (if repeated calls have same effect) - `openWorldHint`: true (if interacting with external systems) #### 2.4 Follow Language-Specific Best Practices **At this point, load the appropriate language guide:** **For Python: Load [🐍 Python Implementation Guide](./reference/python_mcp_server.md) and ensure the following:** - Using MCP Python SDK with proper tool registration - Pydantic v2 models with `model_config` - Type hints throughout - Async/await for all I/O operations - Proper imports organization - Module-level constants (CHARACTER_LIMIT, API_BASE_URL) **For Node/TypeScript: Load [⚡ TypeScript Implementation Guide](./reference/node_mcp_server.md) and ensure the following:** - Using `server.registerTool` properly - Zod schemas with `.strict()` - TypeScript strict mode enabled - No `any` types - use proper types - Explicit Promise<T> return types - Build process configured (`npm run build`) --- ### Phase 3: Review and Refine After initial implementation: #### 3.1 Code Quality Review To ensure quality, review the code for: - **DRY Principle**: No duplicated code between tools - **Composability**: Shared logic extracted into functions - **Consistency**: Similar operations return similar formats - **Error Handling**: All external calls have error handling - **Type Safety**: Full type coverage (Python type hints, TypeScript types) - **Documentation**: Every tool has comprehensive docstrings/descriptions #### 3.2 Test and Build **Important:** MCP servers are long-running processes that wait for requests over stdio/stdin or sse/http. Running them directly in your main process (e.g., `python server.py` or `node dist/index.js`) will cause your process to hang indefinitely. **Safe ways to test the server:** - Use the evaluation harness (see Phase 4) - recommended approach - Run the server in tmux to keep it outside your main process - Use a timeout when testing: `timeout 5s python server.py` **For Python:** - Verify Python syntax: `python -m py_compile your_server.py` - Check imports work correctly by reviewing the file - To manually test: Run server in tmux, then test with evaluation harness in main process - Or use the evaluation harness directly (it manages the server for stdio transport) **For Node/TypeScript:** - Run `npm run build` and ensure it completes without errors - Verify dist/index.js is created - To manually test: Run server in tmux, then test with evaluation harness in main process - Or use the evaluation harness directly (it manages the server for stdio transport) #### 3.3 Use Quality Checklist To verify implementation quality, load the appropriate checklist from the language-specific guide: - Python: see "Quality Checklist" in [🐍 Python Guide](./reference/python_mcp_server.md) - Node/TypeScript: see "Quality Checklist" in [⚡ TypeScript Guide](./reference/node_mcp_server.md) --- ### Phase 4: Create Evaluations After implementing your MCP server, create comprehensive evaluations to test its effectiveness. **Load [✅ Evaluation Guide](./reference/evaluation.md) for complete evaluation guidelines.** #### 4.1 Understand Evaluation Purpose Evaluations test whether LLMs can effectively use your MCP server to answer realistic, complex questions. #### 4.2 Create 10 Evaluation Questions To create effective evaluations, follow the process outlined in the evaluation guide: 1. **Tool Inspection**: List available tools and understand their capabilities 2. **Content Exploration**: Use READ-ONLY operations to explore available data 3. **Question Generation**: Create 10 complex, realistic questions 4. **Answer Verification**: Solve each question yourself to verify answers #### 4.3 Evaluation Requirements Each question must be: - **Independent**: Not dependent on other questions - **Read-only**: Only non-destructive operations required - **Complex**: Requiring multiple tool calls and deep exploration - **Realistic**: Based on real use cases humans would care about - **Verifiable**: Single, clear answer that can be verified by string comparison - **Stable**: Answer won't change over time #### 4.4 Output Format Create an XML file with this structure: ```xml <evaluation> <qa_pair> <question>Find discussions about AI model launches with animal codenames. One model needed a specific safety designation that uses the format ASL-X. What number X was being determined for the model named after a spotted wild cat?</question> <answer>3</answer> </qa_pair> <!-- More qa_pairs... --> </evaluation> ``` --- # Reference Files ## 📚 Documentation Library Load these resources as needed during development: ### Core MCP Documentation (Load First) - **MCP Protocol**: Fetch from `https://modelcontextprotocol.io/llms-full.txt` - Complete MCP specification - [📋 MCP Best Practices](./reference/mcp_best_practices.md) - Universal MCP guidelines including: - Server and tool naming conventions - Response format guidelines (JSON vs Markdown) - Pagination best practices - Character limits and truncation strategies - Tool development guidelines - Security and error handling standards ### SDK Documentation (Load During Phase 1/2) - **Python SDK**: Fetch from `https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md` - **TypeScript SDK**: Fetch from `https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md` ### Language-Specific Implementation Guides (Load During Phase 2) - [🐍 Python Implementation Guide](./reference/python_mcp_server.md) - Complete Python/FastMCP guide with: - Server initialization patterns - Pydantic model examples - Tool registration with `@mcp.tool` - Complete working examples - Quality checklist - [⚡ TypeScript Implementation Guide](./reference/node_mcp_server.md) - Complete TypeScript guide with: - Project structure - Zod schema patterns - Tool registration with `server.registerTool` - Complete working examples - Quality checklist ### Evaluation Guide (Load During Phase 4) - [✅ Evaluation Guide](./reference/evaluation.md) - Complete evaluation creation guide with: - Question creation guidelines - Answer verification strategies - XML format specifications - Example questions and answers - Running an evaluation with the provided scripts