[one-flow skill] AI agents never use parallel steps — skill needs better examples and guidance

[lucasygu]

Summary

The one-flow skill documents the parallel step type, but AI agents almost never use it — and when they do, they get the structure wrong. Out of 65 n8n workflow replications built by AI agents in a single session, zero used the parallel step type, despite 29 of the source n8n workflows having parallel/merge patterns.

Two failure modes

1. AI agents don't reach for parallel when they should (awareness)

Many workflows have independent data fetches that could run concurrently:

• Fetch Gmail + fetch Calendar + fetch Google Sheets → compile into briefing
• Search Exa + scrape with Firecrawl → combine results
• List Google Drive files + list Gmail messages → merge for analysis

In all 65 replicated flows, the AI built these as sequential steps. The data fetches run one after another, even though they're completely independent. This makes flows slower than necessary.

Why it happens: The skill has one parallel example in the step types reference section. But all four complete examples (Examples 1-4) are sequential. The AI-Augmented Patterns section (the most influential section for AI behavior) is also entirely sequential. The AI models its work after the most prominent examples — and those are all sequential.

2. When the AI does try parallel, it generates invalid structure (correctness)

The one time an AI agent attempted to use parallel (for a personal assistant workflow that fetches from 3 platforms simultaneously), it produced malformed substeps — missing name and type fields on the child steps:

{
  "type": "parallel",
  "parallel": {
    "steps": [
      { "platform": "gmail", "action": "..." },
      { "platform": "google-calendar", "action": "..." },
      { "platform": "google-sheets", "action": "..." }
    ]
  }
}

Each substep is missing the required id, name, and type fields. The AI treated parallel.steps as a simplified format rather than following the same schema as top-level steps.

Why it happens: The skill's parallel example shows the correct structure but it's compact — just two lines per substep with { "...": "..." } placeholders. The AI may not internalize that each substep needs the full step schema.

Evidence

• 65 flows built in this session. 0 use parallel.
• 29 out of 100 source n8n workflows use merge/parallel patterns.
• 1 attempt to use parallel resulted in a validation failure.
• The only flow in the entire project that uses parallel correctly is competitive-seo-analyzer, which was hand-built (not AI-generated from a template).

Suggested fix

Add a complete parallel example as Example 5

Show a realistic use case — fetching from multiple platforms concurrently then combining results:

{
  "key": "daily-digest",
  "name": "Daily Digest from Email + Calendar",
  "steps": [
    {
      "id": "fetchAll",
      "name": "Fetch email and calendar data in parallel",
      "type": "parallel",
      "parallel": {
        "steps": [
          {
            "id": "fetchEmails",
            "name": "Fetch recent Gmail messages",
            "type": "action",
            "action": {
              "platform": "gmail",
              "actionId": "GMAIL_LIST_MESSAGES_ACTION_ID",
              "connectionKey": "$.input.gmailKey",
              "pathVars": { "userId": "me" },
              "queryParams": { "maxResults": 10 }
            }
          },
          {
            "id": "fetchEvents",
            "name": "Fetch today's calendar events",
            "type": "action",
            "action": {
              "platform": "google-calendar",
              "actionId": "CALENDAR_LIST_EVENTS_ACTION_ID",
              "connectionKey": "$.input.calendarKey",
              "pathVars": { "calendarId": "primary" },
              "queryParams": { "maxResults": 10 }
            }
          }
        ]
      }
    },
    {
      "id": "combine",
      "name": "Combine email and calendar data",
      "type": "code",
      "code": {
        "source": "const emails = $.steps.fetchEmails.response.messages || [];\nconst events = $.steps.fetchEvents.response.items || [];\nreturn { emails, events, totalItems: emails.length + events.length };"
      }
    }
  ]
}

Add guidance in the AI-Augmented Patterns section

After the file-write → bash → code pattern, add:

### When to use parallel steps

Use `parallel` when your workflow fetches from 2+ independent data sources
before combining them. Common patterns:
- Fetch Gmail + Calendar + Sheets → compile into daily briefing
- Search Exa + scrape with Firecrawl → merge research data
- Query BigQuery + list Google Drive files → combine for analysis

Each substep inside `parallel.steps` must have the full step schema:
`id`, `name`, `type`, and the type-specific config (action, code, etc.).

Impact

Without this fix, every AI-generated workflow runs independent data fetches sequentially. For workflows that fetch from 3+ platforms, this means 3x slower execution for no reason.