netlify-ops

netlify-ops

概要

このスキルを使うと、エージェントはNetlifyのウェブホスティング操作をCLI優先（netlify CLI）で実行し、Netlifyの公式APIを使ったRESTフォールバックも利用できます。SDKは使用しません。CLIは使いやすい一般的な経路で（サイトの作成、ディレクトリのデプロイ、ステータスの確認）、REST APIは幅広い補完的な操作（カスタムドメイン、詳細な読み取り、DNS）を担います。エンドポイントインデックスと$refリゾルバーを介してバンドルされたOpenAPIを基盤とするため、仕様全体がコンテキストに読み込まれることはありません。エージェントは呼び出し元から注入されたトークンを受け取り、CLIコマンドまたはRESTオペレーションを選択して実行し、JSONを解析します。対象となるのはNetlifyの静的サイト／JAMstackおよびサーバーレスの機能であり、フルスタックのコンテナーホスティングではありません。

有効にするタイミング

• ✅ Netlify サイトを作成する場合、またはビルドをデプロイする場合（ドラフト／プレビュー、または--prod）。
• ✅ カスタムドメインを設定して確認する場合、またはサイトのDNSを構成する場合。
• ✅ デプロイステータス（stateフィールド）を確認する場合、またはサイト／デプロイの一覧表示や詳細確認を行う場合。

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

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

ワークフロー

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

呼び出し元がすでにアカウントを特定し、トークンを注入しています。トークンを使用してください。レコードを探したり、ログインしたりしないでください。Netlifyにはシークレットではないレコードフィールドがありません（ホストは固定で、アカウントID／メールアドレスはありません）。コンテキストから、機能（web-hosting）とトークンの変数名を受け取ります。その名前は、プロジェクトレベルの**.envファイルが存在し、その変数を定義している場合はその値として解決し、それ以外の場合は同じ名前の環境変数として解決します（プロジェクトの.envを優先）。トークンの値**はコンテキストの文章には含まれず、変数名だけが含まれます。スコープ解決やディレクトリ走査は行わないでください。対象はプロジェクトの.envであり、.envrcではありません。

トークンをNETLIFY_AUTH_TOKENに割り当てます（CLIはこれを読み取り、RESTフォールバックではAuthorization: Bearerを送信します）。netlify login／logoutは実行しないでください。契約の全文はreferences/credentials.mdを参照してください。

ステップ2 — 一般的な経路（CLI）か補完的な経路（REST）を選ぶ

• CLI（一般的な経路）： assets/cli-index.mdで、sites:create、deploy、status、sites:list、および回避策としてのnetlify api <operationId> --dataを確認します。詳細はreferences/cli-reference.mdを参照してください。
• REST（補完的な経路）： assets/endpoint-index.md（各オペレーションにつき1行）を確認してから、python3 scripts/endpoint.py <operationId>を実行し、パラメーター、本文、curlのひな形を解決します。詳細はreferences/rest-api.mdを参照してください。約690 KBの仕様全体をコンテキストに読み込まないでください。

ステップ3 — 実行する

優先度の高い操作には、同梱の次の4つのスクリプトを使用できます。

• create-site.sh <name> [account-slug] — netlify sites:create … --json（サイトを返します。IDはidフィールドです。--jsonではsite_idではなくidというキーになります。デプロイ時にはそのIDを--siteに渡します）。
• deploy.sh <site-id> <dir> [--prod] — netlify deploy --dir … --site … --json（デフォルトではドラフトをデプロイし、--prodを指定すると公開します）。
• set-custom-domain.sh <site-id> <domain> — RESTのPATCH updateSite（custom_domain）。
• deploy-status.sh <site-id> <deploy-id> — getSiteDeploy（stateフィールド）。

それ以外の操作では、cli-index.mdにあるCLIコマンド、または解決済みのRESTオペレーションに対するcurlを使用します。

ステップ 4 — レスポンスを処理する

• デプロイは非同期で、複数の段階があります。 deploy.sh の --json 出力からデプロイ ID（deploy_id / id フィールド）を取得し、deploy-status.sh に渡します。デプロイは building → uploading → processing → ready（または error）と進みます。state が終端状態になるまで deploy-status.sh（または getSiteDeploy）をポーリングします。ドラフトデプロイには固有のプレビュー URL が割り当てられ、--prod を指定するとライブサイトに公開されます。
• カスタムドメイン ≠ DNS です。 custom_domain を設定しても名前解決されるわけではありません。DNS 設定（configureDNSForSite / dns_zones レコード）も行ってください。
• エラー／制限： 非 2xx の JSON が返されます。レート制限は通常のリクエストが 500 req/min、デプロイは 3/min · 100/day です。X-RateLimit-* ヘッダーに従ってください。401 はトークンがないか、期限切れであることを意味します。

