web-technique-to-skill

Web Technique to Skill

説明文ではなく、動作するコードから始めます。振る舞いを説明する記事やプロンプト集がソースなら、article-prompts-to-skills を使います。自分で作ったものがすでに動作し、その知識がまだ1つのファイルに閉じ込められているなら、こちらを使います。

スキル1つにつき、仕組みを1つ抽出します。うまくできたページには、たいてい複数の仕組みが含まれています。それぞれを別々にパッケージ化しないと、個々の仕組みが薄まってしまいます。

これは、すべての Web 技法スキルに適用する継続的な品質基準です。作成時も改訂時も、このスキル自体を監査してください。作業を通じて忠実度に関するルール、失敗モード、パッケージ化の制約、検証手順に不足が見つかった場合は、子スキル内だけで解決するのではなく、同じ範囲の変更でこの基準も更新してください。

仕組みを1文で名付ける

何かを書く前に、その1文を書きます。取り除いたら、効果が機能しなくなる唯一の要素です。書けないなら、それは見た目にすぎず、仕組みではありません。つまり、まだスキルにはなりません。

その1文が、その後のすべてを決めます。葉が落ちる動きなら、「葉がエッジオンの状態を横切り、その瞬間にほとんど見えなくなることで、目には葉として認識される」です。つまり、スプライトの絵、配色、夜の風景はすべて演出であり、落下する動きこそがスキルです。

確かめるには、頭の中で対象、配色、レイアウトを変えてみます。その文が変わらず成り立つなら、それが仕組みです。意味が通じなくなるなら、名付けたのは演出です。

デモに名前を付け、技術スタックを明示する

目に見える h1 とブラウザーの <title> には、具体的な技法名を使います。Wisps、Cursor Ripples、Liquid Metal Border、Scroll-scrubbed Word Reveal などです。抽象的な仕組みの説明で、対象を隠さないでください。「あらゆる速度で描画」は振る舞いを表しますが、デモの内容は伝わりません。

検証済みの実装経路を、タイトルのすぐ上か下に記載します。次の項目を順番に明記します。

1. ランタイムまたはフレームワーク：Vanilla JavaScript、React、Vue
2. レンダラーまたはブラウザー API：Canvas 2D、WebGL、DOM/CSS、SVG
3. 該当する場合は技法レイヤー：GLSL shaders、Three.js、GSAP、ScrollTrigger

「インタラクティブな実験」や「モーションの研究」ではなく、Vanilla JavaScript · Canvas 2D や Three.js · WebGL · GLSL と記載します。見た目から推測してはいけません。ソース内のインポート、レンダラーの構築、コンテキストの作成を検証してください。getContext('2d') は Canvas 2D であり、シェーダーではありません。WebGLRenderer と ShaderMaterial の組み合わせなら、Three.js、WebGL、GLSL です。より複雑なスタックと誤解される可能性がある場合は、使っていない技術を明記します。WebGL、シェーダー、Three.js は使用していません。

効果とインターフェースのスタックが異なる場合は、分けて記載します。Canvas 2D と CSS の両方がパーティクルを描画するかのように並べるのではなく、Vanilla JavaScript + Canvas 2D によるエフェクト、CSS によるインターフェース と記載します。どの技術が技法を生み出し、どの技術がコントロールのレイアウトだけを担うのか、読者に分かるようにしてください。

承認済みの参照見出しをレイアウトの忠実度のために維持する必要がある場合は、その見出しを残し、技法名とスタックをブラウザータイトル、および参照デザインにすでにあるキッカー、コントロールパネル、または副ラベルに記載します。最初の画面で実装内容が明確に分かる状態にしてください。

仕組みと演出を分ける

ソースの各要素を次の3つに分類し、最初のものだけを残します。

分類	含める場所	例
仕組み	スキル	数学的処理、状態モデル、順序の制約、予算
演出	デモのみ	配色、コピー、画像、ページレイアウト、ブランド
付随要素	どこにも含めない	セレクター名、フォントの選択、一度きりのアセットパス

再利用可能な仕組みをスキル本文に記載する際は、プロジェクト固有のセレクターと付随的なアセットパスを取り除きます。デモでは、承認済みの参照演出を維持します。同じブランド、配色、タイポグラフィー、構図、アセットの配置、雰囲気、動きの階層を保ってください。デモで教える内容と操作できる範囲を絞って技法を切り分け、別のビジュアル世界を作り出さないでください。

各ルールを、それによって防げる不具合に結び付ける

正しい形容詞ではなく、誤った結果を明記してください。不具合を具体的に示すルールは検証できますが、そうでないルールは飾りにすぎません。

