プレビュー：範囲選択コメント付き HTML ページ

あらゆる計画、提案、草稿、完成稿を、「範囲選択 → コメント」ができる HTML に変換し、ユーザーのコンピュータで開いてレビュー（またはクライアントへの提出）を可能にします。確認後、「すべてコピー」を押せば、コメントとチェック結果が Markdown になって返り、会話に貼り付けて修正に使えます。

このスキルのファイルはどこにあるか

このファイルが置かれているフォルダがスキルフォルダです（以下 $SKILL_DIR と表記）。コマンド実行前に設定してください：

SKILL_DIR="${CLAUDE_SKILL_DIR:-$HOME/.claude/skills/preview}"
[ -f "$SKILL_DIR/scripts/md-to-preview.py" ] || SKILL_DIR="$(cd "$(dirname "$(find "$HOME/.claude/skills" .claude/skills -path '*/preview/scripts/md-to-preview.py' 2>/dev/null | head -1)")/.." && pwd)"
echo "$SKILL_DIR"

必要なのは Python 3.9 以上のみ。標準ライブラリだけで動作し、pip install は不要。
macOS では python3、Windows で python3 コマンドがない場合は python または py を使ってください。
スキルフォルダが見つからない場合は処理を停止し、ユーザーに preview フォルダが ~/.claude/skills/ 以下にあるか確認してもらってください。自分で別のコメント機能を実装しないでください。

ファイル	用途
`scripts/md-to-preview.py`	メインジェネレータ：md → プレビューページ
`scripts/convert/inject.py`	既にレイアウト済みの HTML にコメント機能のみ追加
`scripts/convert/visuals.py`、`flow.py`、`tables.py`	図解コンポーネント、フローチャート、テーブル変換（ジェネレータが自動呼出）
`assets/preview-comment-overlay.html`	範囲選択コメント UI
`assets/preview-tokens.css`	色、フォント、余白の調整用。外観を変えたい場合はここを編集
`assets/fonts/`	バンドルフォント：Noto Sans TC、Geist、Geist Mono（SIL OFL ライセンス）
`assets/example.md`	完全なサンプル：架空の案件提案書。全コンポーネント使用例

ルール 1：コメントは常に「範囲選択式」

ユーザーが「コメント追加」「コメント可能なバージョン」と言った場合、それは Google Docs のように「任意の文字列を範囲選択 → コメント」を意味します。各段落の横にインプットボックスを置く方式ではありません。このスキルのコメント UI は範囲選択式ですので、そのまま使用し、別途実装しないでください。

ルール 2：まず書き換え、次にページ生成

ページタイプの分類

タイプ	例	処理方法
説明型	計画、提案、レポート、比較、決定を仰ぐページ	以下のルールに従って読みやすいバージョンに書き換えてからページ生成。作業原稿をそのままジェネレータに渡さない
原文レビュー型	契約書、完成原稿、書き起こし、クライアント原稿	本文は一文字も変えず、`--no-lint` を付けてページ生成。最大でも先頭に `> [!結論]` で「このページの目的」を追加するのみ

説明型の書き方

最初の画面で結論を伝える：先頭に > [!結論] で結論を一行、続けて > [!要你決定] で読者がすべきことをリストアップ。背景は後ろに回し、スクロールしなくても判断できるように。
同じことは一度だけ：結論枠で言ったことは本文で言い換えない。図表で示したことは段落で繰り返さない。「まとめ」セクションは作らない。
平易に：読者が普段使う言葉で。専門用語は初出で比喩を使うか、> [!白話]（平易な説明）で補足。
図で示せるなら書かない：まず「この部分はどんな関係性か」を考え、下の表からコンポーネントを選ぶ。テキスト段落は最大3行。各 ## セクションには最低1つの図解コンポーネントまたは表を入れる。
短く：一文に一つのポイント。言い換え表現（「つまり」「換言すれば」「注目すべきは」など）は削除。
削るのは重複、情報は削らない：数字、日付、名前、結果は絶対に削らず、変更もしない。

