workflows-doctor

Zapier ワークフロー診断

インストール済みの Zapier SDK CLI が Zapier Workflows スキルバンドルに対応しているかを診断します。まず診断を行ってください。SDK とスキルの不整合が検出された場合、または互換性を確認できない場合を除き、スキルを更新しないでください。

互換性メタデータ

ワークフロースキルでは、次のメタデータフィールドを使用します。

• sdk_cli_min：スキルの実行が許可される、最も古い SDK CLI のバージョンです。スキルが依存する最新のコマンドまたはフラグに対応した、最初の SDK CLI バージョンを設定してください。その最初の対応バージョンが正確に分からない場合は、スキルの指示を導入した際に使用した SDK CLI バージョンを設定してください。
• sdk_cli_validated：直近の検証で使用した SDK CLI のバージョンです。sdk_cli_min が変わらない場合でも、ワークフロースキルを意図的に新しい SDK CLI に対してテストして再公開するたびに更新してください。
• refresh_source：正規のスキルソースです。これらのスキルでは、zapier/agent-skills のままにしてください。

コマンドサーフェスのチェックで検証するのは、バンドルに必要な機能のみです。ワークフロー全体が正しく動作することや、JSON ペイロードのセマンティクスが変わっていないことを保証するものではありません。

ステップ 0：毎日のスキル最新状態チェック

以下の SDK 互換性チェックに進む前に実行してください。このチェックは、SDK CLI が変更されていなくても、バンドルに対して npx skills update をときどき実行し、zapier/agent-skills に合わせてワークフロースキルを最新の状態に保ちます。ソフトチェックであり、処理をブロックしません。プロジェクトごとにおよそ 1 日に 1 回だけ実行され、呼び出し元のスキルを停止することはなく、実際に更新を適用した場合にのみ出力します。

これを正確に 1 回実行してから、出力にかかわらずステップ 1 に進んでください。結果を解析したり、それに応じて処理を分岐したりしないでください。

bash scripts/skill-freshness-check.sh

scripts/skill-freshness-check.sh は、このスキル自身のディレクトリを基準に解決してください。このスクリプトは自身のパスからインストール済みのスキルバンドルを特定し、それを含むスコープルート（.agents／.claude を含むディレクトリ）からバンドルの更新を実行します。そのため、どのディレクトリから呼び出しても問題ありません。

• スキルが更新されたという通知が表示された場合は、その通知をユーザーに伝えて処理を続けてください。更新は次回のワークスペース再読み込み時に完全に反映されます。
• 何も表示されない場合は、何も伝えずに続行してください。

この最新状態チェックは、以下のステップ 1～4 で行う SDK コマンドサーフェスの互換性チェックとは独立しており、互換性チェックの内容に変更はなく、引き続き必須のゲートです。トラブルシューティングでは、ZAPIER_WORKFLOWS_DEBUG=1 を設定すると、最新状態チェックの判断を stderr で確認できます。

ステップ 1：バンドルの互換性を確認する

ワークフロースキルバンドルをひとまとまりとして確認してください。workflows-install、workflows-create、workflows-list、workflows-history、workflows-modify を個別に互換性チェックしないでください。通常、ユーザーはこれらのスキルを一緒に使います。また、コアとなるワークフロー SDK サーフェスに不整合があれば、バンドル全体を更新する必要があります。

workflows-create と workflows-modify は、run-workflow-draft で未公開のドラフトをテストし、update-workflow-draft または publish-workflow-draft に --manual を指定して手動開始モードを宣言したうえで、テスト済みのドラフトを publish-workflow-draft で公開します。すべてのコマンドは --stability experimental のもとで実行します。このバンドルでは、--stability を初めて搭載した @zapier/zapier-sdk-cli のバージョン 0.85.0 を sdk_cli_min として必須にします（run-workflow-draft は 0.82.0 で追加されました。旧式の --experimental フラグは非推奨です）。それより古い CLI はアップグレード対象として示されます。

ステップ 2：SDK CLI のバージョンを確認する

次を実行します。

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

zapier-sdk が見つからない場合、または zapier-sdk --version がバンドルの sdk_cli_min を下回る場合は、続行する前に SDK CLI を更新してください。

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