• 弱い例：「自然な雰囲気になるよう、パーティクルの回転に変化を付けます。」
• 強い例：「回転をタンブル角度から駆動し、位相を90度ずらします。独立したサイン波を使うと、揺れに見えたり、イージングの不具合に見えたりします。」

何が問題になるかを具体的に言えないなら、別の方法を試したことがない可能性が高く、そのルール自体が実在しないかもしれません。そのルールを削るか、実際に確かめてください。

形容詞ではなく数値を記載する

実際に採用した定数を記載してください。「控えめ」では使いようがありませんが、0.3–0.5 なら、調整の出発点になります。

レイヤーや状態ごとの範囲、タイミングとイージング、サイズと間隔、予算（dt のクランプ、DPR の上限、インスタンス数）、そして量どうしのトレードオフを示す式を記載してください。値を感覚ではなく測定によって調整した場合は、何を測定したかも記してください。

3つ以上のパラメーターが連動して変化する場合は、文章より小さな表を使ってください。

コストのかかる落とし穴を残す

最も価値のあるルールは、コードを読んでも再導出できず、解決に何時間もかかるものです。たいていは次のいずれかです。

• 色空間 — エディターでは適切に見えるのに画面上では違って見える値。途中で何かがデコードやトーンマッピングを行っています。
• レイアウトのタイミング — 一度だけ計測し、すでにレイアウトが完了している場合にしか正しく動作しないコード。解決策は待ち時間を延ばすことではなく、オブザーバーを使うことです。
• スタッキングと合成 — 3つ上の祖先要素が作ったコンテキストのせいで、他の要素より前面に出せない要素。
• 順序 — 個別には正しい2つの操作が、順序を誤ると問題を起こします。
• プラットフォーム固有の挙動 — あるエンジンでは、プロパティが何も起こさずに無視されます。

これらは症状を先に示し、独立したルールとして記述してください。そうすれば読者は、いま目の前にある不具合だと気付けます。

冒頭で適用範囲を明確にする

最も近い既存のスキルを挙げ、代わりにそちらを使うべき状況を示してください。作業を始める前に agent-skills/*/*/SKILL.md を検索してください。すでにスキルがその仕組みを扱っている場合は、よく似たものを新たに追加するのではなく、そのスキルを拡張してください。

適用範囲が明記されていない「パーティクルを追加する」スキルが2つあっても、適切に選ばれることはありません。

アクセシビリティとライフサイクルを組み込む

Web デザインのスキルでは、これらは付録ではなく、仕組みの一部です。

• prefers-reduced-motion: reduce の場合は、デザインされた静止画を表示してください。エフェクトを隠してはいけません。構図はエフェクトを含めて作られています。コントロールは有効なままにし、操作に応じて動作するようにしてください。
• document.hidden のときと、セクションがビューポートから外れたときは一時停止してください。再開時に時間の基準をリセットし、最初のフレームで一時停止中の時間すべてを積分しないようにしてください。
• dt を約1/30秒にクランプしてください。デバイスのピクセル比は2を上限にしてください。
• ResizeObserver からサイズを取得し、ビューポートがゼロの場合はビルド処理を行わないようにしてください。
• コントロールには実際のフォーム要素を使い、キーボードで操作可能にしてください。フォーカスを見えるようにし、変更を知らせるライブリージョンも用意してください。

コストを正直に伝える

実際にコストがかかるものを明記し、断言する前に測定してください。推測せずにプロファイリングしてください。重そうに見える部分が、実際にはボトルネックではないことがよくあります。本当のボトルネック、効果の高い低コストな調整、そして影響しないものを挙げてください。

最小のコストで最大の効果が得られる調整を報告してください。パーティクルを再利用するフィールドでは、数を増やすよりスポーン帯を狭めるほうが効果的です。画面上の密度は、数 ÷ 面積だからです。

デザインの由来を記録する

SKILL.md に、由来を1行で記載してください。元のプロジェクトと、そこでその仕組みが何をしていたかを示します。読者は、そのスキルが自分に適用できるかどうかを、仕組みが使われていた背景から判断します。「文字の上でも読みやすさを保つ必要があった、暗い WebGL の京都の夜景シーンから抽出」のほうが、どんなに説明を重ねるよりも伝わります。

デモはその由来元の見た目にしてください。下の**「デモを演出する」**を参照してください。残してよいのは、自分が所有していないものだけです。クライアント名やブランド名、ライセンスフォント、購入した画像や第三者の画像などが該当します。それらを置き換え、それ以外はすべて再現してください。

デモを適切に演出する

デモは、ほとんどの読者が目にする唯一の証拠です。 読者がソースプロジェクトを読むことはなく、この1つのファイルを見て技術を評価します。十分に検討されたページに実装された仕組みでも、テスト用ハーネスのように見えるもので示されれば、未完成だと受け取られます。そして、未完成に見えるスキルを使おうとする人はいません。