ルール

必須ルール（絶対に違反しないこと）：

• netlify login / netlify logout は絶対に実行しないでください。 認証には注入されたトークン（NETLIFY_AUTH_TOKEN または --auth）を使用し、CLI はヘッドレスで実行します。トークンがない場合は呼び出し側の重大なエラーであり、ログインを促す理由にはなりません。
• トークンの値を読み取ったり、表示したりしないでください。 $NETLIFY_AUTH_TOKEN（CLI 環境変数）または Bearer $NETLIFY_AUTH_TOKEN（REST）としてのみ参照してください。サブプロセスは環境からトークンを読み取ります。トークンは .env（gitignore 対象）または環境内にのみ存在します。
• REST 呼び出しを構築する前にスキーマを解決してください。 推測したフィールドセットではなく、$ref を解決したスキーマ（endpoint.py）からボディ／パラメーターを作成してください。
• 既知の site_id に --site を指定してデプロイしてください。 新しいチェックアウトには .netlify/state.json がありません。リンク状態に依存したり、--allow-anonymous を使用したりしないでください。
• CLI を優先し、残りは REST を使います。 作成／デプロイ／ステータス確認には CLI を使い、カスタムドメイン、DNS、詳細な読み取りには REST を使います。
• このスキルで認証情報を書き込むことはありません。 認証情報は呼び出し側から提供されます。

推奨事項（変更可能）：

• 非対話型で使うため、CLI に --json（機械可読出力）と --force（プロンプトをスキップ）を渡します。
• ボディを含む REST 書き込み（updateSite、createSiteDeploy）には、netlify api のエスケープハッチより、純粋な curl を優先してください（エスケープハッチのボディキー規約は未検証です）。パスパラメーターのみの操作では、エスケープハッチを使います。
• 手動実装のダイジェストプロトコルではなく、CLI の netlify deploy --dir を優先してください。SHA1 の差分検出とアップロードを処理してくれます。

注意事項

• ログインしないでください。 最も重大な契約違反は、トークンが「機能していない」ときに netlify login を実行することです。無効なトークンは報告すべきエラーであり、ログインを実行する理由にはなりません。
• --build ではなく --no-build を使います。 CLI はデフォルトでビルドを実行します。--build フラグはありません。ビルドを行わない場合は --no-build を指定してください。
• ドラフトと本番は異なります。 --prod を省略すると、ドラフト／プレビューのデプロイになります（固有の URL が割り当てられ、本番サイトには影響しません）。ライブサイトに公開するのは --prod を指定した場合のみです。
• キーとなるのは site_id です。 --name／--account-slug は人間向けの識別子です。すべての API 操作では、不透明な site_id（リンク後の .netlify/state.json 内）をキーとして使います。注意：sites:create --json では、この ID は site_id ではなく id で返されます（作成時の .site_id は null です）。作成出力から .id を読み取り、--site に渡してください。
• ダイジェストデプロイに必要なファイルの手順。 手動で実装した REST の createSiteDeploy は required 配列として SHA1 を返すため、その後アップロードする必要があります。この手順を省略すると、デプロイは ready に到達しません。CLI がこの処理を行います。
• カスタムドメインには DNS が必要です。 updateSite で custom_domain を設定できますが、DNS が設定されるまでドメインは名前解決されません。
• デプロイにはレート制限が適用されます。 3 deploys/min、100/day です。X-RateLimit-Remaining: 0 の場合は、時間をおいて再試行してください。
• state は自由形式の文字列です。 仕様にはデプロイ状態が列挙されていません。状態の一覧はドキュメントに基づくものとして扱い、実際のデプロイで確認してください。

アンチパターン

