Communityコーディング&開発github.com

静的サイト公開(GitHub Pages)

データから依存関係ゼロの静的なHTML/CSS/JSサイトを生成し、ヘッドレスブラウザで検証した後、GitHub Pagesで公開します。Cloudflareカスタムドメイン設定(CNAME、プロキシ無効)もサポートします。

静的サイト公開(GitHub Pages) とは?

このスキルは、AIエージェント(Claude Code、Cursor、Codexなど)が、ユーザーから提供されたデータ(リスト、ギャラリー、ダッシュボード、ポートフォリオなど)をもとに、完全に自己完結型の静的サイトを生成・検証・公開するためのワークフローを提供します。ターゲットは1〜数百アイテムの単一作者向けページで、ビルドツールやフレームワークを一切必要としません。主な特徴は、(1) データの取得・HTML生成・ブラウザ検証・GitHub Pages公開を自動化するスクリプト群、(2) カスタムドメイン設定(Cloudflare CNAMEレコード作成、DNS only(プロキシ無効)、GitHub PagesのEnforce HTTPS有効化)のサポート、(3) 検証ステップでは実際のChromeヘッドレスブラウザでスクリーンショットを撮りクリックテストを実行、(4) 再利用性を考慮したテンプレート(検索・ソート機能付き)を提供します。著作権やアクセス制限、DNSの外部影響に注意する倫理ルールも含まれています。

対応~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/JamesDAdams/my-skills/tree/HEAD/.apm/skills/static-site-publish

Installed? Explore more コーディング&開発 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

静的サイト → GitHub Pages

完全なワークフロー:データ → 自己完結型HTML/CSS/JSページ → ブラウザ検証 → GitHub Pages公開。

対象:1〜数百アイテムのページ、単一作者、実行時の依存関係ゼロ。

使用するタイミング

はいいいえ
「このリスト/テーブルでページを作って」「ギャラリー」「データダッシュボード」バックエンド、認証、データベースが必要なアプリ → 事前に相談
「GitHub / GitHub Pagesで公開して」フレームワーク(Next, Astro, Hugo)で生成されたサイト → フレームワークのフローに従う
既存ページのデータ(タイトル、日付、価格…)の再現第三者のデザイン/CSS/HTMLのコピー → 拒否し、独自デザインを提案

絶対ルール

  1. オリジナルデザイン。 第三者のCSS、HTML、アセットを決してコピーしない。情報構造にインスパイアされるのはOK。デザインを流用するのはNG。
  2. 事実はOK、著作物はNG。 タイトル、日付、価格、評価、リンク = 事実データ、再利用可能。編集テキスト、説明文、ビジュアル = 保護対象:コピーしない。画像は、コミットする代わりに元のCDNにホットリンクする(reference/data-and-ethics.md参照)。
  3. アクセス制限を尊重する。 robots.txtでクローラー禁止、Cloudflare/botチャレンジ → 迂回しない。公式API、キー、または単なる外部リンクにフォールバックする。
  4. 「完了」と言う前に必ず実ブラウザで検証(スクリーンショット+クリックテスト)。
  5. リポジトリ名/アカウントが曖昧な場合は確認なしに公開しない。
  6. 確認なしにカスタムドメインを作成しない。 ユーザーが指定していない場合は、Cloudflareリダイレクトを希望するかどうか、どのドメインかを尋ねる(ステップ6)。サブドメインを勝手に作ったり、独自に作成したりしない:DNSは外部に見える副作用である。

ワークフロー

1. フレーミング(30秒)

  • どんなデータか、アイテム数、1回限りか定期的な更新か?

  • 期待される出力:1ページ?ソート/検索?どのようなビジネス表示ルールか?

  • 公開先:GitHubアカウント、リポジトリ名、公開/非公開(Pagesは無料アカウントでは公開リポジトリが必要)。

  • カスタムドメイン — 指定がない場合は明示的に尋ねる。 一度に質問し、デフォルトの提案を含める:

    Cloudflareリダイレクトを <owner>.github.io(CNAME、プロキシ無効)に設定しますか? はいの場合、どのサブドメイン/セクションですか?

    スキル側では名前は自由ですが、ドメインは作成された瞬間から公開されます:明示的な回答なしには何も作成しない。ユーザーが「いいえ」と答えた場合は、URL https://<owner>.github.io/<repo>/ で終了し、DNSエントリは作成しない。

