html-artifacts

HTML アーティファクト

Markdown はエージェントの出力形式としてデフォルトです。しかし、数文を超える内容には適していません。2 つの選択肢を横に並べたり、実際の図を描いたり、操作可能にしたり、ページとして共有したりできないからです。アーティファクトそのものが成果物である場合、読者はそれを使います。注意深く読み、共有し、実装担当者に渡し、編集内容を貼り戻します。HTML にしましょう。

このスキルは、形式を切り替えることではなく、判断することです。以下の内容のほとんどは、適切に判断して結果を確認することについてです。モデルはすでに HTML の書き方を知っているからです。

次のいずれかに当てはまる場合は HTML を選びましょう

• 比較。 読者が比較検討する必要のある選択肢が 2 つ以上ある場合。縦に並べるより、横に並べるほうが適しています。
• 空間情報。 差分、コールグラフ、モジュールマップ、フローチャート、タイムライン、変更前と変更後など。配置そのものに意味があります。
• 操作性が重要。 イージングカーブ、パラメーター調整、状態マシン、シミュレーションなど。読者が実際に「体感」する必要のあるものです。
• リファレンス資料。 非線形に移動して読む資料。タブ、折りたたみ、余白の用語集、ページ内リンクなどです。
• 色や階層が意味を持つ。 重大度、ステータス、構文、デザイントークン、データ系列などです。
• データ。 12 個を超える数値、傾向、分布など。並べ替えやフィルターができる表、またはグラフが適しています。
• 一時的なエディター。 読者がチケットをドラッグしたり、フラグを切り替えたり、プロンプトを調整したりして、その結果をテキストとして戻す必要がある場合です。
• 共有する予定がある。 リーダー向けの仕様書、レビュアー向けの PR の説明、チーム向けのレポートなどです。人はページを読み、ファイルは流し読みします。
• 長さ。 Markdown が約 100 行を超えると、ナビゲーションやレイアウトの価値が出てきます。

次の場合は Markdown のままにしましょう

• 返答が会話形式、または数文の回答である場合。質問 1 つに回答 1 つで完結します。
• 出力がコード、設定ブロック、コマンド列、またはユーザーが適用する差分である場合。
• ユーザーが使い捨ての内容について迅速に反復している場合（「このファイルを簡単に要約して」「この関数の動作を教えて」など）。
• ドキュメントが git に保存され、PR で継続的に差分を確認する場合。HTML の差分はノイズが多くなります。レビューに役立つ場合は、HTML の ビュー もあわせて提案してください。
• ユーザーが Markdown、特定の形式、または「書式なし」を指定した場合。

迷ったら、自分に 1 つだけ問いかけてください。読者は一度読むだけでなく、その後に何かするでしょうか？ そうでなければ Markdown です。HTML はトークンを 2～4 倍消費し、時間もかかります。必要のない用途を作り出さないでください。

共通ルール

すべての成果物は、以下のすべてを満たす必要があります。

1. 自己完結した単一の .html ファイル。 CSS は <style> に、JS は <script> に記述し、画像はインライン SVG またはデータ URI にします。ビルド手順は不要です。外部スクリプトは、対象のサーフェスで許可されている CDN（references/harness-mechanics.md を参照）からのみ読み込み、本当に必要なライブラリに限ります。
2. 5 秒で内容が伝わること。 <title>、見出し、そして内容に入る前の概要説明文または TL;DR を 1 段落用意します。
3. Markdown をそのまま置き換えたものではなく、実際のレイアウトにすること。 比較には列を使います。タイムラインは図示します。差分は差分として表示します。ページが見出しと段落だけなら、Markdown にすべきです。
4. 標準で見やすく仕上げること。 落ち着いたタイポグラフィ、1 行あたり 60〜75 文字、意味を伝える控えめな色使いにします。グラデーションのヒーロー、絵文字の見出し、目的のないカードグリッドは避けます。references/matching-your-style.md に基本の CSS と避けるべき特徴の一覧があります。
5. スマートフォンの幅と両方のテーマで動作すること。 viewport meta を設定し、相対単位と折り返し可能なレイアウトを使用します。:root にライトテーマのトークンを定義し、prefers-color-scheme: dark と [data-theme="dark"] の両方で再定義して、システム設定と手動切り替えのどちらにも対応します。
6. アクセシビリティの基本を満たすこと。 セマンティック要素、ラベル付きコントロール、キーボードで操作できるインタラクション、視認できるフォーカスを用意し、色だけを手がかりにしないでください。チェックリストは references/accessibility-and-print.md を参照してください。
7. 編集内容をテキストに戻せること。 これは必須です。状態を操作できる要素には、「Markdown / JSON / プロンプトとしてコピー」を必ず用意します。この往復が重要です。
8. 納品前に検証すること。 ブラウザー（Claude Code、Cowork、またはクラウドセッションでの Playwright や Chromium）が使える場合は、ファイルをヘッドレスでレンダリングし、デスクトップ幅とスマートフォン幅でスクリーンショットを撮り、コンソールエラーを確認して、見つかった問題を修正します。ブラウザーが使えない場合（Claude.ai のチャット、アーティファクトのみのサーフェス、シェルがない環境）は、作業を止めたり謝罪したりせず、代わりに references/verify-before-delivering.md の読み合わせチェックリストを実行してから納品します。どちらの場合も、ユーザーに見せる前に成果物を一度確認します。

