cloudflare-pages-ops

cloudflare-pages-ops

概要

このスキルを使うと、エージェントはCloudflare Pagesの操作をCLI優先（Wrangler CLI）で実行し、Cloudflareの公式APIに対するRESTでのフォールバックも利用できます。SDKは不要です。一般的な操作（プロジェクトの作成、ビルドディレクトリのデプロイ）には使いやすいWranglerを使用し、包括的な補完操作（カスタムドメイン、デプロイのステータス、プロジェクト／デプロイ／ドメインの管理）にはREST APIを使用します。バンドルされたPages OpenAPIの一部を、エンドポイントインデックスと$refリゾルバーを介して参照するため、仕様全体がコンテキストに読み込まれることはありません。エージェントは呼び出し元から注入されたaccount_idとトークンを受け取り、WranglerコマンドまたはREST操作を選んで実行し、結果を解析します。Cloudflare Pagesの静的サイト／JAMstackとサーバーレスの機能を操作します。フルスタックのコンテナーホスティングには対応しません。

有効化するタイミング

• ✅ Pagesのプロジェクトを作成する、またはビルドディレクトリをプロジェクトにデプロイする（Direct Upload）。
• ✅ カスタムドメインを追加／一覧表示する、またはデプロイのステータス（ステージの状態遷移）を確認する。
• ✅ プロジェクト、デプロイ（再試行／ロールバック）、ドメインを一覧表示／確認／削除する。

次の場合は有効化しないでください：

• フルスタックのコンテナ／アプリのホスティング（Render、Fly.io、Railway、VercelのSSR-as-PaaS）が必要な場合。ここで扱うCloudflare Pagesは、静的サイト／JAMstackとサーバーレスのホストのみです。
• 必要なのが認証情報の設定だけの場合。認証情報は呼び出し元から提供されます。このスキルは認証情報をプロビジョニングしたり解決したりせず、wrangler loginも実行しません（references/credentials.mdを参照）。

ワークフロー

ステップ1 — 注入された認証情報を受け取る

呼び出し元はすでにアカウントを解決し、この操作に必要な情報を注入しています。これを使用してください。レコードを探したり、ログインしたりしないでください。コンテキストから次の情報を受け取ります。

• account_id（非シークレットのプレーンなコンテキスト値。CLOUDFLARE_ACCOUNT_IDとしてエクスポートされ、RESTパスに埋め込まれます）と、機能（web-hosting）。
• 順序付きの読み込みルールに従ったトークン。コンテキストには変数の名前が含まれます。その値は、プロジェクトの.envファイルが存在し、変数が定義されていればその値、そうでなければ同じ名前の環境変数です（プロジェクトの.envが優先されます）。トークンの値はコンテキストの文章には含まれず、変数名のみが含まれます。スコープの解決やディレクトリの検索は行わないでください。対象はプロジェクトの.envであり、.envrcではありません。

CLOUDFLARE_API_TOKEN（Bearer）とCLOUDFLARE_ACCOUNT_IDに渡します。wrangler loginは絶対に実行しないでください。契約の詳細はreferences/credentials.mdを参照してください。

ステップ2 — 一般的な操作（Wrangler）か補完操作（REST）を選ぶ

• Wrangler（一般的な操作）： assets/cli-index.mdを確認し、pages project create、pages deploy、pages project list、pages deployment list/tailを探します。詳細はreferences/wrangler.mdを参照してください。
• REST（補完操作）： assets/endpoint-index.mdを確認し、次にpython3 scripts/endpoint.py <operationId>を実行して、パラメーター、本文、curlのひな形を解決します。詳細はreferences/rest-api.mdを参照してください。バンドルされた仕様の一部をコンテキストに読み込まないでください。

ステップ3 — 実行する

優先度の高い操作は、バンドルされた次の4つのスクリプトで実行できます。

• create-project.sh <name> [branch] — wrangler pages project create … --production-branch …（Direct Uploadプロジェクト）。
• deploy.sh <project> <dir> [branch] — wrangler pages deploy … --commit-dirty true（ビルド済みディレクトリをアップロードします）。
• add-custom-domain.sh <project> <domain> — RESTのPOST …/domains（Wranglerにはドメイン用のコマンドがありません）。
• deployment-status.sh <project> <deployment-id> — RESTのget-deployment-info（ステージの状態遷移）。

それ以外の場合は、cli-index.mdにあるWranglerコマンド、または解決したREST操作に対するcurlを使用してください。

手順 4 — レスポンスを処理する