2. データ取得

1回のスクリプト実行 → data.json = 信頼できる単一情報源、レンダリングとは分離。

python3 fetch_data.py     # → data.json

ポリシー:リクエスト間に0.3〜0.7秒、明示的なUser-Agent、429/5xxでリトライ。 詳細と注意点(PoW Anubis、Cloudflare、曖昧マッチング、キーなしAPI):reference/data-and-ethics.md。

3. ページ生成

テンプレートから開始、白紙から始めない:

cp .dsh/skills/static-site-publish/templates/{index.html,styles.css,script.js} ./site/
cp .dsh/skills/static-site-publish/templates/build.py ./site/   # data.json → index.html
python3 ./site/build.py
  • build.py:データをカードグリッドに注入する小さなPythonジェネレーター(f-string + html.escape)。データに対するJSランタイムは不要。
  • styles.css:デフォルトのダークテーマ、auto-fill minmax()グリッド、CSS変数。
  • script.js:ページを開いたときにインスタント検索+ソート+表示ルールを計算(再ビルド不要でページを最新に保つため)。
  • 表示時に計算できるもの(ステータス、相対日付)はJSで行う:サイトを毎日再構築する必要がなくなる。
  • HTMLはJSなしでも読めるようにし、JSはプログレッシブエンハンスメントとする。

4. 検証

.dsh/skills/static-site-publish/scripts/verify-site.sh ./site/index.html

Chromeヘッドレスでページを開き、/tmp/site-shot.pngに書き込み、クリック重なりテストを実行する。スクリーンショットを確認(read_imageツール)してから結論を出す。 チェックリスト:デスクトップ+モバイルレンダリング、データ完全(アイテム数をカウント)、リンク正しい、重なりなし。

5. 公開

.dsh/skills/static-site-publish/scripts/publish-gh-pages.sh ./site マイレポ名

スクリプト:gh auth status → git init/commit → gh repo create --source --push → gh api POST /pages → URLが200を返すまでポーリング → 最終URLを表示。

Pagesの遅延は20〜90秒:200を確認する前に「動かない」と結論づけない。gh api repos/{owner}/{repo}/pages/builds/latest --jq .status = builtも確認する。

6. カスタムドメイン+Cloudflare

ユーザーが要求した場合のみ(ステップ1参照)。DNSは公開:AIが「はい」を曖昧なドメイン名に再解釈しない。

必須の順序:DNSが先、証明書が次、Enforce HTTPSが最後。 サイトはすでに *.github.io で200を返している必要がある。

a. CloudflareでのDNSリダイレクト(MCP Cloudflare)

前提トークン:スコープ zone.read + dns.write(Zone Read / DNS Edit)。不足している場合は、停止して拡張を依頼する — 迂回しない。

  1. GET /zones?name=<ルートドメイン> → zone.id。ゾーンが0の場合:そのドメインはこのアカウントにない、確認する。
  2. GET /zones/{zone_id}/dns_records?name=<FQDN> → 同じCNAMEが既に存在する場合は、何も再作成しない(冪等性)。
  3. POST /zones/{zone_id}/dns_records:
{ "type": "CNAME", "name": "<サブドメイン>", "content": "<owner>.github.io",
  "proxied": false, "ttl": 1 }
  • proxied: false = DNS only、譲歩不可:CloudflareプロキシはGitHubが証明書を発行するのを妨げる。
  • ターゲットは <owner>.github.io、末尾スラッシュなし、リポジトリ名なし(jamesdadams.github.io、.../mon-repoではない)。
  • ttl: 1 = Auto。
  1. APIだけでなく、公開解決で確認:
