### Git and npm commands for project setup

Source: https://github.com/haunchen/n8n-skills/blob/main/CONTRIBUTING.en.md

Use these commands to clone the repository, install dependencies, and verify the build and test status.

```bash
# Clone your fork
git clone https://github.com/YOUR_USERNAME/n8n-skill.git
cd n8n-skill

# Install dependencies
npm install

# Build project
npm run build

# Run tests
npm test
```

--------------------------------

### Node Configuration Example

Source: https://github.com/haunchen/n8n-skills/blob/main/docs/IMPLEMENTATION_PLAN.en.md

Example output for node detailed configuration, showing version, position, and parameters for specific nodes.

```markdown
### Example Chat (chatTrigger)
- Version: 1.1
- Position: (-176, -64)
- Parameters: public chat interface

### AI Agent (agent)
- Version: 2.2
- Position: (192, -64)
- Parameters: system message, tools
```

--------------------------------

### Install Development Dependencies

Source: https://github.com/haunchen/n8n-skills/blob/main/README.zh-TW.md

Command to install project dependencies for development.

```bash
npm install
```

--------------------------------

### Connection Relationships Example

Source: https://github.com/haunchen/n8n-skills/blob/main/docs/IMPLEMENTATION_PLAN.en.md

Example output detailing the connection relationships between workflow nodes.

```markdown
Example Chat → AI Agent (main)
Get Weather → AI Agent (ai_tool)
Get News → AI Agent (ai_tool)
```

--------------------------------

### Run in Development Mode

Source: https://github.com/haunchen/n8n-skills/blob/main/README.md

Starts the project in development mode, typically with hot-reloading and debugging capabilities.

```bash
npm run dev
```

--------------------------------

### Example Queries for n8n-skills

Source: https://github.com/haunchen/n8n-skills/blob/main/README.md

These are example natural language queries you can use with n8n-skills to get information about n8n nodes and workflows.

```plaintext
"What are the main features of the HTTP Request node?"
"How to send email using the Gmail node?"
"What programming languages does the Code node support?"
```

```plaintext
"How to create a scheduled workflow?"
"What are the common node combinations for data transformation?"
"How to handle API errors and retries?"
```

```plaintext
"Which nodes can connect to Google Sheets?"
"What AI-related nodes are available?"
"What trigger nodes are available?"
```

--------------------------------

### External Workflow Link Example

Source: https://github.com/haunchen/n8n-skills/blob/main/docs/API_RESEARCH_RESULTS.en.md

Provides an example of how to link to external n8n workflow definitions using markdown. This approach avoids embedding large JSON files directly.

```markdown
## Workflow Definition

Complete workflow definition available from:
- [View on n8n.io](https://n8n.io/workflows/6270)
- [Download JSON](https://api.n8n.io/api/workflows/templates/6270)
```

--------------------------------

### Retrieve Complete Workflow Template

Source: https://github.com/haunchen/n8n-skills/blob/main/docs/workflow-api-research.en.md

Endpoint and example command to fetch detailed workflow data by ID.

```text
GET https://api.n8n.io/api/workflows/templates/{id}
```

```bash
curl https://api.n8n.io/api/workflows/templates/6270
```

--------------------------------

### Install n8n Skills for Claude Code

Source: https://github.com/haunchen/n8n-skills/blob/main/README.zh-TW.md

Commands to create the required directory and copy the skill files for Claude Code CLI usage.

```bash
mkdir -p .claude/skills/n8n-skills
```

```bash
cp -r n8n-skills/* .claude/skills/n8n-skills/
```

--------------------------------

### Example Workflow JSON Data

Source: https://github.com/haunchen/n8n-skills/blob/main/docs/workflow-api-research.en.md

A sample JSON response for a complete workflow template.

```json
{
  "id": 6270,
  "name": "Build Your First AI Agent",
  "workflow": {
    "meta": {
      "instanceId": "e409ea34548a2afe2dffba31130cd1cf2e98ebe2afaeed2a63caf2a0582d1da0",
      "templateCredsSetupCompleted": true
    },
    "nodes": [
      {
        "id": "95421925-c5ad-48bd-9638-c84ff5b5e3c6",
        "name": "Example Chat",
        "type": "@n8n/n8n-nodes-langchain.chatTrigger",
        "position": [-176, -64],
        "parameters": {
          "public": true,
          "options": {
            "title": "Your first AI Agent 🚀",
            "subtitle": "This is for demo purposes. Try me out !"
          }
        },
        "typeVersion": 1.1
      },
      {
        "id": "332af12a-45ab-4e5d-8dab-da21ba2111f9",
        "name": "Your First AI Agent",
        "type": "@n8n/n8n-nodes-langchain.agent",
        "position": [192, -64],
        "parameters": {
          "options": {
            "systemMessage": "You are an AI assistant..."
          }
        },
        "typeVersion": 2.2
      }
    ],
    "connections": {
      "Example Chat": {
        "main": [
          [
            {
              "node": "Your First AI Agent",
              "type": "main",
              "index": 0
            }
          ]
        ]
      },
      "Get Weather": {
        "ai_tool": [
          [
            {
              "node": "Your First AI Agent",
              "type": "ai_tool",
              "index": 0
            }
          ]
        ]
      }
    }
  }
}
```

--------------------------------

### Mermaid Flowchart Example

Source: https://github.com/haunchen/n8n-skills/blob/main/docs/IMPLEMENTATION_PLAN.en.md

Example of a Mermaid flowchart generated from workflow data, illustrating node connections.

