snowflake

Snowflake — 静的ページから EDS への変換

静的 HTML ページを EDS ページに変換し、元のデザインを維持しながら、Document Authoring でコンテンツを編集できるようにします。 次の 2 つの変換レベルに対応しています。

• ページレベル（オーバーレイ） — [data-slot] マーカーを含むテンプレートを使用し、元の DOM をバイト単位でそのまま保持します。テンプレート 1 つ、CSS ファイル 1 つ、スロットキー付きの行を含む DA ドキュメント 1 つで構成されます。
• ブロックレベル — 各コンテンツセクションを、独自の decorate() 関数と CSS を持つ独立した EDS ブロックにします。コンテンツは DA のブロックテーブルで編集します。ヘッダーとフッターは静的なフラグメントのままです。

どちらのレベルでも、元のデザインをそのまま維持します。ページレベルがより安全な既定値です。ブロックレベルはより標準的な EDS 出力になりますが、元のページで各セクションが独立している必要があります。

使用するタイミング

AI 生成の洗練された静的 HTML ページがあり、元のデザインを失わずにコンテンツを DA で編集できるようにして、Edge Delivery Services で公開したい場合に使用します。よくある表現：

• 「https://example.com/static-page を EDS に変換して」
• 「元のマークアップを維持したまま、このページを DA で編集できるようにして」
• 「このページを EDS ブロックに変換して」（level=block を示します）
• 「URL … の次の実験を開始して」
• 「… の静的ページから EDS へのオーバーレイ」（level=page を示します）

このスキルで対応しないこと

標準的な EDS ブロックへの書き換えを伴う移行には対応しません — その場合は page-import を使用します。Snowflake はソースのデザインを維持します。page-import は視覚的な忠実性を目標とせず、標準的な EDS ブロックパターンに書き換えます。3 つのアセット戦略に対応しています（knowledge/methodology.md §3 を参照）。 absolute、vendor、da-media。

パラメーター

パラメーター	値	既定値	説明
level	page、auto、check、block	page	変換レベル — 詳細は以下を参照

level の値

値	動作
auto	フェーズ 2 で実現可能性を分析し、推奨案を提示して、フェーズ 3 の前にユーザーの確認を求めます
check	実現可能性の分析のみを実行し、decisions.json にレポートを出力して、フェーズ 3 の前に停止します。バッチスキャンに便利です
block	ブロックレベルの変換です。分析は検証として引き続き実行され（decisions.json に書き込まれます）が、変換の実行条件にはなりません
page	ページレベルの変換（標準のオーバーレイ）です。分析は引き続き検証として実行されますが、変換の実行条件にはなりません

level が指定されておらず、ユーザーの表現から意図が読み取れる場合は、次のように判断します。

• 「EDS ブロックに変換」「ブロックレベル」 → level=block
• 「オーバーレイ」「DOM を維持」「snowflake overlay」 → level=page
• 中立的な表現 → level=page

使用例

/snowflake https://example.com/promo              → page-level; infer repo, daRoot, slug
/snowflake https://example.com/promo level=block  → block-level, infer the rest
/snowflake https://example.com/promo level=auto   → feasibility analysis decides
/snowflake level=check                            → feasibility scan only (asks for URL)
/snowflake                                        → page-level, fully interactive

ソース URL は先頭に指定する位置引数であり、唯一の必須引数です。それ以外はすべて自動的に解決され、作業を始める前に確認用の要約としてまとめて提示されます。

スキルの依存関係

Snowflake は、da-content スキルの DA HTML ルールと DA 管理 API の仕様を参照します。Snowflake と一緒に da-content を読み込んでください。 フェーズ 3（生成）とフェーズ 5（ラウンドトリップ）では、このスキルを直接参照します。

前提条件

必須 — スキル単独では解決できない唯一の入力です。

1. ソース URL — 変換する静的ページです。アクセス可能である必要があります （一般公開されているか、ローカルの開発サーバーで公開されていること）。