dig +short <fqdn> CNAME @1.1.1.1   # → <owner>.github.io.
dig +short <fqdn> A @1.1.1.1       # → 185.199.108-111 .153

b. GitHub Pages側のドメイン+Enforce HTTPS

.dsh/skills/static-site-publish/scripts/set-pages-domain.sh <owner>/<repo> <ドメイン> ./site

スクリプト:サイトに CNAME ファイルを書き込み(再デプロイ後も持続し、ドメイン消失を防止)→ PUT /repos/{owner}/{repo}/pages を cname で実行 → https_certificate.state = approved を待機 → https_enforced: true を有効化。

⚠️ https_enforced: true は、証明書が存在するまで400を返す。実際の遅延:CNAME作成後5〜20分。そのためスクリプトは失敗せずにループする。発行前に手動で「Enforce HTTPS」にチェックを入れないこと、そしてこの期間中に失敗と結論づけないこと。

c. 最終確認

curl -sI https://<ドメイン>/ | head -5      # 200 + ヘッダー server: GitHub.com

次に、ブラウザでページを再度開く(ステップ4)カスタムURLで:200は、相対パス(styles.css、script.js)が解決することを保証しない — これがドメインルートで提供されるプロジェクトページの典型的な落とし穴である。

7. 更新を可能にする

  • Gitフォルダをユーザーのプロジェクトフォルダに配置する(/tmpでは再起動で消去される)。
  • README.mdに文書化:データの出典、抽出の再実行方法、固定データと動的データ(JSで計算されるルール)の区別。
  • 自動更新されないことをユーザーに明示的に伝える。

既知の落とし穴

症状原因修正
403「Just a moment…」Cloudflareチャレンジ制限を文書化、公式APIか外部リンク;迂回を試みない
「Making sure you're not a bot」でページが切り詰められるPoW Anubisチャレンジを解決(reference参照)か、ユーザーにエクスポートを依頼
セレクタが全アイテムに対して0件を返す間違ったパターン(例:/games/lib/genre: vs /games/lib/popular/genre:)HTMLのサンプルを出力し、ループ前に1ページで正規表現をテスト
カードクリックで正しいリンクが開かない<a>レイヤーが子要素のpositionで覆われている装飾要素に pointer-events: none;elementFromPointでテスト
GitHub Pagesが最初の数分で404ビルド中最大90秒ポーリング
ある列のデータが空ソース側のラベルが変動(「Released」vs「Early Access」)寛容なパターン+アイテムごとのログ、決して無言の except: pass をしない
https_enforced が400「certificate does not exist」証明書がまだ発行されていないhttps_certificate.state = approved を待つ(5〜20分)、スクリプトはループする
30分後もカスタムドメインが404CNAMEがない/所有者が間違っている/リポジトリに CNAME ファイルがないdigでCNAMEを確認、set-pages-domain.shを再実行
プロキシ有効化後にHTTPSが壊れるレコードがProxiedになっているDNS only(proxied: false)に戻す、GitHub証明書はプロキシ経由では検証できない
「Domain is already in use」そのドメインがすでにアカウント内の別のリポジトリで宣言されているカスタムドメインはリポジトリごとに1つ;再割り当て前に古い方を解放
カスタムドメインでCSS/JSが404だが *.github.io/repo/ ではOKproject pageがルートで提供されているのに絶対パス(/styles.css)を使用相対パス(styles.css)を使用

参考

  • reference/data-and-ethics.md — 抽出、PoW Anubis、Cloudflare、ライセンス、画像のホットリンク
  • reference/design-and-verify.md — 最小限のデザインシステム、ブラウザテスト、アクセシビリティ
  • reference/publish-gh-pages.md — ghコマンド、命名、ドメイン、トラブルシューティング
  • scripts/publish-gh-pages.sh — 公開+Pages有効化
  • scripts/set-pages-domain.sh — カスタムドメイン+Enforce HTTPS(Cloudflare CNAME後)
  • scripts/verify-site.sh
  • templates/{index.html,styles.css,script.js,build.py}

関連スキル