```mermaid
graph LR
  N0[Example Chat] --> N1[AI Agent]
  N2[Get Weather] -->|ai_tool| N1
  N3[Get News] -->|ai_tool| N1
```

--------------------------------

### Testing n8n Workflow API with cURL and jq

Source: https://github.com/haunchen/n8n-skills/blob/main/docs/API_RESEARCH_RESULTS.en.md

Examples demonstrating how to use cURL to fetch workflow data from the n8n API and jq to parse and extract specific information like the workflow name, node count, and connection keys.

```bash
# Test 1: Get workflow name
$ curl -s "https://api.n8n.io/api/workflows/templates/6270" | jq '.name'
"Build Your First AI Agent"
```

```bash
# Test 2: Count nodes
$ curl -s "https://api.n8n.io/api/workflows/templates/6270" | jq '.workflow.nodes | length'
13
```

```bash
# Test 3: View connection relationships
$ curl -s "https://api.n8n.io/api/workflows/templates/6270" | jq '.workflow.connections | keys'
[
  "Connect Gemini",
  "Conversation Memory",
  "Example Chat",
  "Get News",
  "Get Weather"
]
```

--------------------------------

### Generate Main SKILL.md File with SkillGenerator

Source: https://context7.com/haunchen/n8n-skills/llms.txt

Use SkillGenerator to create the main skill file, including YAML frontmatter, overview, and navigation. It also generates guide files for node discovery, usage, and workflow patterns. Requires SkillConfig and EnrichedNodeInfo for input.

```typescript
import { SkillGenerator, generateSkillMarkdown, generateSkillFile } from 'n8n-skills';
import type { SkillConfig, EnrichedNodeInfo, SkillGeneratorInput } from 'n8n-skills';

// Skill configuration
const config: SkillConfig = {
  name: 'n8n-skills',
  version: '1.2.0',
  description: 'Use when building n8n workflows. Keywords: n8n, workflow, automation.',
  author: 'Frank Chen',
  license: 'MIT',
  maxLines: 5000,
  topNodesCount: 50
};

const generator = new SkillGenerator(config);

// Enriched node data (from collectors + parsers + organizers)
const nodes: EnrichedNodeInfo[] = [
  {
    nodeType: 'nodes-base.httpRequest',
    displayName: 'HTTP Request',
    description: 'Makes HTTP requests',
    category: 'input',
    packageName: 'n8n-nodes-base',
    version: '4.2',
    usageCount: 487,
    usagePercentage: 12.34,
    score: 0.95,
    rank: 1,
    tier: 'essential',
    properties: {
      coreProperties: [/* ... */],
      operations: [/* ... */],
      hasCredentials: true,
      totalPropertyCount: 15
    }
  }
  // ... more nodes
];

// Generate main SKILL.md content
const input: SkillGeneratorInput = {
  nodes,
  nodeUsageStats: { 'nodes-base.httpRequest': { count: 487, percentage: 12.34 } },
  resourceFiles: [
    { name: 'HTTP Request', path: 'resources/input/nodes-base.httpRequest.md', description: '...', category: 'input' }
  ],
  config,
  templateCount: 20
};

const skillContent = generator.generate(input);
// Returns complete SKILL.md with frontmatter, sections, and navigation

// Generate guide files
const howToFindNodes = generator.generateHowToFindNodesFile(nodes, input.nodeUsageStats);
const usageGuide = generator.generateUsageGuideFile(input.resourceFiles);
const workflowPatterns = generator.generateWorkflowPatternsFile(20);

// Convenience functions
const markdown = generateSkillMarkdown(input);
await generateSkillFile(input, 'output/SKILL.md');

```

--------------------------------

### Run Development Commands

Source: https://github.com/haunchen/n8n-skills/blob/main/README.zh-TW.md

Standard npm scripts for building, developing, testing, and type-checking the project.

```bash
# 建置專案
npm run build

# 開發模式
npm run dev

# 執行測試
npm test

# 型別檢查
npm run typecheck
```

--------------------------------

### Build Project

Source: https://github.com/haunchen/n8n-skills/blob/main/README.md

Executes the build script to compile the project for production.

```bash
npm run build
```

--------------------------------

### Run Tests

Source: https://github.com/haunchen/n8n-skills/blob/main/README.md

Executes the test suite to ensure the project's functionality.

```bash
npm test
```

--------------------------------

### Execute Build Orchestration Programmatically

Source: https://context7.com/haunchen/n8n-skills/llms.txt

Initializes the SkillBuilder with a configuration file and triggers the full build process, which includes node collection, property parsing, and resource generation.

```typescript
import { SkillBuilder } from 'n8n-skills/scripts/build';

// Create builder with configuration
const builder = new SkillBuilder('config/skill-config.json');

// Execute complete build process
await builder.build();

// Build steps executed:
// 1. Collect node information from NPM packages (uses cache)
// 2. Collect detailed node properties (uses cache)
// 3. Collect usage statistics from n8n.io API (uses cache)
// 4. Organize and rank nodes by priority
// 5. Build node compatibility matrix
// 6. Generate resource files (tiered strategy)
// 7. Generate compatibility matrix document
// 8. Generate template files (smart caching)
// 9. Generate community node documentation
// 10. Generate main SKILL.md and guide files

// Output:
// ✓ Collected 542 nodes
// ✓ Parsed properties for 542 nodes
// ✓ Fetched 100 templates
// ✓ Selected 10 primary nodes
// ✓ Generated 126 resource files
// ✓ Build completed in 45.23 seconds
```

--------------------------------

### Get Workflow Template by ID