ワークフロー

1. 決める。 上記の 2 つのリストを確認します。何を作るのか、なぜ HTML にするのかを 1 行で伝えます。
2. 参考資料を選ぶ。 以下のインデックスから該当するファイルを読みます。短い資料です。依頼が複数のカテゴリにまたがる場合は、2 つ読んでください。
3. ユーザーのスタイルに合わせる。 プロジェクトにデザインシステム、トークン、またはフロントエンドデザインのスキルがあれば、それを使います。なければ references/matching-your-style.md の基本設定を使います。
4. 作成する。 まずレイアウト、次に内容、最後にインタラクションを作ります。ユーザーが提供したデータはあらかじめ入力しておきます。
5. 検証する。 ルール 8 に従います。問題を修正してから、ファイルのパスまたは成果物と、それが何であるかを示す 1 文を添えて納品します。

カテゴリー索引

リクエストの内容…	参照先…
選択肢の比較、実装計画、方針を決める前の方向性の検討	references/exploration-and-planning.md
注釈付き差分、PR の説明、コードレビュー、モジュールマップ、「このコードを説明して」	references/code-review-and-pr.md
デザイントークン、コンポーネントシート、モックアップ、アニメーションとインタラクションのプロトタイプ	references/design-and-prototypes.md
インライン SVG の図、フローチャート、アーキテクチャ図	references/diagrams-and-illustrations.md
グラフ、ダッシュボード、並べ替え・フィルター可能なデータテーブル、メトリクス	references/data-and-charts.md
ステータスレポート、インシデントの事後分析、概念の解説、学習教材	references/reports-and-research.md
スライドデッキ、矢印キーで操作するプレゼンテーション	references/decks.md
単発のエディター：トリアージボード、フラグの切り替え、プロンプト調整ツール、ラベラー	references/custom-editors.md
既存のビジュアルスタイルやデザインシステムに合わせる場合、安全なデフォルト	references/matching-your-style.md
アクセシビリティと印刷のチェックリスト	references/accessibility-and-print.md
ファイルの保存先と各サーフェスで許可される内容：Claude Code、Claude.ai artifacts、Cowork、公開された artifacts	references/harness-mechanics.md
納品前のチェック：ヘッドレスと手動	references/verify-before-delivering.md

出力の仕組み（簡単な説明）

• ディスク上（Claude Code、Cowork、クラウドセッション）： 作業ディレクトリに説明的な名前の .html ファイルを kebab-case で保存し、検証してから、ユーザーにパスと開き方を伝えます。関連する成果物は1つのフォルダーにまとめます。
• Claude.ai artifacts： 指示がない限り、React ではなく単一の HTML artifact を作成します。artifact のサンドボックスを守ります。利用可能な CDN のみを使い、ストレージは信頼できないものとして扱い、相対リンクは使いません。
• 公開または共有する artifacts： 実行時の機能（永続化、ライブデータなど）を備えている場合があります。そのサーフェスのドキュメントで確認できる場合にのみ使用し、機能があると決めつけないでください。

各サーフェスの詳細は references/harness-mechanics.md を参照してください。

このスキルの対象外

常に HTML で回答するというものではありません。Markdown のほうが適切な場合は Markdown を使ってください。見栄えの悪い HTML は良質な Markdown よりも劣り、検証していない HTML はどちらにも劣ります。