• まずデプロイ ID を取得してください。 deploy.sh（Wrangler）が出力するのはテキストのみで、deployment-status.sh が必要とする ID は出力されません。wrangler pages deployment list --project-name <name> --json | jq -r '.[0].Id' で取得してください（deployment list --json が返すテーブルのキーは大文字始まりのため、.id ではなく .Id です）。
• デプロイは非同期で、段階的に進みます。 デプロイは latest_stage.name ∈ queued/initialize/clone_repo/build/deploy、status ∈ success/idle/active/failure/canceled の状態を順に進みます。deploy ステージの status: success（完了）になるか、いずれかのステージが failure になるまで deployment-status.sh をポーリングしてください。
• HTTP だけでなくエンベロープを確認してください。 すべての REST レスポンスは {success, errors, messages, result} です。200 でも success: false の場合があります。errors[].code/message を確認してください。
• カスタムドメインと DNS は別物です。 ドメインを追加するには、Cloudflare ゾーンにそのドメインを設定し、DNS をプロジェクトに向ける必要があります。
• 制限： ユーザーあたり 5 分間に 1,200 リクエストです。超過すると HTTP 429 が返されます。

ルール

絶対に守るルール（違反禁止）：

• wrangler login は絶対に実行しないでください。 認証には注入された CLOUDFLARE_API_TOKEN と CLOUDFLARE_ACCOUNT_ID を使用し、Wrangler はヘッドレスで実行します。トークンまたは account_id がない場合は呼び出し元の重大なエラーであり、ログインを促すものではありません。
• トークンの値を読み取ったり、出力したりしないでください。 $CLOUDFLARE_API_TOKEN（環境変数または Bearer）としてのみ参照してください。サブプロセスは環境変数から読み取ります。トークンは .env（gitignore 対象）または環境変数にのみ保存されます。account_id は秘密情報ではなく、コンテキスト情報です。
• ディレクトリのデプロイには curl ではなく Wrangler を使ってください。 REST の create-deployment のボディは multipart/form-data です。ディレクトリのデプロイを curl で手作業で組み立てないでください。
• REST 呼び出しを構築する前に、スキーマを解決してください。 $ref を解決したスキーマ（endpoint.py）からボディ／パラメーターを作成し、フィールドを推測して使わないでください。
• HTTP だけでなく success を確認してください。 success:false を伴う 200 は失敗です。errors[] を確認してください。
• このスキルは認証情報を書き込みません。 認証情報は呼び出し元が提供します。

推奨事項（上書き可能）：

• 機械処理用の出力を得るには、wrangler pages project list／deployment list に --json を渡してください。
• 未コミットのツリーからデプロイする場合は、--commit-dirty true を指定してください。
• カスタムドメインとデプロイごとのステータスには REST を使ってください（Wrangler にはそれらのコマンドがありません）。

注意点

• ログインしないでください。 トークンが「機能しない」ときに wrangler login を実行するのは、この取り決めに違反します。無効なトークン／account_id はエラーとして通知するものであり、ログインして解決するものではありません。
• ヘッドレス実行では CLOUDFLARE_ACCOUNT_ID が必須です。 Wrangler にはトークンとともにこれが必要です。account id の不足は CI で最もよくある失敗です。
• デプロイはマルチパートです。 REST のデプロイエンドポイントは multipart/form-data（バイナリパート）です。wrangler pages deploy <dir> を使い、デプロイを JSON で POST しないでください。
• Direct Upload と Git-connected は異なります。 wrangler pages deploy が動作するのは Direct-Upload プロジェクトです。Git-connected プロジェクトは git push でデプロイされ、Wrangler ではデプロイできません。（Direct-Upload プロジェクトを後から Git に切り替えることはできません。）
• エンベロープに失敗が隠れていることがあります。 {success:false} が 200 とともに返される場合があるため、必ず確認してください。
• カスタムドメインには DNS が必要です。API は DNS を作成しません。 add-custom-domain.sh はドメインを登録するだけです（status: initializing）。REST の POST /domains は、同じアカウントのゾーンであっても DNS レコードを作成しません（自動作成するのはダッシュボードのみです）。ゾーンに CNAME <domain> -> <project>.pages.dev が存在するまで、検証は「CNAME record not set」のまま保留されます。また、Pages スコープのトークンではそのレコードを作成できません（Zone DNS:Edit が必要です）。そのため、呼び出し元が別途追加してください。
• pages deploy <dir> はアップロードするだけで、ビルドはしません。 すでにビルド済みの出力ディレクトリ（dist／build／…）を渡してください。Wrangler はフレームワークのビルドを実行しません。
• レート制限があります。 ユーザーあたり 5 分間に 1,200 リクエストの累積制限です。429 が返された場合は、バックオフしてください。

アンチパターン