Source: https://github.com/haunchen/n8n-skills/blob/main/docs/workflow-api-research.en.md

Retrieves the complete workflow definition for a given template ID. This endpoint provides detailed information including node configurations, connection relationships, parameter settings, and node positions, which is essential for understanding and importing workflows.

```APIDOC
## GET /api/workflows/templates/{id}

### Description
Retrieves the complete workflow definition for a specific template ID.

### Method
GET

### Endpoint
https://api.n8n.io/api/workflows/templates/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the workflow template.

### Response
#### Success Response (200)
- **id** (number) - The template ID.
- **name** (string) - The name of the template.
- **workflow** (object) - Contains the detailed workflow structure.
  - **meta** (object) - Metadata about the workflow instance.
    - **instanceId** (string) - The unique ID of the workflow instance.
    - **templateCredsSetupCompleted** (boolean) - Indicates if template credentials setup is complete.
  - **nodes** (array) - An array of complete node definitions.
    - **id** (string) - The unique UUID of the node.
    - **name** (string) - The name of the node.
    - **type** (string) - The type of the node (e.g., "n8n-nodes-base.httpRequest").
    - **position** (array) - The [x, y] coordinates of the node on the canvas.
    - **parameters** (object) - The configuration parameters for the node.
    - **typeVersion** (number) - The version of the node type.
    - **credentials** (object) - Optional. Credentials configuration for the node.
    - **notes** (string) - Optional. Notes associated with the node.
    - **cid** (string) - Optional. Creator ID.
    - **creator** (string) - Optional. Creator name.
  - **connections** (object) - Defines the connection relationships between nodes.
    - **[sourceNodeName]** (object) - Keys are source node names.
      - **[outputType]** (array) - Keys are output types (e.g., "main").
        - **[array of connections]** (array)
          - **node** (string) - The target node name.
          - **type** (string) - The type of connection.
          - **index** (number) - The output index.
  - **pinData** (object) - Pinned data for the workflow.

#### Response Example
```json
{
  "id": 6270,
  "name": "Build Your First AI Agent",
  "workflow": {
    "meta": {
      "instanceId": "e409ea34548a2afe2dffba31130cd1cf2e98ebe2afaeed2a63caf2a0582d1da0",
      "templateCredsSetupCompleted": true
    },
    "nodes": [
      {
        "id": "95421925-c5ad-48bd-9638-c84ff5b5e3c6",
        "name": "Example Chat",
        "type": "@n8n/n8n-nodes-langchain.chatTrigger",
        "position": [-176, -64],
        "parameters": {
          "public": true,
          "options": {
            "title": "Your first AI Agent 🚀",
            "subtitle": "This is for demo purposes. Try me out !"
          }
        },
        "typeVersion": 1.1
      },
      {
        "id": "332af12a-45ab-4e5d-8dab-da21ba2111f9",
        "name": "Your First AI Agent",
        "type": "@n8n/n8n-nodes-langchain.agent",
        "position": [192, -64],
        "parameters": {
          "options": {
            "systemMessage": "You are an AI assistant..."
          }
        },
        "typeVersion": 2.2
      }
    ],
    "connections": {
      "Example Chat": {
        "main": [
          [
            {
              "node": "Your First AI Agent",
              "type": "main",
              "index": 0
            }
          ]
        ]
      },
      "Get Weather": {
        "ai_tool": [
          [
            {
              "node": "Your First AI Agent",
              "type": "ai_tool",
              "index": 0
            }
          ]
        ]
      }
    }
  }
}
```
        }
      ]
    }
  ]
}
```

```APIDOC
## GET /api/templates/search

### Description
Retrieves a list of workflow templates with basic information. This endpoint is suitable for searching and listing available templates but lacks detailed workflow structure.

### Method
GET

### Endpoint
https://api.n8n.io/api/templates/search

### Parameters
#### Query Parameters
- **page** (number) - Required - The page number for pagination.
- **rows** (number) - Required - The number of items per page.
- **category** (string) - Optional - Filters templates by category.
- **search** (string) - Optional - Search keywords for template names or descriptions.

### Response
#### Success Response (200)
- **totalWorkflows** (number) - The total number of workflows matching the query.
- **workflows** (array) - An array of workflow template objects.
  - **id** (number) - The unique ID of the workflow template.
  - **name** (string) - The name of the workflow template.
  - **description** (string) - A brief description of the workflow.
  - **totalViews** (number) - The total number of views for the template.
  - **createdAt** (string) - The date and time when the template was created.
  - **user** (object) - Information about the user who created the template.
  - **nodes** (array) - A simplified list of nodes in the workflow (contains basic info like id, name, displayName, icon).

#### Response Example
```json
{
  "totalWorkflows": 100,
  "workflows": [
    {
      "id": 1,
      "name": "Example Workflow",
      "description": "A sample workflow for demonstration.",
      "totalViews": 1500,
      "createdAt": "2023-10-27T10:00:00Z",
      "user": {
        "id": 10,
        "name": "John Doe"
      },
      "nodes": [
        {
          "id": "node-1",
          "name": "Start",
          "displayName": "Start Node",
          "icon": "icon-start"
        },
        {
          "id": "node-2",
          "name": "Process",
          "displayName": "Processing Node",
          "icon": "icon-process"
        }
      ]
    }
  ]
}
```
```

--------------------------------

### Run Build and Maintenance Tasks via NPM

Source: https://context7.com/haunchen/n8n-skills/llms.txt

Standard npm scripts for managing the build lifecycle, updating node data, and running quality assurance checks.