• netlify login を実行する。 禁止です。契約によってトークンが注入されます。独自に認証を解決したり、ユーザーにログインを促したりしないでください。
• トークンを表示する。 echo $NETLIFY_AUTH_TOKEN は絶対に実行せず、表示されるコマンドに貼り付けたり、値をファイルに書き込んだりしないでください。環境変数のみを参照してください。
• REST のリクエストボディを推測する。 endpoint.py で updateSite ／ createSiteDeploy を解決してください。記憶を頼りにボディを手書きしないでください。
• --site を指定せずにデプロイする。 新しいチェックアウトでリンク状態に依存すると、誤ったサイト（またはどのサイトにも）へ黙ってデプロイされます。必ず site_id を指定してください。
• --allow-anonymous を使う。 これは認証なしで申請可能なサイトを作成します。このスキルの手順ではありません。必ず注入されたトークンを使い、既知のサイトにデプロイしてください。
• 仕様全体を読み込む。 約 690 KB の OpenAPI を cat しないでください。インデックスを確認し、1 つの操作を解決してください。

出力

このスキルは CLI／API の副作用（要求された Netlify 操作）を発生させ、解析した JSON を呼び出し元のエージェントに返します。独自のファイルは書き込みません（呼び出し元から注入されたトークンを 消費する だけです）。デプロイの場合は、デプロイ ID、URL、最終 state を報告します。サイトの場合は、site_id と URL を報告します。読み取りの場合は、要求された JSON を返します。想定される利用者は、ウェブホスティング操作の実行を必要とする呼び出し元のエージェント（またはサブエージェント）です。シークレットが出力に含まれることはありません。

関連項目

• references/credentials.md — 認証情報の契約（名前で指定されたトークン → NETLIFY_AUTH_TOKEN、順序付き読み込みルール、ログイン禁止）。
• references/cli-reference.md — netlify CLI の機能と netlify api によるエスケープハッチ。
• references/rest-api.md — REST API の詳細、ダイジェストデプロイプロトコル、状態と制限。
• これは、プロバイダーごとのサービススキルパターンにおける github-cli-ops と同じ CLI 優先の兄弟スキルであり、atlassian-rest-ops と同じ OpenAPI 準拠の兄弟スキルです。

段階的な情報開示

詳細なコンテンツはサブフォルダーに置かれており、必要に応じて読み込まれます。

• references/credentials.md — 呼び出し元から注入されるトークン、順序付き読み込みルール、Bearer ブリッジ、ログイン禁止。ステップ 1 で読み込みます。
• references/cli-reference.md — CLI コマンド、エスケープハッチ、CLI の注意点。ステップ 2～3 で読み込みます。
• references/rest-api.md — REST のパターン、優先操作の表、ダイジェストデプロイプロトコル、状態と制限。REST の詳細が必要な場合に読み込みます。
• references/sources.md — 出典（公式 OpenAPI、CLI／API ドキュメント、2 つのソーススキル）と「実環境で確認」する項目。
• assets/cli-index.md — CLI コマンドのクイックリスト（ステップ 2）。
• assets/endpoint-index.md — REST 操作ごとに 1 行のインデックス（ステップ 2）。
• assets/netlify-openapi.json — 同梱の仕様（Swagger 2.0。リゾルバー経由で照会し、全体を読み込むことはありません）。
• scripts/endpoint.py + .validation.md — $ref を解決する python3 スクリプト（ステップ 2）。
• scripts/{create-site,deploy,set-custom-domain,deploy-status}.sh + .validation.md — 検証済みの 4 つの優先操作スクリプト。

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

これは、エージェントフロー以外で 人が手動でスキルを実行する場合の便宜を図るものであり、スキルの依存要件ではありません。スキルの規定契約は呼び出し元による注入（ステップ 1）です。この付録は手動実行者向けの手順にすぎません。

手動で実行するには、Netlify PAT（User → Applications → Personal access tokens）を作成し、その値を Git の追跡対象外である .env に保存して、CLI（npm i -g netlify-cli）をインストールした後、変数に値を設定します。

set -a; source .env; set +a                 # loads $NETLIFY_PROD_TOKEN, never prints it
export NETLIFY_AUTH_TOKEN="$NETLIFY_PROD_TOKEN"
bash scripts/create-site.sh my-site
bash scripts/deploy.sh <site-id> ./dist --prod

トークンの値は名前でのみ参照され、表示されることはありません。失効可能で有効期間の短い PAT を推奨します。

本文の上限

• description は 1,024 文字以下（agentskills.io の上限）。
• 本文は約 500 行／5,000 トークン以下です。毎ターンのコンテキストに保持されます。CLI／REST の詳細は references/ にあります。
• assets/netlify-openapi.json は大容量です（ディスク上で照会し、コンテキストには読み込みません）。