権限の問題でグローバルな npm インストールに失敗する場合は、再試行する前に Node／npm の環境を修正するようユーザーに伝えてください。sudo npm install -g よりも、nvm または Homebrew を使ったユーザー所有の Node インストールを優先してください。

インストール済みの SDK CLI バージョンがバンドルの sdk_cli_validated より新しい場合は、コマンドサーフェスの検出に進んでください。SDK CLI が新しいという理由だけでスキルを更新しないでください。

ステップ 3：現在のコマンド体系を確認する

まず、SDK のヘルプ出力を確認します。

zapier-sdk --stability experimental --help

ヘルプ出力を使って、以下に示す必須バンドル機能に対応する現在のコマンド名とフラグを確認します。このスキルの現在のコマンド名は、ワークフロースキルバンドルの検証に使用した SDK CLI バージョンの例であり、互換性の基準ではありません。現在のヘルプ出力に、必須機能を実行する同等の方法が示されている場合は、現在のヘルプ出力に従ってください。

候補として見つかったコマンドごとに、コマンド固有のヘルプを確認します。

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

必須バンドル機能

SDK CLI に、ワークフロースキルバンドル向けに以下の操作を行う明確な方法が用意されていることを確認します。

• ワークフローコンテナーを作成する。
• ワークフローの未公開ドラフトを一覧表示する。
• ワークフローのドラフトを作成（フォーク）する。
• ワークフローのドラフトを読み取る。
• ワークフローのドラフトを更新する。ドラフトリビジョンによる楽観的同時実行制御を行い、開始モード（--trigger、またはオンデマンドの場合は --manual）を指定する。
• ワークフローのドラフトを実行する。指定したドラフトリビジョンの未公開テスト実行を開始する（run-workflow-draft）。
• ワークフローのドラフトを公開する。楽観的同時実行制御と有効状態の設定を行い、開始モード（保存済みのトリガー、またはオンデマンドの場合は --manual）を指定する。
• ワークフローのドラフトを破棄する。
• ワークフローを一覧表示する。
• ワークフローの実行を一覧表示する。
• ワークフローの実行を確認する。
• アプリのトリガーを検出または一覧表示する。
• ワークフローをトリガーする。
• ワークフローの公開範囲を制御する。非公開ワークフローの作成、または現在の同等機能を含む。
• ワークフローのドラフトにアプリ接続をバインドする。
• 必要に応じて、アプリの実装／バージョンメタデータをバインドする。
• ワークフローのドラフトにトリガー設定を指定する。
• ワークフローの実行時またはトリガー時に入力を渡す。
• ワークフローのドラフト公開時に有効状態を制御する。

バンドルでは、ドラフトを通じて公開します。publish-workflow-draft はテスト済みのドラフトリビジョンを公開してドラフトを消費するため、古いドラフトが残りません。バンドルでは、publish-workflow-version による直接公開は行いません。バンドルの不変条件：未公開ドラフトを残したまま公開しないこと。

現在の SDK ヘルプ出力が明確な場合は、以下のコマンド例よりもそちらを優先してください。確認結果が曖昧な場合、または必須機能がないように見える場合は、互換性が未確認であると判断し、ワークフロースキルバンドルを更新してください。

検証済み SDK CLI のコマンド体系におけるコマンド例：

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

検証済み SDK CLI のコマンド体系におけるフラグの例：

• 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

ヘルプテキストで同じ必須バンドル機能が明確にサポートされている場合は、現在の同等のフラグやコマンド形式を使用してもかまいません。

ステップ 4：スキルを更新するか判断する

必須バンドル機能がすべて確認できた場合は、更新せずに続行するよう呼び出し元のスキルに伝えます。

必須機能が一つでも欠けている場合、または互換性を確認できない場合は、スキルの同期を保つため、ワークフロースキルバンドル全体を更新してください。

まずは標準的な day-2 更新手順を優先します。

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

skills update でインストール済みスキルが見つからない場合、誤ったスコープを更新する場合、またはその他の理由で失敗する場合は、正規の 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

スキルを更新したら、現在のスキル実行を終了します。エージェントのワークスペースを再読み込みし、元のリクエストを再実行するようユーザーに伝えてください。現在の実行で、すでに読み込まれている指示が変更されたと約束してはいけません。