```bash
# NPM commands for building
npm run build          # Compile TypeScript to dist/
npm run build:full     # Full build: compile + generate skill pack
npm start              # Same as build:full

# Development
npm run dev            # TypeScript watch mode
npm run clean          # Clean dist, output, and cache
npm run rebuild        # Clean + build

# Data updates
npm run update         # Update n8n node data
npm run update:check   # Dry-run update check
npm run update:community       # Update community packages
npm run update:community:check # Dry-run community check
npm run update:website # Update website statistics

# Testing and validation
npm test               # Run Jest tests
npm run test:coverage  # Coverage report
npm run lint           # ESLint check
npm run typecheck      # TypeScript type checking
npm run validate       # Validate generated output
```

--------------------------------

### Generate Node Documentation Files with ResourceGenerator

Source: https://context7.com/haunchen/n8n-skills/llms.txt

Use ResourceGenerator to create detailed Markdown documentation for each node, supporting a tiered strategy for individual or merged files. Configure output directory and overwrite behavior. Requires EnrichedNodeInfo, CompatibilityMatrix, and NodeConnectionInfo.

```typescript
import { ResourceGenerator, createResourceGenerator } from 'n8n-skills';
import type { EnrichedNodeInfo, CompatibilityMatrix, NodeConnectionInfo } from 'n8n-skills';

// Create generator with output configuration
const generator = new ResourceGenerator({
  outputDir: 'output/resources',
  overwrite: true
});

// Or use factory function
const gen = createResourceGenerator({ outputDir: 'output/resources' });

// Node data with priority information
const highPriorityNodes: EnrichedNodeInfo[] = [
  // Top 50 most important nodes - get individual files
  { nodeType: 'nodes-base.httpRequest', displayName: 'HTTP Request', category: 'input', /* ... */ }
];

const lowPriorityNodes: EnrichedNodeInfo[] = [
  // Remaining 492 nodes - merged into category files
  { nodeType: 'nodes-base.azureCosmosDb', displayName: 'Azure Cosmos DB', category: 'transform', /* ... */ }
];

// Compatibility data for connection guides
const compatibilityMatrix: CompatibilityMatrix = { /* ... */ };
const nodeConnectionInfoList: NodeConnectionInfo[] = [ /* ... */ ];

// Generate using tiered merge strategy
const resourceFiles = await generator.generateTiered(
  highPriorityNodes,
  lowPriorityNodes,
  compatibilityMatrix,
  nodeConnectionInfoList
);

// Output structure:
// resources/
// ├── INDEX.md                           # Master index with line numbers
// ├── compatibility-matrix.md            # Connection compatibility
// ├── transform/
// │   ├── README.md                      # Category index
// │   ├── nodes-base.code.md             # High-priority individual file
// │   ├── nodes-base.set.md
// │   ├── transform-merged-1.md          # Low-priority merged (first 100)
// │   └── transform-merged-2.md          # Low-priority merged (next 100)
// ├── input/
// │   ├── README.md
// │   └── nodes-base.httpRequest.md
// └── templates/
//     └── README.md

// INDEX.md contains precise line numbers for merged files:
// | Node Name | File Path | Start Line | Line Count |
// | Azure Cosmos DB | transform/transform-merged-1.md | 110 | 64 |

// Read specific node from merged file:
// Read("resources/transform/transform-merged-1.md", offset=110, limit=64)

console.log(`Generated ${resourceFiles.length} resource files`);
console.log(`Processed ${generator.getProcessedCount()} nodes`);

// Clean all generated files
await generator.cleanAll();

```

--------------------------------

### Development workflow commands

Source: https://github.com/haunchen/n8n-skills/blob/main/CONTRIBUTING.en.md

Commands for running the project in development mode, performing quality checks, and validating output.

```bash
# Development mode (watch mode)
npm run dev

# Type checking
npm run typecheck

# Lint checking
npm run lint

# Run full build
npm run build:full

# Validate output
npm run validate
```

--------------------------------

### Project directory structure

Source: https://github.com/haunchen/n8n-skills/blob/main/CONTRIBUTING.en.md

Overview of the source code organization.

```text
src/
├── collectors/    # Data collectors
├── parsers/       # Data parsers
├── organizers/    # Data organizers
├── generators/    # File generators
├── validators/    # Validators
└── utils/         # Utility functions
```

--------------------------------

### Generate Node Configuration Details

Source: https://github.com/haunchen/n8n-skills/blob/main/docs/workflow-api-research.en.md

Generates detailed markdown for each node in the workflow, including its type, version, position, notes, and parameter configuration. Parameters are output as a JSON string.

```typescript
/**
 * Generate node detail information
 */
private generateNodeDetails(workflow: WorkflowDefinition): string {
  const lines: string[] = [];

  workflow.workflow.nodes.forEach((node) => {
    lines.push(`### ${node.name}`);
    lines.push('');
    lines.push(`- Type: lexible${node.type}lexible`);
    lines.push(`- Version: ${node.typeVersion}`);
    lines.push(`- Position: (${node.position[0]}, ${node.position[1]})`);

    if (node.notes) {
      lines.push(`- Notes: ${node.notes}`);
    }

    if (Object.keys(node.parameters).length > 0) {
      lines.push('- Parameter Configuration:');
      lines.push('```json');
      lines.push(JSON.stringify(node.parameters, null, 2));
      lines.push('```');
    }

    lines.push('');
  });

  return lines.join('\n');
}
```

--------------------------------

### Analyze Node Connection Compatibility

Source: https://context7.com/haunchen/n8n-skills/llms.txt

Use CompatibilityAnalyzer to build a matrix of node connection compatibility based on input/output types. This enables intelligent workflow design suggestions. Requires NodeConnectionInfo data, typically from InputOutputParser.

```typescript
import { CompatibilityAnalyzer } from 'n8n-skills';
import type { NodeConnectionInfo, CompatibilityMatrix } from 'n8n-skills';