自動解決 — 作業を開始する前の一括確認用として、初期化の概要に表示されます。

2. 対象の EDS リポジトリ — gh repo view --json nameWithOwner で検出し、 失敗した場合は git remote get-url origin の解析にフォールバックします。オーバーレイエンジンがすでに 組み込まれている必要があります（knowledge/architecture.md の「Solution shape」を参照）。存在しない場合はフェーズ 0 でインストールします。
3. DA ルートパス — .snowflake/config.json の daRoot キーが設定されていればその値を使用し、 そうでなければ現在の Git ブランチ名（スキルがコードに使用するブランチと同じ）をデフォルトとして使用します。概要に表示され、インラインで上書きできます。
4. 変換レベル — 表現から推定します（「Parameters」を参照）。推定できない場合は page になります。概要に表示され、インラインで上書きできます。
5. スラッグ／テンプレート名 — ソース URL から導出されます（ケバブケース、 30 文字以下）。概要に表示され、インラインで上書きできます。

認証チェック（ブロックなし） — DA トークンを $DA_TOKEN → ~/.aem/da-token.json の順に解決します。ステータスは初期化の概要に表示されます。フェーズ 1～4 では不要です。呼び出し時にトークンがない場合は、フェーズ 5（ラウンドトリップ）の実行前に da-auth スキルを呼び出してください。

初期化

呼び出しのたびに、エージェントはフェーズ 0 に入る前に次の手順を実行します。

1. 入力を解決 — 上記の「前提条件」セクションにある高速パスのルールを適用します。

2. 基盤を調査 —

   node <SKILL_DIR>/scripts/install-substrate.mjs --dry-run
   

   結果（何もしない／クリーンインストール／ドリフト／カスタムコード検出）を記録します。

