---
name: n8n-workflows
description: Build, review, and safely modify n8n workflows using the official n8n docs, local n8n API access, and existing credentials. Use when creating or editing automations in n8n, wiring credentials into workflows, cloning a base workflow, debugging executions, or making workflow changes without breaking a live automation.
---

# n8n Workflows

Use this skill to work on n8n workflows carefully and predictably.

## Core rules

- Prefer the official n8n docs as the source of truth.
- Treat existing production workflows as fragile.
- Inspect before editing.
- Prefer cloning or exporting before risky edits.
- Test with manual executions before trusting production triggers.
- Do not assume the public API accepts the same payload shape as the Editor UI.
- If a workflow is live, avoid partial updates that could wipe nodes, connections, or settings.

## Safe workflow process

1. Find the target workflow and inspect its current structure.
2. Export or duplicate the workflow before risky edits.
3. Prefer making changes in the cloned workflow instead of the live original when the existing workflow is already working.
4. Inspect available credentials separately.
5. Modify the workflow in a way that preserves nodes, connections, and trigger structure.
6. Run a manual test or inspect executions before re-enabling confidence.
7. Only then make broader changes or swap over from the original.

## Read references as needed

- For workflow safety and editing guidance, read `references/safety.md`.
- For local API patterns and payload caution, read `references/api.md`.
- For workflow design and testing habits, read `references/design.md`.
- For a preflight checklist before edits, read `references/checklist.md`.

## Local environment assumptions

When local n8n is present, prefer inspecting it directly.
Current environment patterns already observed here:
- n8n is reachable locally on `http://127.0.0.1:5678`
- public API auth uses `N8N_API_KEY`
- credentials can be listed separately from workflow definitions

## Editing discipline

- Never send a guessed minimal update payload to a live workflow.
- Preserve the full workflow shape needed by the endpoint you are using.
- If endpoint behavior is uncertain, stop and export or duplicate first.
- Prefer additive changes over large restructures.
- When adding credentials, match existing node patterns closely.
- For a working production workflow, prefer cloning and editing the clone rather than writing directly into the live workflow.

## Testing discipline

- Keep workflows inactive while developing when practical.
- Use manual executions for testing.
- Inspect execution output instead of trusting assumptions.
- If a workflow powers a live daily brief, reminder, or messaging path, treat it as production.

## Recovery mindset

If an edit appears to damage a workflow:
- stop making more writes
- inspect version history, exports, or duplicate copies
- restore structure first
- only then continue feature edits


---

# Workflow Safety

## Purpose

Use this reference before editing existing n8n workflows, especially live ones.

## Practical safety rules

- Assume a live workflow is production unless proven otherwise.
- Inspect the workflow first.
- Export or duplicate before risky edits.
- Do not rely on memory for node names, connections, or payload shapes.
- Avoid editing a live workflow if you do not yet understand how its trigger, credential, and delivery path fit together.

## Minimum safe sequence

1. Identify the workflow by exact name and ID.
2. Inspect its nodes, connections, active status, and credentials.
3. Inspect available credentials separately.
4. Create a backup path first:
   - duplicate workflow in UI, or
   - export workflow JSON, or
   - confirm a recoverable prior version exists
5. If the original workflow is already working, make changes in the duplicate first.
6. Make the smallest possible change.
7. Run a manual test.
8. Review the execution output.
9. Only then trust the workflow again or swap from the original to the clone.

## High-risk changes

Treat these as risky:
- API updates to an existing live workflow
- replacing trigger nodes
- changing credential bindings
- changing delivery nodes that send messages or webhooks
- changing code nodes that aggregate multiple branches
- changing schedule timing on a production briefing workflow

## Best-practice default

When a workflow is already working:
- keep the original intact
- clone it
- make edits in the clone
- test the clone manually
- only replace or activate the clone once it is verified

This lowers the chance that a bad edit blocks the scheduled run of the original workflow.

## Red flags

Stop and reassess if:
- the update endpoint accepts less data than expected
- the returned workflow shape differs from what the UI shows
- nodes disappear from the fetched workflow
- active status changes unexpectedly
- the workflow no longer shows a trigger node
- connection arrays no longer line up with expected branches

## Recovery principle

If something looks broken, stop writing immediately.
Repeated writes after a bad update usually make recovery harder.


---

# API Patterns and Caution

## Purpose