const analyzer = new CompatibilityAnalyzer();

// Node connection information (from InputOutputParser)
const nodeConnectionInfo: NodeConnectionInfo[] = [
  {
    nodeType: 'nodes-base.httpRequest',
    displayName: 'HTTP Request',
    inputTypes: ['main'],
    outputTypes: ['main'],
    isMultiInput: false,
    isMultiOutput: false,
    requiresSpecialInputs: false,
    category: 'input'
  },
  {
    nodeType: 'nodes-base.if',
    displayName: 'IF',
    inputTypes: ['main'],
    outputTypes: ['main', 'main'],  // Two outputs: true/false
    isMultiInput: false,
    isMultiOutput: true,
    requiresSpecialInputs: false,
    category: 'transform'
  },
  {
    nodeType: 'langchain.agent',
    displayName: 'AI Agent',
    inputTypes: ['main', 'ai_languageModel', 'ai_tool'],
    outputTypes: ['main'],
    isMultiInput: true,
    isMultiOutput: false,
    requiresSpecialInputs: true,  // Requires AI model input
    category: 'transform'
  }
];

// Build complete compatibility matrix
const matrix: CompatibilityMatrix = analyzer.buildCompatibilityMatrix(nodeConnectionInfo);
```

```typescript
// Get recommended connections for a node
const recommendations = analyzer.getRecommendedConnections('nodes-base.httpRequest', matrix, 10);
recommendations.forEach(rec => {
  console.log(`→ ${rec.targetNode} (score: ${rec.score}, ${rec.reason})`);
});
```

```typescript
// Check if two specific nodes are compatible
const canConnect = analyzer.isCompatible('nodes-base.httpRequest', 'nodes-base.if', matrix);
console.log(`HTTP Request → IF: ${canConnect ? 'Compatible' : 'Incompatible'}`);
```

```typescript
// Get compatibility score between nodes
const score = analyzer.getCompatibilityScore('nodes-base.httpRequest', 'nodes-base.if', matrix);
console.log(`Compatibility score: ${score}`);  // Higher = better match
```

--------------------------------

### Batch Fetch Workflow Definitions (TypeScript)

Source: https://github.com/haunchen/n8n-skills/blob/main/docs/IMPLEMENTATION_PLAN.en.md

Method for batch fetching multiple workflow definitions with concurrency control. Recommended concurrency is 5 per batch.

```typescript
public async fetchMultipleWorkflows(
  templateIds: number[],
  concurrency?: number
): Promise<WorkflowDefinition[]>
```

--------------------------------

### Organize n8n Nodes by Category

Source: https://context7.com/haunchen/n8n-skills/llms.txt

Use CategoryOrganizer to assign nodes to categories based on configuration rules. It helps in selecting top nodes for main skill files and grouping remaining nodes for resource files. Requires a category configuration file.

```typescript
import { CategoryOrganizer } from 'n8n-skills';

// Create organizer with category configuration
const organizer = new CategoryOrganizer('config/categories.json');

// Node information to organize
const nodes = [
  { nodeType: 'nodes-base.code', displayName: 'Code', description: 'Execute JavaScript', isTrigger: false },
  { nodeType: 'nodes-base.webhook', displayName: 'Webhook', description: 'Receive webhooks', isTrigger: true },
  { nodeType: 'nodes-base.gmail', displayName: 'Gmail', description: 'Send emails', isTrigger: false }
];

// Organize nodes with limit of 50 top nodes
const result = organizer.organize(nodes, 50);

console.log('Top nodes:', result.topNodes.length);
console.log('Remaining nodes:', result.remainingNodes.length);
console.log('Uncategorized:', result.uncategorizedNodes);
```

```typescript
// Group nodes by category for file generation
const grouped = organizer.groupByCategory(result.topNodes);
for (const [category, categoryNodes] of grouped) {
  console.log(`${category}: ${categoryNodes.length} nodes`);
}
```

```typescript
// Get category information
const categoryInfo = organizer.getCategoryInfo('transform');
console.log(categoryInfo?.name, categoryInfo?.description, categoryInfo?.icon);
```

```typescript
// Get categories sorted by priority
const categories = organizer.getCategoriesByPriority();
categories.forEach(({ key, definition }) => {
  console.log(`${key}: priority ${definition.priority}`);
});
```

```typescript
// Generate statistics
const stats = organizer.generateStatistics(result);
console.log(`Total: ${stats.totalNodes}, Top: ${stats.topNodesCount}`);
console.log('Category breakdown:', stats.categoryCounts);
```

--------------------------------

### Generate Node Details (TypeScript)

Source: https://github.com/haunchen/n8n-skills/blob/main/docs/IMPLEMENTATION_PLAN.en.md

Method to generate detailed configuration information for each node in the workflow. Includes version, position, and parameters.

```typescript
private generateNodeDetails(workflow: WorkflowDefinition): string
```

--------------------------------

### View n8n Skills File Structure

Source: https://github.com/haunchen/n8n-skills/blob/main/README.zh-TW.md

The expected directory structure after extracting the n8n-skills zip file.

```text
n8n-skills/
├── SKILL.md              # 主要技能檔案
└── resources/            # 詳細節點文件
    ├── input/            # 輸入類節點
    ├── output/           # 輸出類節點
    ├── transform/        # 轉換類節點
    ├── trigger/          # 觸發類節點
    ├── organization/     # 組織類節點
    ├── misc/             # 其他節點
    ├── community/        # 社群套件節點
    └── templates/        # 工作流程範本