図解コンポーネント一覧

数行の簡易記法で記述します。図はジェネレータが描画します。区切りは全角 ｜、矢印は → を使用。完全な記法は assets/example.md 参照。

説明したい内容	コンポーネント	記法
旧 vs 新、現在 vs 改善後	対照表	```対照：最初の行 `現在 → 改善後`、以降 `項目｜旧 → 新`
システム構成、データフロー	構造図	```架構：一行一階層 `階層名｜箱、箱`、階層内の順序は `甲 → 乙`、階層間は `↓ 説明` 行を挿入
いつ何が起こるか	タイムライン	```時間軸：一行 `時刻｜タイトル｜説明`。行頭 `✅` は完了、`👉` は現在
順序・手順・因果	手順図	```步驟：一行 `タイトル｜説明`、自動採番。4つ以下は横並び、5つ以上は縦並び
いくつかの重要な数字	数字カード	```数字：一行 `数字単位｜ラベル｜注釈`。数字と単位の間に空白があると単位が小さく表示
複数案、役割分担、並列項目	カード	```卡片（または `選項`、`分工`）：一行 `タイトル｜一行｜一行`。行頭 `★` は推奨案
多項目比較	表	通常の md テーブル。ヘッダに「現在／旧」と「改善後／新／提案」が同時にある場合、旧列はグレー、新列は薄緑になる
分岐のあるフロー	フローチャートカード	ASCII または mermaid の flow 図（graph/flowchart の TD/LR）。変換に失敗した場合はそのまま表示
結論・決定事項・注意・リスク	強調ボックス	`> [!結論] タイトル`、次の行から `> 内容`。使用可能：結論、要你決定、注意、風險、完成、白話、說明
ステータス	色ラベル	インライン `{綠:完了}` `{黃:待機中}` `{紅:停止}` `{藍:進行中}` `{灰:やらない}`
一文の中のキーワード	強調線	`==キーワード==`、一文に最大1箇所

色には固定の意味があります：青＝結論・情報、緑＝完了・改善後、黄＝注意・待機、赤＝リスク・停止。「要你決定」はページ内に1つだけ。
記法が間違っていてもページは壊れず、灰色のコードブロックとして表示されるだけ。生成後、図になるべきものが灰色のままになっていないか確認。
順序や因果がある場合は手順図・タイムライン、互いに独立している場合はカードを使用。
図内の文字も実際のテキストなので、範囲選択コメントが可能。

レイアウトチェック

ページ生成時に自動で「レイアウトチェック」が実行されます。先頭に結論ボックスがない、テキスト段落が長すぎる、図解コンポーネントが少なすぎる、言い回しの問題、ダッシュの使い方、同じことを二度言っている、など。警告があれば md を修正して再実行し、「レイアウトチェック：通過」が出るまで繰り返します。原文レビュー型の場合は --no-lint を付けてチェックをスキップ。

リソース節約

図は常に簡易記法で記述し、HTML や SVG を手書きしない。別途画像を生成しない。
内容を変えたい場合は md を編集して再実行。出力された HTML を直接編集しない。
長大な詳細リストは --fold "3" で折りたたむ。

ルール 3：必ずジェネレータを使う

プレビューページは必ず scripts/md-to-preview.py（md ソース用）または scripts/convert/inject.py（既にレイアウト済みの HTML 用）で生成。CSS を手書きしたり、自分でコメント機能を実装したりしない。
外観を変更したい場合は assets/preview-tokens.css を編集し、ジェネレータを再実行。

実行手順

Step 1：ソースと識別情報の確認

会話の内容から判断。判断できない場合はユーザーに質問：

何をプレビューするのか？（会話で書いたばかりの内容か、ユーザーが指定したファイルか）
誰がコメントするのか？識別情報のデフォルトは 我,訪客（私, 訪問者）。クライアントに見せる場合は 客戶,我（クライアント, 私）のように変更（最初がデフォルト識別情報）。

