Zapier Workflows Doctor

Diagnose whether the installed Zapier SDK CLI can support the Zapier Workflows skill bundle. Be diagnostic first. Do not refresh skills unless SDK/skill drift is detected or compatibility cannot be confirmed.

Compatibility Metadata

Workflow skills use these metadata fields:

• sdk_cli_min: oldest SDK CLI version the skill is allowed to run against. Set it to the first SDK CLI version that supports the newest command or flag the skill depends on. If that exact first-supported version is uncertain, use the SDK CLI version used when introducing the skill instruction change.
• sdk_cli_validated: SDK CLI version used during the latest validation pass. Update it whenever workflow skills are intentionally tested and republished against a newer SDK CLI, even if sdk_cli_min does not change.
• refresh_source: canonical skill source. For these skills, keep this as zapier/agent-skills.

Command-surface checks verify required bundle capabilities only. They do not prove full workflow correctness or that JSON payload semantics are unchanged.

Step 0: Daily Skill-Freshness Check

Run this before the SDK compatibility steps below. It keeps the workflow skills current with zapier/agent-skills even when the SDK CLI has not changed, by occasionally running npx skills update for the bundle. It is soft and non-blocking: it self-throttles to roughly once per day per project, never stops the calling skill, and prints nothing unless it actually applied an update.

Run it exactly once, then continue to Step 1 regardless of its output. Do not parse or branch on the result:

bash scripts/skill-freshness-check.sh

Resolve scripts/skill-freshness-check.sh relative to this skill's own directory. The script locates the installed skill bundle from its own path and runs the bundle update from the scope root that contains it (the directory holding .agents/.claude), so it does not matter which directory you invoke it from.

• If it prints a note that skills were refreshed, pass that note along to the user and keep going; the update takes full effect on the next workspace reload.
• If it prints nothing, say nothing and continue.

This freshness check is independent of the SDK command-surface compatibility check in Steps 1–4 below, which is unchanged and remains a hard gate. For troubleshooting, set ZAPIER_WORKFLOWS_DEBUG=1 to see the freshness check's decision on stderr.

Step 1: Check Bundle Compatibility

Check the workflow skill bundle as one unit. Do not maintain separate compatibility checks for workflows-install, workflows-create, workflows-list, workflows-history, and workflows-modify; users will normally use these skills together, and drift in any core workflow SDK surface should refresh the whole bundle.

workflows-create and workflows-modify test an unpublished draft with run-workflow-draft and publish the tested draft with publish-workflow-draft, declaring a manual start mode with --manual on update-workflow-draft or publish-workflow-draft. Every command runs under --stability experimental. The bundle gates on sdk_cli_min = 0.85.0, the first @zapier/zapier-sdk-cli that ships --stability (run-workflow-draft arrived in 0.82.0; the older --experimental flag is deprecated). A CLI older than that is flagged for upgrade.

Step 2: Check SDK CLI Versions

Run:

which zapier-sdk
zapier-sdk --version
npm view @zapier/zapier-sdk-cli version

If zapier-sdk is missing or zapier-sdk --version is below the bundle's sdk_cli_min, update the SDK CLI before continuing:

npm install -g @zapier/zapier-sdk-cli@latest
zapier-sdk --version

If global npm installs fail because of permissions, tell the user to fix their Node/npm setup before retrying. Prefer a user-owned Node install through nvm or Homebrew over sudo npm install -g.

If the installed SDK CLI version is newer than the bundle's sdk_cli_validated, continue to command-surface discovery. Do not refresh skills solely because the SDK CLI is newer.

Step 3: Discover Current Command Surface

Start from the SDK help output:

zapier-sdk --stability experimental --help

Use the help output to discover the current command names and flags for the required bundle capabilities below. Current command names in this skill are examples from the SDK CLI version the workflow skill bundle was validated against; they are not the compatibility contract. If the current help output exposes an equivalent way to perform a required capability, use the current help output.

For each discovered candidate command, inspect command-specific help:

zapier-sdk --stability experimental <candidate-command> --help