Use this reference when interacting with n8n through the local API instead of only through the Editor UI.

## What to assume

- The n8n public API may validate request bodies more strictly than expected.
- The payload shape for updates may reject extra properties.
- The payload shape may also require more than a naive minimal object.
- The safest edit is not always a direct overwrite of a live workflow.

## Local patterns seen here

- Base URL: `http://127.0.0.1:5678/api/v1`
- Auth header: `X-N8N-API-KEY: <token>`
- Credentials can be listed independently from workflows

## Working habits

### Read first

Before editing, retrieve:
- workflow list
- target workflow by ID
- credential list when credentials matter

### Preserve structure

When editing a workflow, preserve at least:
- name
- nodes
- connections
- settings

Do not assume other fields are accepted by the write endpoint.
Do not assume fields returned by GET are valid to send back unchanged in PUT.

## Safer strategy than blind overwrite

Prefer this order:
1. fetch the workflow
2. inspect the required write shape
3. duplicate or back up before mutation
4. apply the smallest edit possible
5. fetch again and compare structure
6. run manual execution

## Credential wiring guidance

When adding a new account of the same service:
- copy the existing node pattern closely
- change only the credential binding, node name, and any account-specific query or labeling
- update downstream code nodes carefully so new branches are clearly labeled
- verify the aggregation logic still works when one branch returns zero items

## Do not do this

- do not send guessed partial workflow payloads to production workflows
- do not assume GET and PUT schemas are symmetric
- do not keep retrying write variants against a damaged workflow without a restore plan


---

# Workflow Design and Testing

## Purpose

Use this reference when building or improving n8n workflows so they are easier to test and less brittle to change later.

## Official-doc takeaways

From the n8n docs:
- a workflow is a collection of connected nodes
- use workflow templates to get started when useful
- debug with the executions list
- manual executions are the recommended testing path while developing
- keeping workflows inactive during development is recommended when practical

## Design habits

- Keep node names explicit and stable.
- Label multi-account branches clearly.
- Keep code nodes readable and defensive.
- When aggregating multiple branches, handle empty branches safely.
- Avoid hidden assumptions about timezones, field shapes, or one provider matching another.

## Good patterns

### Multi-account inbox pattern

- one trigger
- one branch per mailbox/account
- one aggregation node with explicit labels like `[Outlook]`, `[Gmail personal]`, `[Gmail work]`
- one downstream summarizer or delivery node

### Base-workflow pattern

The official docs suggest a base workflow that is duplicated and customized per user or context.
Use that pattern when:
- the structure stays the same
- only credentials or a few parameters change
- you want to reduce the chance of breaking a working template

### Safe-change clone pattern

When changing a workflow that already works in production:
- duplicate the workflow first
- edit the duplicate
- test the duplicate manually
- only then cut over from the original if the clone behaves correctly

Prefer this over direct edits to the production workflow whenever timing or reliability matters.

### Execution-first debugging pattern

When testing:
- run manually
- inspect execution output for each branch
- verify item shapes before updating code nodes
- only then trust delivery output

## Common failure modes

- adding a new account with a different response shape than the old node
- rewriting a code node without checking all incoming branches
- assuming time-based filters mean the same thing across providers
- modifying a production schedule before validating the data path


---

# n8n Workflow Preflight Checklist

## Before editing

- What is the exact workflow name?
- What is the workflow ID?
- Is it active?
- What trigger starts it?
- What credentials does it already use?
- What delivery path could break if this fails?
- Is there a backup, duplicate, or export?

## Before adding a new account branch

- Is there an existing node for the same service to copy from?
- What is the exact credential name?
- Does the new node return the same data shape?
- Does downstream aggregation label each source clearly?
- What happens if the new branch returns zero items?

## Before writing via API

- Do I know the accepted write shape for this endpoint?
- Am I preserving nodes, connections, and settings?
- Am I sending only fields the endpoint expects?
- Do I have a restore path if the write goes sideways?

## Before trusting the change

- Did I fetch the workflow again after the edit?
- Are all nodes still present?
- Is the trigger still present?
- Are connections still intact?
- Did I run a manual execution?
- Did I inspect the execution output?
- Did I confirm no live delivery path broke?

## If something breaks

- Stop making writes.
- Check for workflow history, export, or duplicate.
- Restore structure first.
- Resume edits only after the workflow is healthy again.