3. DA トークンを確認 —

   DA_TOKEN=$(node -e "
     const fs = require('fs');
     const p = process.env.HOME + '/.aem/da-token.json';
     try {
       const t = JSON.parse(fs.readFileSync(p, 'utf8'));
       if (t.expires_at > Date.now() + 60000) process.stdout.write(t.access_token);
     } catch {}
   ")
   

   ブロックなし — 概要に表示するステータスのみを記録します。

4. 各フェーズの開始前に、実行パラメーターを必ず表示します。すべての値が事前に指定されている場合や、曖昧さなく推定できた場合でも、この概要を必ず表示してから、確認を待たずに直ちに続行します。

   Source URL : https://example.com/promo   ← required (provided)
   Target repo: acme/my-site                ← detected from git
   DA root    : /main                        ← from current branch
   Level      : page                        ← default
   Slug       : promo                       ← derived from URL
   Substrate  : clean install — 9 files     ← (or: already current ✓)
   DA token   : cached ✓                    ← (or: not found — needed at Phase 5)
   

   よくあるケース（新規インストール — snowflake 基盤がまだなく、置き換えられたファイルはバックアップ済み）では、一時停止せずに続行します。以前の snowflake 基盤から差分が生じたドリフトの場合のみ一時停止します。上書きによって意図的なカスタマイズが失われる可能性があるためです。このケースはフェーズ 0 で処理します。

5. 続行 — フェーズ 0 → 1 → … → 6 の順に実行します。

クイックスタート — 最初から最後までの例

対象の EDS リポジトリのルートから実行する、7 つのフェーズにわたる変換全体の簡略版です。 phases/ 以下の各フェーズファイルにプロンプトの完全版があり、ここにはエージェントが出力する実際のコマンドの 構成を示します。

# Inputs (resolved during init, confirmed in the summary)
SOURCE_URL="https://example.com/promo"
PAGE_SLUG="promo"
DA_ROOT="/main"                       # defaults to current branch name
NNN=001                           # next run number
PROJECT=".snowflake/projects/${NNN}-${PAGE_SLUG}"
TEMPLATE_NAME="promo"
LEVEL="page"                      # page | auto | check | block

# Phase 0 — install (or verify) the overlay substrate (once per repo)
node "<SKILL_DIR>/scripts/install-substrate.mjs"

# Phase 1 — capture: fetch source + assets into the project folder
mkdir -p "$PROJECT/input"
curl -fsS "$SOURCE_URL" -o "$PROJECT/input/index.html"
# For JS-rendered pages, use a browser to get the fully rendered HTML instead

# Phase 2 — analyze: produce decisions.json (sections, slots, asset
# strategy, head-links, conversionLevel). Includes block-level
# feasibility assessment. If LEVEL=check, stop here.
# Driven by phases/2-analyze.md.

# Phase 3 — generate: produce 5 artifacts + DA-source body
# (templates/<tpl>.html, fragments/<tpl>/{header,footer}.html,
# styles/<tpl>.css, scripts/<tpl>-animations.js, da/<slug>.html).
# Driven by phases/3-generate.md.

# Phase 4 — wire: copy artifacts to EDS-served paths and build the
# drafts file. Driven by phases/4-wire.md.

# Phase 5 — round-trip: local dev server + production preview
npx -y @adobe/aem-cli up --html-folder drafts &
TOKEN="${DA_TOKEN:-$(jq -r .access_token ~/.aem/da-token.json)}"
git checkout -b "snowflake-${NNN}" && git add . && git commit -m "snowflake #${NNN}"
git push -u origin "snowflake-${NNN}"
curl -X PUT -H "Authorization: Bearer $TOKEN" \
  -F "data=@${PROJECT}/output/da/${PAGE_SLUG}.html;type=text/html" \
  "https://admin.da.live/source/${OWNER}/${REPO}${DA_ROOT}/${PAGE_SLUG}.html"
curl -X POST -H "Authorization: Bearer $TOKEN" \
  "https://admin.hlx.page/preview/${OWNER}/${REPO}/snowflake-${NNN}${DA_ROOT}/${PAGE_SLUG}"
# Verify at https://snowflake-${NNN}--${REPO}--${OWNER}.aem.page/${DA_ROOT}/${PAGE_SLUG}

# Phase 6 — reflect: append findings to $PROJECT/learnings.md;
# promote cross-project rules to knowledge/learnings.md.

<SKILL_DIR> は、この SKILL.md を含むディレクトリの絶対パスです。エージェントは呼び出し前にこの値を置き換えます。ホストごとの解決ルールについては HOST-NOTES.md を参照してください。

7 つのフェーズ（順次実行）

各フェーズは、実行可能な bash + Node を含む自己完結型の Markdown ファイルです。 エージェントはフェーズのプロンプトを読み、手順を実行し、プロジェクトルートの state.json （<projectsDir>/<NNN>-<slug>/state.json）を更新してから、 次に進みます。再実行しても安全です。フェーズは完了済みの作業をスキップします。

0. 前提条件 — オーバーレイ基盤をインストール／検証し、 .snowflake/config.json に設定を記録します。リポジトリごとに 1 回実行します。 phases/0-prereq.md を参照してください。

1. 取得 — ソース HTML と参照されている外部アセットを取得し、 プロジェクトフォルダーを作成します。 phases/1-capture.md を参照してください。

2. 分析 — 構造マップを作成します。ヘッダー／フッターの境界、セクション リスト、スロットの候補、移動する head レベルのリンク、アセット戦略を含みます。 ブロックレベルの実現可能性評価も実行します — knowledge/block-level-feasibility.md を参照してください。 ページ複雑度ゲートも含まれます。セクションが 8 個を超える、またはスロット化可能な要素が 100 個を超えるページは、 コンテンツ抽出が不完全になるのを避けるため、ページレベルからブロックレベルへ自動的に切り替わります（phases/2-analyze.md を参照）。 notes.md と decisions.json（conversionLevel を含む）を生成します。 phases/2-analyze.md を参照してください。

3. 生成 — フェーズ 2 の conversionLevel に応じて分岐します。

   • page：5 つのオーバーレイ成果物（テンプレート HTML、 ヘッダーフラグメント、フッターフラグメント、ページ CSS、アニメーション JS） と、スロットキー付きの行を含む DA ソースの本文を生成します。
   • block：セクションごとのブロック JS／CSS、ヘッダー／フッター フラグメント、グローバルスタイル／トークン、標準ブロックテーブルを含む DA ソースの本文を生成します。
   • hybrid：合格したセクションにはブロックレベルを、基準を満たさないセクションにはページレベルの フラグメントを使用します。 page と block はどちらも、いずれの基盤 フレーバー（eds または milo）でもサポートされます。Milo 固有の差分（chrome メタデータ、ページレベル／ブロックレベルの生成、--pa-* アニメーション サイドカー、配線）はすべて、 assets/substrate-milo/FLAVOR.md に記載されています。 各フェーズのドキュメントには、条件付きでこのドキュメントへの参照があります。コアスキルは基盤に依存しません。 phases/3-generate.md を参照してください。

4. 配線 — 成果物を EDS が配信するパスにコピーし、ローカルテスト用の drafts ファイルを作成して、lint を実行します。 phases/4-wire.md を参照してください。

5. ラウンドトリップ — まずローカル（開発サーバー）、次に本番（ブランチ作成 + push + DA PUT + プレビュー API）で実行します。どちらにもブラウザー健全性ゲートを適用します。ページが描画され（空白でなく）、オーバーレイが適用され、ソースの構造と一致し、コンソール／ネットワークエラーがなく、1:1 の DOM 等価性チェックに合格してから、処理を続行できます。 phases/5-roundtrip.md を参照してください。

6. 振り返り — 実行で得られた知見を追記し、プロジェクト横断の学びを knowledge/learnings.md に反映します。イテレーションは 終了しません — 終了するかどうかはユーザーが決めます。 phases/6-reflect.md を参照してください。

フェーズごとのナレッジ解決： 各フェーズはまず .snowflake/knowledge/<file>.md（プロジェクト固有のオーバーライド）を試し、 次に <SKILL_DIR>/knowledge/<file>.md（同梱の標準版）を試します。 競合する場合はプロジェクトのオーバーライドが優先されます。

読み込み順序

必要なフェーズが始まるときにのみ、必要な知識を読み込みます。

呼び出し時（Phase 0 の前）：

1. このファイル。
2. knowledge/methodology.md — フェーズの規則の正本です。
3. da-content スキルを読み込み可能であることを確認します（Phase 3 と 5 で必要です）。

Phase 2（分析）： 4. knowledge/block-level-feasibility.md — ブロックレベル変換とページレベル変換の判定基準です。

Phase 3（生成）： 5. knowledge/architecture.md — オーバーレイエンジンとスロットライターの動作仕様です。 6. knowledge/block-level-conversion.md — ブロックレベル変換のアーキテクチャとパターンです。 7. knowledge/learnings.md — 生成に関連するプロジェクト横断の知見です。

Phase 5（ラウンドトリップ）： 8. knowledge/eds-da-mechanics.md — EDS パイプラインのオーバーレイ実行環境に関する知見です。 9. knowledge/learnings.md — メディア処理、CORS、スクロールアニメーションの癖に関する項目（すでに読み込んでいる場合を除く）。

その後、Phase 0 から開始します。

参考資料（エージェントは読み込みません）

• README.md — 人間向けの概要、インストールコマンド、コントリビューションガイドラインです。
• HOST-NOTES.md — ホストごとのアダプターに関する注記（Slicc、Claude Code、汎用シェル）、<SKILL_DIR> のパス解決ルール、.snowflake/ ディレクトリの規約、およびホスト間で使用が禁止されているプリミティブ（メンテナー向け）です。
• examples/README.md — 完了したイテレーションの実例へのリンクです。