Required Bundle Capabilities

Confirm that the SDK CLI exposes a clear way to perform these operations for the workflow skill bundle:

• Create a workflow container.
• List a workflow's open drafts.
• Create (fork) a workflow draft.
• Read a workflow draft.
• Update a workflow draft, with optimistic concurrency via a draft revision, declaring its start mode (--trigger, or --manual for on-demand).
• Run a workflow draft: start an unpublished test run of a given draft revision (run-workflow-draft).
• Publish a workflow draft, with optimistic concurrency and enabled-state control, declaring its start mode (a stored trigger, or --manual for on-demand).
• Discard a workflow draft.
• List workflows.
• List workflow runs.
• Inspect a workflow run.
• Discover or list app triggers.
• Trigger a workflow.
• Control workflow visibility, including private workflow creation or the current equivalent.
• Bind app connections on workflow drafts.
• Bind app implementation/version metadata when required.
• Provide trigger configuration on workflow drafts.
• Pass workflow input when running or triggering workflows.
• Control enabled state when publishing workflow drafts.

The bundle publishes through drafts: publish-workflow-draft publishes the tested draft revision and consumes the draft, so nothing stale is left behind. The bundle does not use direct publish-workflow-version. The bundle invariant: never publish past an open draft.

When the current SDK help output is clear, prefer it over the example commands below. If discovery is ambiguous or a required capability appears absent, treat compatibility as unconfirmed and refresh the workflow skill bundle.

Example commands from the validated SDK CLI surface:

zapier-sdk --stability experimental create-workflow --help
zapier-sdk --stability experimental list-workflows --help
zapier-sdk --stability experimental list-workflow-runs --help
zapier-sdk --stability experimental get-workflow-run --help
zapier-sdk --stability experimental list-triggers --help
zapier-sdk --stability experimental trigger-workflow --help
zapier-sdk --stability experimental get-trigger-run --help
zapier-sdk --stability experimental get-workflow --help
zapier-sdk --stability experimental get-workflow-version --help
zapier-sdk --stability experimental list-workflow-drafts --help
zapier-sdk --stability experimental create-workflow-draft --help
zapier-sdk --stability experimental get-workflow-draft --help
zapier-sdk --stability experimental update-workflow-draft --help
zapier-sdk --stability experimental run-workflow-draft --help
zapier-sdk --stability experimental publish-workflow-draft --help
zapier-sdk --stability experimental discard-workflow-draft --help

Example flags from the validated SDK CLI surface:

• create-workflow: --private
• update-workflow-draft: --draft-revision, --dependencies, --connections, --app-versions, --trigger, --manual
• run-workflow-draft: --input
• publish-workflow-draft: --draft-revision, --manual, --enabled
• trigger-workflow: --input

Equivalent current flags or command shapes are acceptable if the help text clearly supports the same required bundle capability.

Step 4: Decide Whether To Refresh Skills

If all required bundle capabilities are confirmed, tell the calling skill to continue without refreshing.

If any required capability is missing, or compatibility cannot be confirmed, update the entire workflow skill bundle so the skills stay in sync.

Prefer the standard day-2 update path first:

npx skills update workflows-install workflows-doctor workflows-create workflows-list workflows-history workflows-modify workflows-ai-by-zapier -y

If skills update cannot find the installed skills, updates the wrong scope, or otherwise fails, fall back to explicit installs from canonical GitHub:

npx skills add zapier/agent-skills --skill workflows-install --yes
npx skills add zapier/agent-skills --skill workflows-doctor --yes
npx skills add zapier/agent-skills --skill workflows-create --yes
npx skills add zapier/agent-skills --skill workflows-list --yes
npx skills add zapier/agent-skills --skill workflows-history --yes
npx skills add zapier/agent-skills --skill workflows-modify --yes
npx skills add zapier/agent-skills --skill workflows-ai-by-zapier --yes

After updating skills, stop the current skill invocation. Tell the user to reload the agent workspace and rerun their original request. Do not promise that the current invocation has changed its already-loaded instructions.