預覽：可框選評論的 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 安裝任何東西。
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`	框選評論介面
`assets/preview-tokens.css`	色、字、間距；想改外觀改這裡
`assets/fonts/`	自帶字型 Noto Sans TC、Geist、Geist Mono（SIL OFL 授權）
`assets/example.md`	完整範例：一份虛構的接案提案，所有元件都用到

規則一：評論一律是「框選式」

使用者說「加評論」「可以評論的版本」，指的都是像 Google Docs 那樣「框選任意文字 → 留評論」，不是每段旁邊放一個輸入框。這個技能的評論介面就是框選式，直接用，不要另外做。

規則二：先改寫、再產頁

先分頁面型態

型態	例子	怎麼處理
解說型	計劃、提案、報告、比較、要對方拍板的頁	照下面的寫法重寫成好讀的版本再產頁，不要把工作稿直接丟進產生器
原文審稿型	合約、完稿文案、逐字稿、客戶給的稿	內文一個字都不動，產頁加 `--no-lint`；最多在最前面加一個 `> [!結論]` 說明這頁要看什麼

解說型的寫法

第一屏講完：最前面用 > [!結論] 一句話講結論，接著 > [!要你決定] 列出讀者要做的事。背景放後面，讀者不往下捲也能做決定。
一件事只講一次：結論框講過的，內文不再換句話重講；圖或表格講過的，下面不再用段落重述。不寫「總結」段。
白話：用讀者平常講的詞。專有名詞第一次出現就用比喻，或用 > [!白話] 補一句解釋。
能畫就不寫：先問「這段在講哪一種關係」，照下表挑元件。純文字一段最多三行；每個 ## 段落至少一個圖像元件或表格。
短：一句一個重點。刪掉「換句話說」「也就是說」「值得注意的是」這類起手式。
刪的是重複，不是資訊：數字、日期、名稱、後果一個都不能少、不能改。

圖像元件速查

寫幾行短語法，圖由產生器畫。分隔用全形 ｜，箭頭用 →。完整寫法看 assets/example.md。

這段在講什麼	元件	語法
舊 vs 新、現在 vs 改完後	對照	```對照：第一行 `現在 → 改完後`，之後每行 `項目｜舊的 → 新的`
系統怎麼組成、資料怎麼流	架構	```架構：每行一層 `層名｜盒子、盒子`；層內有先後寫 `甲 → 乙`；兩層之間可插一行 `↓ 說明`
什麼時候發生什麼	時間軸	```時間軸：每行 `時間｜標題｜說明`；行首 `✅` 已完成、`👉` 現在
先後順序、操作步驟、因果鏈	步驟	```步驟：每行 `標題｜說明`，自動編號；四步以內橫排、五步以上直排
幾個關鍵數字	數字	```數字：每行 `數字單位｜標籤｜小註`；單位跟數字之間空一格才會變小字
幾個方案、誰做什麼、並列條目	卡片	```卡片（也可寫 `選項`、`分工`）：每行 `標題｜一行｜一行`；行首 `★` 標成建議方案
多欄比較	表格	一般 md 表格。表頭同時有「現在／舊」與「改完後／新／建議」時，舊欄自動轉灰、新欄淡綠
有分支的流程	流程卡片	ASCII 或 mermaid 流程圖（graph／flowchart 的 TD、LR）；轉不準的會保留原樣
結論、要讀者決定、注意、風險	重點框	`> [!結論] 標題`，下一行起 `> 內容`。可用：結論、要你決定、注意、風險、完成、白話、說明
狀態	色標	行內 `{綠:已完成}` `{黃:等你}` `{紅:卡住}` `{藍:進行中}` `{灰:不做}`
一句裡的關鍵字	重點線	`==關鍵字==`，一段最多一處

顏色有固定意思：藍是結論與資訊、綠是完成與改完後、黃是注意與等待、紅是風險與卡住。「要你決定」全頁只放一個。
語法寫錯不會壞頁，只會退回成灰底程式碼區塊；產完看一眼有沒有該變成圖卻還是灰底的。
有先後或因果用步驟、時間軸；互不相干才用卡片。
圖裡的字都是真文字，一樣能框選評論。

版面體檢

產頁時會自動印「版面體檢」：開頭沒有結論框、某段全是文字太長、圖像元件太少、繞圈詞、破折號、同一件事講兩次等。有提醒就改 md 重跑，直到出現「版面體檢：通過」。原文審稿型加 --no-lint。

省資源

圖一律用短語法，不手刻 HTML 或 SVG，不另外生圖。
要改內容就改 md 重跑，不要直接改輸出的 HTML。
很長的明細用 --fold "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 和 preview-fonts/ 資料夾要一起打包，只傳 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"

告訴使用者三件事：

框選任何文字就會跳出「新增評論」。
方框可以直接點選勾選。
看完按右上角「複製全部」，把內容貼回對話。

Step 4（選配）：給客戶評論

把 HTML 和旁邊的 preview-fonts/ 資料夾一起壓縮成 zip 傳給客戶，請他解壓縮後雙擊 HTML 打開。
身份設成客戶的角色，例如 --identities "客戶,我"。
評論存在客戶自己的瀏覽器裡，不會自動同步回來。請客戶看完按「複製全部」，把文字用 email 或訊息傳回。

勾選確認

要使用者從一串項目裡逐項決定，而且選項固定時，就做成勾選，不要叫他打字回覆。例如：一批功能要做或不做、一批素材選哪幾個、上線前檢查清單。只有一兩個選項，或需要寫理由的，直接問或用框選評論就好。

怎麼寫

md 裡照任務清單寫，產生器會轉成可以點的方框：

### 一定要做

- [x] 訂單表單（顧客填完自動進資料庫）
- [ ] 排班日曆（每位員工只看自己的班）

- [ ] 未勾、- [x] 預設勾好。
每一組放在自己的標題下面（## 或 ###）：匯出時用「前面最近的標題」分組。
每個項目要有名稱加一句說明，能獨立看懂，不要只寫「是」「否」。
同一個標題底下不要有兩個一模一樣的選項文字。

使用者那邊會發生什麼

勾選狀態記在他的瀏覽器，重新整理不會掉；按「清空」只清評論，不清勾選。
按「複製全部」，最前面會多一段：

## 勾選結果（已勾 2/5）

### 範圍確認 › 一定要做
- [x] 訂單表單（顧客填完自動進資料庫）
- [ ] 排班日曆（每位員工只看自己的班）

收到勾選結果時

先把勾選結果原封不動存成一個檔案，之後照這份做，不要憑記憶重打。
沒勾的項目就是不做或維持原樣，不要自己補判斷。
同一組勾了互相矛盾的選項，回頭問使用者。
會影響對外的動作（寄信、刪檔、上線），先列出最後清單，使用者說「照做」才動手。

收到「評論彙整」時怎麼套用

使用者按「複製全部」貼回來的內容長這樣：每則評論有被框選的原文（引文）、位置（段落標題）、前後文和評論內容。

逐條解讀

評論長相	解讀
只有一段新文字、沒有動詞	替換：把引文換成評論文字
「刪除」「去掉」	刪掉引文那段（只刪引文範圍）
「加入」「補」「下面多一個」	新增：在引文附近加內容
描述型（「可以…嗎」「希望…」）	照需求修改
模糊、兩種讀法都通	選改動最小的做法，回報時說清楚你選了哪種

先用「位置」和「前後文」找到正確的那一處再改。同一段文字在頁面出現好幾次時，用前後文確認只對到一處。
同一輪評論可能跟上一輪重複，先比對哪些已經改過。

套用、重跑、重開

改 md 原稿，再用同一條指令、同一個 --key 重跑產生器，不要直接改輸出的 HTML（下次重跑會被蓋掉）。同一個 key，舊評論才接得回來。
重新打開頁面給使用者看。
回報：逐條列「哪一則 → 改了什麼」，模糊的標註你的選擇。

技術備忘（給 Claude，不用講給使用者聽）

評論錨定用「框選文字＋前後文」，內容小改也能重新對到位置，找不到就標「原文已變動」。
高亮用瀏覽器的 CSS Custom Highlight API，不改動頁面結構。Chrome、Edge、Safari 新版都支援；不支援的瀏覽器只會少了黃色高亮，側欄評論照常。
評論與勾選存在瀏覽器 localStorage，每頁用不同的 --key，否則不同頁的評論會混在一起。
評論介面載入後提供 window.PreviewComments：.refresh() 重新定位高亮、.data() 取出所有評論、.exportMd() 回傳匯出的 markdown。
頁面自己的彈窗 z-index 要低於 10400，評論按鈕才不會被蓋住。

kevin8656/claude-skill-preview

claude-skill-preview 是什麼？

在你喜歡的 AI 中提問

預覽

說明文件