ソースが会話内の内容の場合、まず md ファイルとして保存。保存先はユーザーの現在の作業フォルダ（なければデスクトップ上の プレビュー フォルダ）。ファイル名は日本語で内容を説明する名前（例：提案-サンプルクライアント.md）。

Step 2：ページ生成

ソースが md の場合（最も一般的）：

python3 "$SKILL_DIR/scripts/md-to-preview.py" "<ソース>.md" "<出力>.html" \
  --identities "私,訪問者" --badges "草稿,2026-10-19"

パラメータ	説明
`--identities`	識別情報のリスト、カンマ区切り。最初がデフォルト
`--badges`	タイトル下の灰色の小さなラベル、カンマ区切り。省略可
`--key`	コメントをブラウザに保存する際のキー。ページごとに一意。省略時は出力ファイル名
`--title`	ドキュメントのタイトル。省略時は md 最初の `#` 見出し
`--fold "3,4"`	指定したレベルの見出しを折りたたみ可能なセクションに。長いページ用
`--no-lint`	レイアウトチェックをスキップ（契約書や完成原稿などの原文用）
`--no-overlay`	コメント機能なしのクリーンバージョン
`--icon`	タブのアイコンに表示する文字または emoji。省略時はタイトルの最初の文字
`--fonts copy`／`link`／`none`	フォント処理。デフォルトは `copy`

フォント：デフォルトでは出力 HTML と同じ場所に preview-fonts/ フォルダが作成されます。🚨 HTML を他人に送る場合は、HTML と preview-fonts/ フォルダを一緒に zip で圧縮してください。 HTML だけを送るとシステムフォントにフォールバックします（動作はしますが見栄えは落ちます）。

画像：md 内で独立した段落として書かれた ![説明](img/ファイル名.jpg) は、キャプション付きの画像として表示されます。パスは出力 HTML からの相対パス。

ソースが既にレイアウト済みの HTML の場合（例えば自分で作った提案ページ）：レイアウトは変更せず、コメント機能のみ追加。

python3 "$SKILL_DIR/scripts/convert/inject.py" "<ページ>.html" -o "<ページ>-コメント版.html" --identities "私,クライアント"

-o は新しいファイル名を指定。ツールは元のファイルを上書きしません。
ページに既にコメント機能がある場合、新しいバージョンに置き換えるには --replace を追加。

Step 3：ユーザーに表示

システムのデフォルトブラウザで開く：

# macOS
open "<出力>.html"
# Windows（Claude のターミナルが Git Bash の場合：start、PowerShell の場合は Start-Process "<出力>.html"）
start "" "<出力>.html"
# Linux
xdg-open "<出力>.html"

ユーザーに以下の3点を伝えます：

任意の文字列を範囲選択すると「コメントを追加」が表示されます。
チェックボックスはクリックで選択・解除できます。
確認後、右上の「すべてコピー」を押して、内容を会話に貼り付けてください。

Step 4（オプション）：クライアントにレビュー依頼

HTML と preview-fonts/ フォルダを一緒に zip に圧縮してクライアントに送信。解凍後、HTML をダブルクリックして開くよう依頼。
識別情報はクライアントの役割に設定（例：--identities "クライアント,私"）。
コメントはクライアントのブラウザのローカルストレージに保存され、自動的に同期されることはありません。クライアントには確認後「すべてコピー」を押し、そのテキストをメールやメッセージで送り返すよう依頼。

チェックボックス確認

ユーザーがプロジェクトの各項目について1つずつ決定する必要があり、かつ選択肢が決まっている場合、テキスト入力を求めず、チェックボックス形式にします。例：一連の機能を実装するかしないか、複数の素材からいくつかを選ぶ、リリース前のチェックリスト。選択肢が1～2個しかない場合や理由を書く必要がある場合は、直接質問するか範囲選択コメントを使ってください。

記述方法

md 内でタスクリスト形式で記述すると、ジェネレータがクリック可能なチェックボックスに変換します：