• wrangler login の実行。 禁止されています。コントラクトによってトークンが注入されるため、自分で認証を解決したり、ユーザーにログインを求めたりしないでください。
• トークンの表示。 echo $CLOUDFLARE_API_TOKEN は絶対に実行せず、表示されるコマンドに貼り付けたり、値をファイルに書き込んだりしないでください。環境変数のみを参照してください。（account_id は秘密情報ではないため、パスに含めてもかまいません。）
• REST でディレクトリのデプロイを手作業で実装すること。 デプロイはマルチパート形式です。Wrangler を使用してください。
• REST の本文を推測すること。 endpoint.py で create-project／add-domain を解決してください。記憶を頼りに本文を手書きしないでください。
• HTTP ステータスだけを信頼すること。 success:false を含む 200 は失敗です。errors[] を確認してください。
• 仕様全体を読み込むこと。 バンドルされたスライスを cat しないでください。インデックスを確認し、1 つの操作を解決してください。（10 MB の Cloudflare OpenAPI 全体を取得することも絶対に避けてください。）

出力

このスキルはCLI／API の副作用（要求された Cloudflare Pages 操作）を実行し、解析した結果を呼び出し元のエージェントに返します。独自のファイルは書き込みません（呼び出し元から注入された認証情報を使用するだけです）。デプロイの場合はデプロイ ID、URL、最終ステージのステータスを報告し、プロジェクトの場合はプロジェクト名／ID、URL を報告します。読み取りの場合は要求された result を返します。抽象的な利用者は、ウェブホスティング操作の実行を必要とする呼び出し元のエージェント（またはサブエージェント）です。秘密情報が出力に含まれることはありません。

関連項目

• references/credentials.md — 認証情報のコントラクト（コンテキストから取得する account_id ＋名前で指定したトークンから CLOUDFLARE_API_TOKEN を設定、順序付き読み込みルール、ログイン不要）。
• references/wrangler.md — Wrangler の Pages 機能と、対応していない内容。
• references/rest-api.md — REST の残りの操作、エンベロープ、デプロイのステージ遷移、制限事項。
• これは github-cli-ops の CLI 優先版であり、atlassian-rest-ops／netlify-ops と同じく OpenAPI を基盤とする、プロバイダーごとのサービススキルパターンの一部です。

段階的な開示

詳細な内容はサブフォルダーに置かれており、必要な場合にのみ読み込まれます。

• references/credentials.md — 呼び出し元から注入される account_id とトークン、順序付き読み込みルール、Bearer への橋渡し、ログイン不要。ステップ 1 で読み込みます。
• references/wrangler.md — Wrangler コマンド、Direct Upload と Git の使い分け、CLI の注意事項。ステップ 2～3 で読み込みます。
• references/rest-api.md — REST パターン、優先操作の表、エンベロープ、デプロイのステージ遷移、制限事項。REST の残りの操作で読み込みます。
• references/sources.md — 出典（バンドルされた Pages スライスと公式ドキュメント）および「ライブで確認」する項目。
• assets/cli-index.md — Wrangler のクイックコマンド一覧（ステップ 2）。
• assets/endpoint-index.md — REST 操作ごとの 1 行の説明（ステップ 2）。
• assets/cloudflare-pages-openapi.json — バンドルされた Pages OpenAPI スライス（リゾルバー経由で照会し、全体を読み込むことはありません）。
• scripts/endpoint.py と .validation.md — $ref を解決する python3 スクリプト（ステップ 2）。
• scripts/{create-project,deploy,add-custom-domain,deployment-status}.sh と .validation.md — 検証済みの優先操作スクリプト 4 つ。

単独での使用（任意、必須ではありません）

これは、エージェントのワークフロー外で人が手動でスキルを実行する場合の便宜のためのものであり、スキルの依存関係ではありません。スキルの規範的なコントラクトは呼び出し元による注入（ステップ 1）です。この付録は、手動で操作する場合の橋渡しにすぎません。

手動で実行するには、スコープを限定したトークンを作成し（My Profile → API Tokens → Create Token、Cloudflare Pages: Edit）、値を Git で無視される .env に保存し、Wrangler をインストールして（npm i -g wrangler）、その後、自分で変数に値を設定します。

set -a; source .env; set +a                 # loads $CLOUDFLARE_PAGES_TOKEN, never prints it
export CLOUDFLARE_ACCOUNT_ID="<account-id>"
export CLOUDFLARE_API_TOKEN="$CLOUDFLARE_PAGES_TOKEN"
bash scripts/create-project.sh my-site main
bash scripts/deploy.sh my-site ./dist

トークンの値は名前でのみ参照し、表示することはありません。取り消し可能で、有効期間の短いスコープ付きトークンを使用してください。

本文の予算

• description は1,024文字以下（agentskills.ioの上限）。
• 本文は約500行／5,000トークン以下にします。毎ターンのコンテキストに含まれるため、Wrangler／RESTの詳細は references/ に記載します。
• assets/cloudflare-pages-openapi.json は Pages のスライスです（ディスク上で参照し、コンテキストには読み込みません）。