```

--------------------------------

### Fetch Workflow Definition using cURL

Source: https://github.com/haunchen/n8n-skills/blob/main/docs/workflow-api-summary.en.md

Use this command to fetch a complete workflow definition from the n8n.io API by its ID. The output is a JSON object.

```bash
curl https://api.n8n.io/api/workflows/templates/6270 | jq '.'
```

--------------------------------

### View Connection Relationships in Workflow

Source: https://github.com/haunchen/n8n-skills/blob/main/docs/workflow-api-summary.en.md

This command retrieves a workflow definition and uses `jq` to display the connection relationships between nodes.

```bash
curl -s https://api.n8n.io/api/workflows/templates/6270 | jq '.workflow.connections'
```

--------------------------------

### Define Template API Request Parameters

Source: https://github.com/haunchen/n8n-skills/blob/main/docs/workflow-api-research.en.md

Endpoint configuration for searching n8n templates.

```text
GET https://api.n8n.io/api/templates/search
Parameters:
- page: Page number
- rows: Items per page
- category: Category filter (optional)
- search: Search keywords (optional)
```

--------------------------------

### Implement fetchWorkflowDefinition Method

Source: https://github.com/haunchen/n8n-skills/blob/main/docs/workflow-api-summary.en.md

This TypeScript method should be added to `src/collectors/api-collector.ts` to fetch a specific workflow definition using the n8n.io API.

```typescript
public async fetchWorkflowDefinition(templateId: number) {
  const response = await this.client.get(
    `/workflows/templates/${templateId}`
  );
  return response.data;
}
```

--------------------------------

### Acknowledge n8n-mcp usage

Source: https://github.com/haunchen/n8n-skills/blob/main/ATTRIBUTIONS.en.md

Recommended text to include when using the n8n-mcp package in a project.

```text
Built with n8n-mcp (https://github.com/czlonkowski/n8n-mcp)
Created by Romuald Czlonkowski @ www.aiadvisors.pl/en
```

--------------------------------

### Generate Markdown with Workflow Details

Source: https://github.com/haunchen/n8n-skills/blob/main/docs/workflow-api-research.en.md

Use this function to generate a complete markdown document for a template, including workflow architecture, node configuration, and connection details. It requires Template, WorkflowDefinition, and TemplateCategory objects as input.

```typescript
/**
 * Generate markdown with complete workflow definition
 */
generateTemplateMarkdownWithWorkflow(
  template: Template,
  workflow: WorkflowDefinition,
  category: TemplateCategory
): string {
  const sections = [
    // ... original basic info ...

    '## Workflow Architecture',
    '',
    this.generateWorkflowDiagram(workflow),
    '',
    '## Node Configuration Details',
    '',
    this.generateNodeDetails(workflow),
    '',
    '## Connection Relationships',
    '',
    this.generateConnectionDetails(workflow),
    '',
    '## Complete Workflow JSON',
    '',
    '```json',
    JSON.stringify(workflow.workflow, null, 2),
    '```',
    ''
  ];

  return sections.join('\n');
}
```

--------------------------------

### Commit message format

Source: https://github.com/haunchen/n8n-skills/blob/main/CONTRIBUTING.en.md

Recommended structure for commit messages to ensure clarity and traceability.

```text
type: Brief description (under 50 characters)

More detailed explanation (if needed)
- Explain the reason for changes
- Explain the impact scope
- Related Issue numbers

Closes #123
```

--------------------------------

### Count Nodes in Workflow Definition

Source: https://github.com/haunchen/n8n-skills/blob/main/docs/workflow-api-summary.en.md

This command fetches a workflow definition and then uses `jq` to count the number of nodes within the workflow.

```bash
curl -s https://api.n8n.io/api/workflows/templates/6270 | jq '.workflow.nodes | length'
```

--------------------------------

### Test n8n Workflow API with cURL

Source: https://github.com/haunchen/n8n-skills/blob/main/docs/API_RESEARCH_RESULTS.en.md

A collection of bash commands to query, filter, and inspect n8n workflow template data using cURL and jq.

```bash
# 1. Test API availability
curl -s "https://api.n8n.io/api/workflows/templates/6270" | jq '.name'

# 2. View complete structure
curl -s "https://api.n8n.io/api/workflows/templates/6270" | jq '.' | head -100

# 3. Count nodes
curl -s "https://api.n8n.io/api/workflows/templates/6270" | jq '.workflow.nodes | length'

# 4. List node types
curl -s "https://api.n8n.io/api/workflows/templates/6270" | jq '.workflow.nodes[].type' | sort -u

# 5. View connection relationships
curl -s "https://api.n8n.io/api/workflows/templates/6270" | jq '.workflow.connections'

# 6. Download complete JSON
curl -s "https://api.n8n.io/api/workflows/templates/6270" > workflow-6270.json
```

--------------------------------

### Generate Mermaid Flowchart (TypeScript)

Source: https://github.com/haunchen/n8n-skills/blob/main/docs/IMPLEMENTATION_PLAN.en.md

Method to generate a Mermaid flowchart representation of the workflow architecture. Useful for visualizing node relationships.

```typescript
private generateWorkflowDiagram(workflow: WorkflowDefinition): string
```

--------------------------------

### Generate Connection Relationship Details

Source: https://github.com/haunchen/n8n-skills/blob/main/docs/workflow-api-research.en.md

Generates a markdown list detailing the connections between nodes in the workflow. It specifies the source node, output type, target node, and target index.

```typescript
/**
 * Generate connection relationship details
 */
private generateConnectionDetails(workflow: WorkflowDefinition): string {
  const lines: string[] = [];

  Object.entries(workflow.workflow.connections).forEach(([source, outputs]) => {
    lines.push(`**${source}**`);
    Object.entries(outputs).forEach(([outputType, targets]) => {
      targets.flat().forEach(target => {
        lines.push(`  - ${outputType} → ${target.node} (index: ${target.index})`);
      });
    });
    lines.push('');
  });

  return lines.join('\n');
}
```

--------------------------------

### Define Workflow Detail Response Interfaces

Source: https://github.com/haunchen/n8n-skills/blob/main/docs/workflow-api-research.en.md

TypeScript interfaces for the complete workflow definition, including nodes and connection relationships.

```typescript
interface WorkflowDetailResponse {
  id: number;                    // Template ID
  name: string;                  // Template name
  workflow: {
    meta: {
      instanceId: string;
      templateCredsSetupCompleted: boolean;
    };
    nodes: WorkflowNode[];       // Complete node definitions
    connections: WorkflowConnections;  // Node connection relationships
    pinData: Record<string, any>;      // Pinned data
  };
}

interface WorkflowNode {
  id: string;                    // Node UUID
  name: string;                  // Node name
  type: string;                  // Node type (e.g., "n8n-nodes-base.httpRequest")
  position: [number, number];    // Node position [x, y]
  parameters: Record<string, any>;  // Node parameter configuration
  typeVersion: number;           // Node version
  credentials?: Record<string, any>;  // Credentials configuration
  notes?: string;                // Node notes
  cid?: string;                  // Creator ID
  creator?: string;              // Creator name
}

interface WorkflowConnections {
  [sourceNodeName: string]: {
    [outputType: string]: Array<Array<{
      node: string;              // Target node name
      type: string;              // Connection type (main, ai_tool, ai_languageModel, etc.)
      index: number;             // Output index
    }>>;
  };
}
```

--------------------------------

### Generate Connection Details (TypeScript)

Source: https://github.com/haunchen/n8n-skills/blob/main/docs/IMPLEMENTATION_PLAN.en.md

Method to generate a description of the connection relationships between nodes in the workflow.

```typescript
private generateConnectionDetails(workflow: WorkflowDefinition): string
```

--------------------------------

### Fetch Single Workflow Definition (TypeScript)

Source: https://github.com/haunchen/n8n-skills/blob/main/docs/IMPLEMENTATION_PLAN.en.md

Method to fetch a single workflow definition from the n8n API. Ensure request delays and error handling are implemented.

```typescript
public async fetchWorkflowDefinition(templateId: number): Promise<WorkflowDefinition>
```

--------------------------------

### Verify Claude Code Directory Structure

Source: https://github.com/haunchen/n8n-skills/blob/main/README.zh-TW.md

The required directory structure for n8n-skills within a project's .claude folder.

```text
你的專案/
└── .claude/
    └── skills/
        └── n8n-skills/
            ├── SKILL.md
            └── resources/
```

--------------------------------

### Rank Nodes by Importance with PriorityRanker

Source: https://context7.com/haunchen/n8n-skills/llms.txt

Calculate node importance scores and categorize them into tiers using usage frequency, documentation, and popularity metrics.

```typescript
import { PriorityRanker } from 'n8n-skills';

// Create ranker with configuration file
const ranker = new PriorityRanker('config/priorities.json');

// Prepare node data for ranking
const nodeData = [
  {
    nodeType: 'nodes-base.httpRequest',
    displayName: 'HTTP Request',
    description: 'Makes HTTP requests',
    category: 'Core Nodes',
    usageCount: 487,
    hasDocumentation: true,
    propertyCount: 15,
    packageName: 'n8n-nodes-base'
  },
  {
    nodeType: 'nodes-base.slack',
    displayName: 'Slack',
    description: 'Send messages to Slack',
    category: 'Communication',
    usageCount: 234,
    hasDocumentation: true,
    propertyCount: 8,
    packageName: 'n8n-nodes-base'
  }
  // ... more nodes
];

// Rank all nodes
const scoredNodes = ranker.rankNodes(nodeData);

// Group nodes by tier
const grouped = ranker.groupByTier(scoredNodes);
console.log('Essential nodes:', grouped.essential.length);
console.log('Common nodes:', grouped.common.length);
console.log('Specialized nodes:', grouped.specialized.length);

// Get nodes by specific tier
const essentialNodes = ranker.getNodesByTier(scoredNodes, 'essential');

// Generate comprehensive ranking report
const report = ranker.generateReport(scoredNodes);
console.log(`Total: ${report.totalNodes}`);
console.log(`Tier counts:`, report.tierCounts);
console.log(`Average scores:`, report.averageScores);
console.log('Top 10 nodes:', report.topNodes.map(n => n.displayName));
```

--------------------------------

### Generate Workflow Diagram (Mermaid)

Source: https://github.com/haunchen/n8n-skills/blob/main/docs/workflow-api-research.en.md

Generates a Mermaid graph definition for visualizing the n8n workflow. It processes nodes and connections to create a directed graph. Ensure the workflow object has a valid structure.

```typescript
/**
 * Generate workflow diagram
 */
private generateWorkflowDiagram(workflow: WorkflowDefinition): string {
  const lines = ['```mermaid', 'graph LR'];

  // Generate nodes
  workflow.workflow.nodes.forEach((node, index) => {
    const nodeId = `N${index}`;
    const label = node.name.replace(/"/g, '\\"');
    lines.push(`  ${nodeId}["${label}<br/>${node.type}"]`);
  });

  // Generate connections
  const nodeNameToId = new Map<string, string>();
  workflow.workflow.nodes.forEach((node, index) => {
    nodeNameToId.set(node.name, `N${index}`);
  });

  Object.entries(workflow.workflow.connections).forEach(([source, outputs]) => {
    const sourceId = nodeNameToId.get(source);
    Object.entries(outputs).forEach(([outputType, targets]) => {
      targets.flat().forEach(target => {
        const targetId = nodeNameToId.get(target.node);
        if (sourceId && targetId) {
          lines.push(`  ${sourceId} -->|${outputType}| ${targetId}`);
        }
      });
    });
  });

  lines.push('```');
  return lines.join('\n');
}
```

--------------------------------

### n8n API Endpoint for Complete Workflow Definitions

Source: https://github.com/haunchen/n8n-skills/blob/main/docs/API_RESEARCH_RESULTS.en.md

This endpoint retrieves a complete workflow definition, including all nodes, their parameters, positions, and connection relationships. The returned JSON is directly importable into n8n.

```bash
GET https://api.n8n.io/api/workflows/templates/{id}

# Example
curl https://api.n8n.io/api/workflows/templates/6270
```

--------------------------------

### Fetch Workflow Definitions for Templates

Source: https://github.com/haunchen/n8n-skills/blob/main/docs/workflow-api-research.en.md

Fetches complete workflow definitions for a given array of templates. It selects the top 50 most popular templates to limit API requests and returns a Map of workflow IDs to their definitions.

```typescript
// Step 3.5: Fetch complete workflow definitions
async function fetchWorkflowDefinitions(
  templates: Template[]
): Promise<Map<number, WorkflowDefinition>> {
  const collector = new ApiCollector();
  const definitions = new Map<number, WorkflowDefinition>();

  // Select top N most popular templates
  const topTemplates = templates
    .sort((a, b) => b.totalViews - a.totalViews)
    .slice(0, 50);  // Limit quantity to avoid excessive API requests

  const templateIds = topTemplates.map(t => t.id);
  const workflows = await collector.fetchMultipleWorkflows(templateIds);

  workflows.forEach(workflow => {
    definitions.set(workflow.id, workflow);
  });

  return definitions;
}
```

--------------------------------

### Fetch Workflow Definitions in TypeScript

Source: https://github.com/haunchen/n8n-skills/blob/main/docs/IMPLEMENTATION_PLAN.en.md

This function is responsible for fetching workflow definitions. It includes steps for selecting popular templates, checking cache, batch fetching uncached definitions, and saving the cache. Ensure the Template and WorkflowDefinition types are properly defined.

```typescript
// Step 3.5: Fetch workflow definitions
async function fetchWorkflowDefinitions(
  templates: Template[]
): Promise<Map<number, WorkflowDefinition>> {
  // 1. Select top 50 most popular templates
  // 2. Check cache
  // 3. Batch fetch uncached ones
  // 4. Save cache
  // 5. Return results
}
```

--------------------------------

### Extend ApiCollector with Workflow Fetching Methods

Source: https://github.com/haunchen/n8n-skills/blob/main/docs/workflow-api-research.en.md

Methods for fetching individual workflow definitions with retry logic and batch fetching with concurrency control.

```typescript
/**
 * Fetch complete workflow definition
 */
public async fetchWorkflowDefinition(templateId: number): Promise<WorkflowDefinition> {
  try {
    console.log(`Fetching complete workflow definition for Template ID ${templateId}...`);

    const response = await this.withRetry(async () => {
      return await this.client.get<WorkflowDefinition>(
        `/workflows/templates/${templateId}`
      );
    });

    console.log(`Successfully fetched workflow: ${response.data.name}`);
    console.log(`- Node count: ${response.data.workflow.nodes.length}`);
    console.log(`- Connection count: ${Object.keys(response.data.workflow.connections).length}`);

    return response.data;
  } catch (error) {
    if (error instanceof Error) {
      throw new Error(`Failed to fetch workflow definition: ${error.message}`);
    }
    throw new Error('Unknown error occurred while fetching workflow definition');
  }
}

/**
 * Batch fetch multiple workflow definitions
 */
public async fetchMultipleWorkflows(
  templateIds: number[],
  concurrency: number = 5
): Promise<WorkflowDefinition[]> {
  const results: WorkflowDefinition[] = [];

  // Use concurrency control to avoid too many requests
  for (let i = 0; i < templateIds.length; i += concurrency) {
    const batch = templateIds.slice(i, i + concurrency);
    const batchResults = await Promise.all(
      batch.map(id => this.fetchWorkflowDefinition(id))
    );
    results.push(...batchResults);

    // Add delay between batches
    if (i + concurrency < templateIds.length) {
      await this.delay(1000);
    }
  }

  return results;
}
```

--------------------------------

### Workflow Type Definitions (TypeScript)

Source: https://github.com/haunchen/n8n-skills/blob/main/docs/IMPLEMENTATION_PLAN.en.md

Interface definitions for workflow nodes, connections, and the overall workflow definition.

```typescript
export interface WorkflowNode { ... }
```

```typescript
export interface WorkflowConnections { ... }
```

```typescript
export interface WorkflowDefinition { ... }
```