### 必須

- [x] 注文フォーム（顧客が入力後、自動でデータベースに保存）
- [ ] シフトカレンダー（各従業員は自分のシフトのみ表示）

- [ ] は未チェック、- [x] はデフォルトでチェック済み。
各グループは自身の見出し（## または ###）の下に配置：エクスポート時に「直近の見出し」でグループ分け。
各項目には名前と説明を付け、独立して読めるようにする。「はい」「いいえ」だけでは不十分。
同じ見出しの下に、全く同じ選択肢テキストを複数置かない。

ユーザー側での動作

チェック状態はブラウザに保存され、ページを更新しても保持されます。「クリア」はコメントのみクリアし、チェック状態はクリアしません。
「すべてコピー」を押すと、先頭に次のようなブロックが追加されます：

## チェック結果（チェック済み 2/5）

### 範囲確認 > 必須
- [x] 注文フォーム（顧客が入力後、自動でデータベースに保存）
- [ ] シフトカレンダー（各従業員は自分のシフトのみ表示）

チェック結果を受け取ったら

チェック結果をそのままファイルとして保存し、これに従って作業する。記憶だけで再入力しない。
チェックされていない項目は「やらない」「現状維持」と解釈し、独自に判断を追加しない。
同じグループ内で矛盾する選択肢が同時にチェックされている場合、ユーザーに確認する。
外部へのアクション（メール送信、ファイル削除、公開など）に影響する場合、最終リストを一度提示し、ユーザーが「実行」と言ってから行動する。

「コメント集約」を受け取ったときの適用方法

ユーザーが「すべてコピー」で貼り付けた内容は以下の形式：各コメントに、範囲選択された原文（引用）、位置（段落見出し）、前後文、コメント内容が含まれます。

一つずつ解釈

コメントの内容	解釈
新しいテキストのみ、動詞なし	置換：引用箇所をコメントのテキストで置き換え
「削除」「消して」	引用箇所を削除（引用範囲のみ）
「追加」「補足」「次にもう一つ」	新規追加：引用箇所の近くに内容を追加
記述型（「〜できますか？」「〜してほしい」）	要望に沿って修正
曖昧、複数の解釈が可能	変更が最小になる方法を選び、レポートでその選択を明示

まず「位置」と「前後文」で該当箇所を特定してから修正。同じテキストがページ内に複数回出現する場合、前後文で一意に特定できることを確認。
同一ラウンドのコメントに前回と重複がある場合、既に修正済みのものを比較・除外。

適用、再実行、再表示

md 原稿を修正し、同じコマンド・同じ --key でジェネレータを再実行。出力 HTML を直接編集しない（次回再実行時に上書きされるため）。同じ --key を使うことで、以前のコメントが引き継がれます。
ページを再度開いてユーザーに表示。
レポート：各コメントについて「どのコメント → 何を修正したか」をリスト。曖昧な場合は、自分が選択した方法を注記。

技術メモ（Claude 向け。ユーザーに説明する必要はありません）

コメントのアンカーは「範囲選択テキスト＋前後文」を使用。内容が多少変更されても対応可能。見つからない場合は「原文が変更されました」と表示。
ハイライト表示はブラウザの CSS Custom Highlight API を使用。ページ構造は変更しない。Chrome、Edge、Safari の最新版で対応。非対応ブラウザでは黄ハイライトが表示されないだけで、サイドバーのコメントは通常通り動作。
コメントとチェック状態はブラウザの localStorage に保存。ページごとに異なる --key を使用しないと、異なるページのコメントが混ざる。
コメント UI 読み込み後、window.PreviewComments が利用可能：.refresh() でハイライトの再配置、.data() ですべてのコメント取得、.exportMd() でエクスポート用 Markdown を取得。
ページ内のモーダルの z-index は 10400 未満に設定しないと、コメントボタンが隠れてしまいます。

kevin8656/claude-skill-preview

claude-skill-preview とは？

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

プレビュー

ドキュメント