つまり、デモに求められる完成度は、コードサンプルではなく、元の制作物の完成度です。

• 承認済みのリファレンスは、着想の源ではなく合格基準として扱います。 分離した仕組みを取り巻く、最初のフレーム、レイアウトの幾何学的な構成、配色、タイポグラフィの処理、アセットのスケール、雰囲気、動きの階層を同じように再現します。コーディングの前に、レイヤーごとに棚卸しを行います。デモを開いた人が、その名前を読む前に元の制作物をすぐに見分けられるようにしてください。
• リファレンス自体のアセットは、それらを生成するコードを移植して使います。 元の制作物が空、月、テクスチャ、シルエットを生成しているなら、それらの関数を変更せずに移植します。手作業で作ったCSSによる、手続き型生成の月の近似は、本物の海とクレーター地形がある月の隣では平坦な円盤に見えます。並べた瞬間に、その差は明らかです。生成処理を移植しても静止時のコストはなく、デモを自己完結した単一ファイルに保てます。また、単に似せるのではなく、本当に同じ演出にできます。
• 忠実な再現に必要な、自分が権利を持つリファレンスアセットは、技術とともに持ち込みます。 デモに必要なローカルアセットだけを最小限コピーし、出所を記録します。1ファイルに収めることよりも、正確に再現することを優先します。自己完結していても元の制作物に合わない近似より、持ち運び可能なローカル一式のほうが優れています。ただし、自分が権利を持たないものは持ち込んではいけません。クライアントのブランド、ライセンス付きフォント、購入した画像、サードパーティのメディアなどが該当します。
• スクロールや操作を行う前に、最初の画面で仕組みを見せます。 要点を見るのにクリックが必要なら、見せ方が適切ではありません。
• 仕組みが時間やスクロールにまたがる場合は、状態遷移全体を検証します。 冒頭のフレームでは世界観を示し、その演出を担うものを見せる必要がありますが、それだけでは複数シーンにわたる展開を証明できません。作成した各キーステートに加え、順方向、逆方向、高速スキップ、スクロール途中からの再読み込みの各経路を比較します。ヒーロー部分が完璧でも、第3章が壊れていては問題です。
• レイアウトを決めるリファレンスの文言は維持します。 見出しや本文を変えると承認済みの構成が変わる場合は、文言をそのまま保ち、技術名、検証済みのスタック、仕組みの説明を、ブラウザータイトルと、リファレンスにすでにある補助パネル、コントロール、マイクロコピー、アクセシブルな説明に記載します。説明的な見出しのために視覚的な忠実度を犠牲にしてはいけません。ただし、何の実装か分からない状態にはしないでください。
• 統一感のある系列にします。 同じリファレンスから2つの技術を取り出すなら、デモも兄弟のように見える必要があります。リファレンスを共有するデモのコレクションは一連の制作物として受け取られます。一方、それぞれが独自の世界を作るコレクションは、寄せ集めに見えます。

Canvas 2D の軌跡を単位距離ごとに生成する場合の、文言の例を示します。

Vanilla JavaScript · Canvas 2D

ウィスプ

距離に応じて生成する Canvas 2D パーティクルにより、手を動かす速さが変わっても間隔は一定です。CSS はインターフェースのスタイル設定のみに使います。生成方法をタイマーに切り替えると、同じジェスチャーでも粒子がばらけます。素早く動かすと点が散らばり、手を止めると同じ場所に積み重なります。WebGL、シェーダー、Three.js は使用しません。

タイトルでエフェクトを示します。キッカーでスタックを特定します。本文では仕組みと、失敗する場合、そして実装上の曖昧さになりそうな点を説明します。本文で言及したコントロールが画面に表示されるため、読者は説明を確かめられます。

• 1画面につき、アイデアは1つにします。 3つのことを証明しようとするデモは、どれも証明できません。
• 重要な状態を示すコントロールは、実際のフォーム要素として用意し、システムが固定値ではなくパラメーター化されていることを示します。すでに見えている内容を言い換えるだけのコントロールは省きます。

品質基準

以下の項目は、毎回すべて満たしてください。

• 最大と最小のステップを慎重に定めた、意図的なサイズスケールを設定します。ブラウザーのデフォルト設定は使いません。
• 一貫したリズムで余白を配置します。
• 意味を持つアクセントカラーを1色に絞り、控えめなパレットを使います。
• フォーカス状態も含め、すべてのインタラクティブなコントロールにスタイルを設定します。
• 具体的な手法のタイトルと、検証済みのランタイム、レンダラー、主要な手法ライブラリを最初の画面に表示します。
• 実際にありそうなプロジェクトから、具体的で実在感のあるコピーを使います。「カードタイトル」や「デモセクション」は使いません。
• 正確な参照元で可能な場合は、自己完結型のファイルを1つだけ使います。そうでない場合は、リモートのランタイム依存なしで、所有するアセットだけを含む最小限のローカルバンドルを使います。
• 390pxから1440pxまで対応し、セマンティックなHTML、見えるフォーカス、両端の幅でエラーのないコンソールを実現します。

