n8n Workflows

SKILL.md

---
name: n8n
description: Build, manage, and trigger n8n workflows via API. Create automations, connect services, and orchestrate complex workflows.
---

# n8n Workflow Skill

Build and manage n8n workflows programmatically.

## Connection

- **URL:** https://n8n.crl.to
- **Credentials:** `~/clawd/secrets/n8n.json`

## API Usage

```bash
# Auth header
N8N_KEY=$(jq -r '.apiKey' ~/clawd/secrets/n8n.json)

# List workflows
curl -s "https://n8n.crl.to/api/v1/workflows" \
  -H "X-N8N-API-KEY: $N8N_KEY"

# Get workflow by ID
curl -s "https://n8n.crl.to/api/v1/workflows/{id}" \
  -H "X-N8N-API-KEY: $N8N_KEY"

# Create workflow
curl -s -X POST "https://n8n.crl.to/api/v1/workflows" \
  -H "X-N8N-API-KEY: $N8N_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "My Workflow", "nodes": [...], "connections": {...}}'

# Activate/deactivate
curl -s -X PATCH "https://n8n.crl.to/api/v1/workflows/{id}" \
  -H "X-N8N-API-KEY: $N8N_KEY" \
  -H "Content-Type: application/json" \
  -d '{"active": true}'

# Execute workflow (webhook trigger)
curl -s -X POST "https://n8n.crl.to/webhook/{webhook-path}" \
  -H "Content-Type: application/json" \
  -d '{"data": "payload"}'

# List executions
curl -s "https://n8n.crl.to/api/v1/executions" \
  -H "X-N8N-API-KEY: $N8N_KEY"
```

## Workflow Patterns

Reference docs in `docs/` folder:

| Pattern | File | Use Case |
|---------|------|----------|
| Webhook Processing | `webhook_processing.md` | Receive external triggers |
| HTTP API Integration | `http_api_integration.md` | Call external APIs |
| Database Operations | `database_operations.md` | CRUD with databases |
| AI Agent Workflow | `ai_agent_workflow.md` | LLM-powered automations |
| Scheduled Tasks | `scheduled_tasks.md` | Cron-based automation |

## Expression Syntax

See `docs/expression-syntax.md` for n8n expression patterns.

Key variables:
- `{{ $json }}` - Current item data
- `{{ $json.body }}` - Webhook payload (critical!)
- `{{ $node["NodeName"].json }}` - Data from specific node
- `{{ $now }}` - Current timestamp
- `{{ $env.VAR_NAME }}` - Environment variable

## Node Configuration

See `docs/node-config.md` for node setup patterns.

Common nodes:
- `n8n-nodes-base.webhook` - Trigger on HTTP request
- `n8n-nodes-base.httpRequest` - Make HTTP calls
- `n8n-nodes-base.code` - Custom JavaScript/Python
- `n8n-nodes-base.if` - Conditional branching
- `n8n-nodes-base.set` - Transform data
- `n8n-nodes-base.slack` - Slack integration
- `n8n-nodes-base.googleSheets` - Google Sheets

## Workflow JSON Structure

```json
{
  "name": "Workflow Name",
  "nodes": [
    {
      "id": "uuid",
      "name": "Node Name",
      "type": "n8n-nodes-base.webhook",
      "position": [250, 300],
      "parameters": {},
      "typeVersion": 1
    }
  ],
  "connections": {
    "Node Name": {
      "main": [[{"node": "Next Node", "type": "main", "index": 0}]]
    }
  },
  "settings": {
    "executionOrder": "v1"
  }
}
```

## Validation

See `docs/validation.md` for error handling patterns.

Common issues:
- Missing required parameters
- Wrong expression syntax (`{{ }}` vs `$()`)
- Webhook data in `$json.body` not `$json`
- Node type format: `n8n-nodes-base.*` not `nodes-base.*`

## Quick Reference

```bash
# Helper function
n8n_api() {
  curl -s "https://n8n.crl.to/api/v1/$1" \
    -H "X-N8N-API-KEY: $(jq -r '.apiKey' ~/clawd/secrets/n8n.json)" \
    "${@:2}"
}

# Usage
n8n_api workflows | jq '.data[].name'
n8n_api workflows/abc123
n8n_api executions?limit=10
```