抽出元のページと並べたときに見劣りするデモは、完成していません。

ブラウザーで検証してから報告する

ファイルを読んだだけで、見た目や操作性について断言してはいけません。実際に動かして確認します。

1. デモを1440×900と390×844で読み込みます。
2. 表示されるタイトルに手法が記載されていること、スタックの説明がソースのインポート、レンダラー、コンテキストの作成方法と一致することを確認します。
3. 主要なインタラクションを試し、状態が実際に変化することを確認します。
4. スクロール、タイムライン、または複数状態の手法では、作成されたすべての状態を順方向と逆方向にたどり、継ぎ目をまたいで素早くスキップし、0以外の状態で再読み込みします。
5. Tabキーで順に移動し、フォーカスが見えていて、順序が正しいことを確認します。
6. 動きを減らす設定での動作を実行し、描画が合成され、アニメーションが停止することを確認します。
7. 両方の画面サイズでコンソールにエラーがないことを確認します。
8. リポジトリで共通の寸法を使ってプレビューをキャプチャします。
9. ソースとデモをソースのビューポートで横に並べて比較します。複数状態の手法では、代表的なすべての主要状態を比較します。個別のエフェクトを磨き込む前に、階層、クロップ、スケール、配置、雰囲気の構造的なずれを修正します。

この確認で問題が見つかることを前提にしてください。見つかった場合は、基準を緩めず、デモを修正して再実行します。

パッケージ化してコミットする

agent-skills/<category>/<skill-name>/
  SKILL.md
  agents/openai.yaml
  demo/
    index.html
    PROMPT.md
    preview.jpg
    reference.*        # optional owned staging required for exact fidelity

SKILL.mdは命令形で記述し、フロントマターにはnameとdescriptionだけを含めます。すべてのトリガーフレーズはdescriptionに記載します。demo/PROMPT.mdには、最小限のプロンプト、デモの再現、リミックス用プロンプトの3つの見出しを設けます。リミックスでは、仕組みと予算を維持しながら、題材、パレット、構成を変更します。

新しいフォルダーと、そのフォルダーに必要なギャラリーの行だけをステージングします。コミットする前にgit diff --cached --statを確認し、既存の変更済みファイルには手を加えないでください。

検証

• 主語、パレット、レイアウトを変更しても、仕組みを説明する文が成立する
• 表示されるタイトルは、抽象的な仕組みの説明ではなく、技法を示している
• 最初の画面に、検証済みのランタイム、レンダラーまたはブラウザー API、主要な技法ライブラリが記載されている
• ステージングの内容はデモにあり、スキル本体にはない
• すべてのルールで、防止する不具合が明記されている
• 定数は形容詞ではなく、実際の数値である
• コストの大きな落とし穴は、症状を先にして記述されている
• 最も近い既存スキルとの境界が、冒頭で明示されている
• 出典情報は、元プロジェクト名を記した一行の説明になっている
• デモは、同じパレット、書体、構成、雰囲気を備え、参照元だとすぐに分かる
• 参照元のビューポートでソースとデモを並べて比較し、構造上のずれが残っていない
• 参照元独自のジェネレーターを移植するか、コードを切り分けるのが現実的でない場合は、所有権を持つ最小限の参照アセットを同梱している
• 所有権のないものが持ち込まれておらず、デモは単一ファイル、または必要性を説明できる最小限の所有アセットのバンドルとして提供されている
• 同じ参照元のデモが、互いに一貫した印象になっている
• デモ内のコピーで仕組みを説明し、それが防ぐ不具合を明記している
• スクロールや操作をする前に、最初の画面で仕組みを示している
• スクロール、タイムライン、複数状態を伴う仕組みを、すべての重要な状態、逆方向、高速なスキップ時、深い位置での再読み込み後に検証している
• 元になったページの隣に置いても、見劣りしないデモになっている
• 文字の段階、間隔のリズム、パレットが意図的に設計され、デフォルトのままではない
• モーション低減時に、要素を隠すのではなく、デザインされた静止画を表示する
• コストに関する主張は、推測ではなく測定に基づいている
• 両方のブレークポイントでブラウザー上でデモを動作させ、コンソールにエラーがないことを確認している
• 新しいスキルのフォルダーだけがステージングされている