Html Visualizer

HTML Visualizer

把資訊圖像化呈現給人類閱讀的萬用 skill。

核心精神

人類看 HTML、AI 看 Markdown

• AI 思考 / 規劃 / Inter-agent 溝通用 Markdown（密度高、AI 處理快）
• 最終給人類看的長文件用 HTML（視覺化、易閱讀、可互動、可分享）
• 不是兩份 output、是同一個 source 用對的 representation 給對的 audience

預設視覺風格：Anthropic / Claude 官方品牌風

預設用 Anthropic 風格（ivory 米白底 + clay 赤陶 accent + serif 標題 + 換字重強調 + warm gray）— editorial / book / magazine 質感、跟 Claude 官方品牌一致。

完整 design tokens 見 references/color-and-typography.md、Anthropic-signature 元件見 references/component-library.md § 首段。風格總覽（四份範例入口＋設計系統樣張）見 references/examples/anthropic-gallery/index.html。

例外：工程儀表板 / 重度互動表單 / 內部工具 / 使用者明確要 dashboard 風時、改用 functional 風（藍 accent + 純 sans）。判斷規則見 references/do-and-dont.md § 何時打破規則。

何時用

預設用 HTML（不要問使用者）：

預設用 Markdown / 純文字（不用此 skill）：

• 短 Q&A、單句回應
• 程式碼 fix、技術討論
• 終端機 output 格式
• AI 內部 scratch / 思考過程
• 使用者明確要求「給我 markdown」/「純文字」/「在 chat 直接給我」

工作流（給 AI 自己看）

Step 0 ⭐ 場景判斷與範本選擇（必做、決定起手式）

寫第一行 HTML 前、先用以下對照表選範本。這一步沒做對、後面 visual / 互動都會走錯方向：

判斷流程（1 分鐘）：

1. 讀 user 原始 prompt + 內容素材、找這些訊號：
   • 直接訊號：「marathon 收尾」「sprint retro」「給我選項拍板」「列待確認」「我醒了 / 回來了 + 有 marathon 收尾」「decision sheet」
   • 間接訊號：素材內含 5+ 條「待 user 確認 / 拍板 / review / 寫入 / commit」事項、或含「pending QA」「未 push」「未 commit」「等 user」字眼
2. 任一訊號中 → 先數「實際要 user 拍板的題數」（不是數關鍵字次數）：
   • ≥ 5 題 → marathon-decision-sheet 範本（強制、不要 fallback）
   • < 5 題、主體就是要拍板 → 輕量決策頁：base-template + 就地拍板卡，開場兩三句就進題目。< 5 題、主體是報告 → editorial-report 原樣，題目就地放在背景段末尾。⚠️ 不要因為關鍵字命中就硬套六段敘事——實測 5 題的內容被套成 2265 行、每題墊了四百多行前置閱讀，讀者要捲過 58% 才看得到第一題
3. 都不中 → 對照表選其他範本

Step 1 思考階段（用 markdown）

0. ⭐ 讀使用者的設定檔：python3 <本 skill 目錄>/scripts/profile.py show --rules，印出來的文字規則當成這一頁的生成規則（偏好以設定檔為準；跟本 skill 的「規範」衝突時以本 skill 為準——規範＝相反做法本身就是缺陷，例如中文不用斜體）。字型、配色、字級、寬度這些數值不用抄，Step 3 的自檢會蓋章套用。沒有設定檔就全部沿用範本原值
1. 理解需求：呈現什麼資訊、給誰看、為了什麼決策
2. Read 對應範本 README（marathon-decision-sheet 的話、必先讀）
3. 規劃結構：依範本框架寫 markdown outline（區段順序、每段重點、需要的視覺化類型）

   • ⭐⭐ 每題先配對它的背景段落（hard rule、決定閱讀動線）：列出每道拍板題，標出「讀者要拍這題，得先知道什麼」。

     • 有對應背景 → 該題就地放在那段的末尾（同一張卡：問題 → 方案對照 → 選項 → 補充框）。禁把它丟到文件尾段的決策區
     • 不需要背景就能拍（延後項目 / 要不要寫進記憶 / 怎麼驗 / 提交拆法 / 要不要推送）→ 收進尾段「程序快答」
     • 配對表寫進 outline，寫 HTML 時照著擺。⚠️ 舊版把說明全放上半、拍板全放下半，兩邊用不同分類軸切，讀者拍板時找不到回去的路——這是本 skill 修過最嚴重的動線問題，不要退回去

   • ⭐ 圖像化優先：outline 的每一段都要問「這段能不能用畫的」。預設用視覺元件承載資訊，文字只做補述——流程用流程圖 / 對比用並排 mock / 結構用樹狀或版面縮圖 / 分類用卡片矩陣 / 數據看形狀就交棒 chart。連續三行以上的純文字說明就是訊號：停下來想有沒有對應的視覺形態（元件清單見 references/component-library.md、資料圖表交棒 chart）

   • ⭐ 挑最小的視圖（2026-08-29 拍板，參考 show-me）：每段選視圖時用下表挑「能把重點講清楚的最小視圖」，且一頁通常只用其中一兩種、別淹沒讀者：

     要講的點	最小視圖
     演算法 / 判斷邏輯	pseudocode（code-shape）
     執行期呼叫關係	call tree（code-shape）
     UI 結構與狀態歸屬	component tree（code-shape）
     檔案分工 / 大型重構	淺層檔案責任樹（code-shape）
     跨部件互動時序	SVG 時序圖（references/structure-diagrams.md §7.3；有分支用組合片段）
     ⭐ 分支 / 角色交接 / 回頭路 / 分區跨線 / 多父或有環的依賴	SVG 結構圖（references/structure-diagrams.md：流程圖 / 泳道 / 狀態機 / 架構 / 依賴圖…）；單向直線鏈才用 div 流程圖。該圖 ≥6 格 → 掛探索層（§6.7：點格聚焦 / 追上下游 / 兩點路徑 / 章節視角；assets/diagram-explore.{css,js} 內嵌）；有格子需要比圖上多兩行的說明 → 寫 template[data-detail]，點一格就在浮動窗讀到（小圖也適用，§6.7）
     改了什麼（結構 / 流程 / 檔案佈局）	結構 diff
     改了什麼（畫面外觀）	Before-After UI mock
     資料的形狀	交棒 chart

4. 思考互動：marathon-decision-sheet 必含 radio + sticky copy + 題目地圖（題數 ≥ 5 必放；< 5 題但第一題的可見文字位置 > 40% 也必放）；其他範本依需求加
   • ⭐ 逐題標記 UI/UX 決策：掃每個待拍板決策題、標出本身涉及 UI/UX 的（頁面 / 按鈕 / 欄位顯示 / modal / 流程入口 / 排版 / 順序 / 顯示條件 / 文案呈現）。被標到的題 → 規劃時就排進「現況畫面 vs 修改後畫面」對比 mock、不要只列文字選項。判斷準則見 references/do-and-dont.md § UI/UX 決策題

Step 2 產出階段（寫 HTML）

5. 起手式：
   • marathon-decision-sheet 場景 → 複製 references/examples/marathon-decision-sheet/index.html 改內容、保留 CSS / JS / 結構
   • 報告類（editorial-report）、教學類（explainer 骨架 A）、規格對齊（spec-alignment） → 複製該範例的 index.html 改內容，保留 CSS／JS／結構
   • 其他場景 → 複製 assets/base-template.html 起手
   • 絕不從零寫
6. 填內容：把 markdown outline 翻成 HTML 元件、保留範本的互動 JS
7. 配色 / 字體：照 references/color-and-typography.md 的 token、不要自創；使用者設定檔的值由 Step 3 自檢蓋章覆寫，不要手抄進頁面
   • ⭐ 字級要能被「風格設定」推動：<style> 與 style="" 裡寫死的 px 字級，自檢會自動改成乘倍率；腳本在執行期組出來的行內字級改不到，要自己寫成 calc(13px * var(--fs, 1))（字級覆蓋率檢查會抓漏）。固定在畫面上的介面列（sticky 拍板列、頂部導覽）加 data-tw-lock，字放到 200% 時才不會蓋掉半個畫面
   • ⭐⭐ 好讀的五條硬規則（2026-10-27 起；方向是讓讀者好讀、好回饋，設計與創意只是手段）。前三條自檢會量，有 ✗ 就修：
     1. 小字只用墨色：24px 以下的字用 --text-soft／--clay-ink／--green-ink／--yellow-ink；--clay、--olive、#c49845、--g500 只當填色、邊框、圖示與大字（當小字只有 2.5–3.5:1）。白字按鈕底用 --clay-d。對照表見 references/color-and-typography.md §對比規則
     2. 中文長標題切語意片段：超過 12 個中文字的 h1／h2 才切，h3 不切（h3 斷在哪都還讀得懂，切了反而在窄欄裡留孤字）。寫法 <span class="ph">為什麼登入</span><span class="ph">要發兩張憑證</span>，瀏覽器只在片段之間換行；強調詞兩側不加半形空格
     3. 淡入動畫要 fail-open：沒捲到的段落在列印、存 PDF 時也要看得到（範本已內建 @media print；自己寫淡入就照抄）
     4. 行長：容器可以滿寬，裡面兩行以上的文字 ≤ 72ch（提示框、卡片內文也算）
     5. 手機表格看形狀選做法：欄數 ≤ 4、每格是短文字的比較表 → 640px 以下每列變一張卡（寫法見 references/component-library.md § 表格在手機每列變一張卡）；欄數 > 4 或以數字為主的資料表 → 外包 .tbl-wrap 整表橫向捲動。兩種都不要用 overflow-wrap: anywhere 把欄位壓成一字一行。橫向流程鏈在 640px 以下改直排
   • ⭐ 圖示用 lucide inline SVG、不用 emoji（references/component-library.md § 圖示）。設定檔 checks.noEmoji 開著時自檢會擋
8. 存檔：寫到 ~/Documents/claude-html/{YYYY-MM}/{slug}-{date}.html（歸檔根目錄可用環境變數 HTML_VISUALIZER_ARCHIVE_DIR 改）（不要再寫 /tmp——系統暫存區重開機就清空，而這些產出常被回頭參照）。先寫死、Step 3 自檢後再 open

Step 3 ⭐ 審稿階段（寫完 HTML 後、open 前必跑）

寫完 HTML 不要立刻 open 給人看 — 必須先跑中英混雜詞審稿。HTML 是給人類看的長文件、中英混雜詞讀起來不順、特別影響 user-facing 體驗。skip 這一步、user 看了會回來指出「不中不英看不懂」、徒增來回。

9. 跑中英混雜詞審稿：

   • Read references/cn-en-translation-checklist.md 看替換清單 + 保留原則
   • 用 Python script 批次替換對照表中的詞（順序：長片語先、短詞後）
   • 範例 script 在 reference 檔末段、可直接複製改用

10. 保留技術專有名詞（替換清單明列）：

    • Skill 名 / git 命令 / framework / library / CT 名 / field name / endpoint path
    • 公知縮寫（API / RBAC / SSE / PBX / TLS / DOM）
    • 敏捷用語（Story / Epic / Sprint）

11. 元件名首次出現加註中文（例：BindCustomerDialog（客戶綁定對話框））；之後同元件可省略註解

12. 句構檢查：批次替換完整 read 一遍 — 替換可能造成句構斷裂（嵌套引號 / 多餘空格 / 詞性不通）、必修

13. ⭐⭐ 跑自檢指令（取代過去十來條手打 grep）：

    bashCopy code
    python3 <本 skill 目錄>/scripts/verify.py <file>
    

    ⭐ 它會先「蓋章」、改寫受檢檔：①把使用者設定檔選過的值寫成 :root 變數 ②把寫死的 px 字級與間距改成乘 --fs／--dens 倍率 ③補上「風格設定」面板（assets/tweaks.{css,js}，缺就注入、舊版整段換新）。三件都冪等，重跑不會疊加；倍率為 1 時頁面外觀逐像素不變。範本原檔不蓋；唯讀環境或幫別人審稿時加 --no-stamp。寫不進去會標「未蓋章」，不是通過。

    一次跑完並依產出類型自動分流：結構完整性（標籤平衡 / 標題）、⭐腳本健檢（每個 inline script 跑 node --check / JS 抓的元素 id 真的存在）、Session 識別已填值、拍板機制（決策卡 ↔ 選項 ↔ 摘要三方一致 / 每題有補充框且被抓取 / 複製摘要三件套 / 無下拉選單）、閱讀動線（題數 ≥ 5 要有題目地圖；< 5 題時第一題的可見文字位置 > 40% 也要有）、呈現品質（每段都有視覺元件 / 中英混雜詞）。

    🔴 腳本健檢為什麼存在（2026-08-13 實際事故）：一份決策頁 13 項自檢全過、open 給使用者後，複製鈕按了完全沒反應。根因是 JS 字串裡混進真正的換行字元 → 整個 script 區塊 SyntaxError → 事件監聽器從未掛上。結構、拍板機制、文案檢查全都看不到這種錯——它不在標記裡，在「腳本能不能跑」。 高風險寫法：用腳本產生 HTML（腳本寫腳本）時，\n 之類的轉義會被多吃一層；要放換行改用 String.fromCharCode(10) 常數，完全不用轉義字元即免疫此類問題。 ⚠️ 機器上沒有 node 時這項會標成「無法驗證」而不是通過——看到它就別當作驗過了。

    🔴 執行期健檢（2026-09-09 加，同一支指令內建，用 playwright 真的把頁面跑起來）：抓載入時的 pageerror，再按一次複製鈕與預覽鈕，看頁面有沒有任何可見變化。

    為什麼存在（2026-09-09 同型事故再一次）：決策頁砍掉了「題目地圖」那段 HTML，腳本裡 qmap.remove() 對 null 炸掉，同一個 script 區塊後面的複製鈕監聽器全沒掛上。語法檢查、版面健檢、拍板機制三方一致全綠，「JS 參照的元素都存在」只給黃燈並註「動態產生的可忽略」，於是被忽略了。靜態檢查永遠有下一種漏法（08-13 是換行字元炸 SyntaxError、09-09 是 null 存取）；「載入 → 有沒有炸 → 按下去有沒有變」這三步不會漏。回掃當月 112 份產出，另抓到 3 份載入就炸的頁面。 ⚠️ 同一個 script 區塊裡任何一行炸掉，它後面的所有監聽器都不會掛上；砍範本區塊時，對應的 JS 要一起砍或加 null 防護（範本 renderQuestionMap 已補）。 ⚠️ 這項標「未驗證」時同樣不算通過。

    ⭐ 樣式健檢（2026-09-08 加，同一支指令內建）：掃每個 inline <style>，抓三種會讓瀏覽器從該行起丟棄後面所有 CSS 的結構錯——多一個 }、規則沒收尾、孤兒屬性（規則開頭被切掉）。

    🔴 為什麼存在（2026-09-08 實際事故）：一份決策頁 9 項自檢全過、版面健檢在三個寬度都說沒跑版，open 給使用者後整頁沒有樣式。根因是前一天用 sed -n 'A,Bp' 從範本切 CSS 片段，切點落在規則中間。當時做過括號檢查、得到「左 158 右 158 平衡」——因為多切掉一個 { 又多留一個 }，數量剛好抵銷。括號平衡量的是數量，CSS 合法性要的是結構。 而且失效是沉默且連鎖的：症狀出現在離錯誤很遠的地方（錯在第 508 行、新加的樣式在第 667 行），看新加那段永遠找不到原因。 🔴 四種可讀性崩潰為什麼要另外量（實際事故）：一份報告 18 項自檢全過、版面健檢三個寬度都說沒跑版，交付後被回報日期清單的中文被壓成一個字一行。根因是為了讓「每段都有視覺元件」變綠，把共用樣式已定義的 .timeline（七欄網格）套到一個兩欄清單上，兩套佈局互相覆蓋。原本的檢查看不到——直排既不溢出視窗、也沒有文字被切掉，只是變得超高。同一個 class 撞車還可能表現成元素被壓扁、文字看不見、被蓋住，所以四種一起量。 🔴 連帶新增 class 撞車靜態檢查（在「樣式健檢」段）：同一個元素掛了兩個都在管佈局的 class 就報，跨 <style> 區塊（自訂 CSS 撞共用樣式）判 ✗、同區塊（作者刻意覆寫，例如 .ba-grid.venn 改欄數）只給提示。它抓的是原因、四種崩潰抓的是症狀，兩邊互補。 🔴 不要為了讓某項自檢變綠而套用已定義的 class 名——這正是上面那次事故的動作。要新元件就用自己的命名空間；套用前先 rg '\.<名字>\s*\{' <head 檔> 確認共用樣式沒定義過。凡是「為了過檢查」而改的東西，一律要親自看渲染結果，不能只信同一支自檢再跑一次通過。 🔴 表格欄位失衡＋逐寬度截圖（2026-09-09 加，版面健檢內建）：量每張表格，某欄平均超過 12 字卻被壓到不足 8 字寬、疊 6 行以上，且同表另一欄寬它 2.5 倍以上就報；<td> 上掛 white-space: nowrap 而內容 ≥ 40 字也報。每個寬度另存一張整頁截圖並印出路徑（預設在系統暫存目錄的 html-visualizer-shots/，可用 HTML_VISUALIZER_SHOT_DIR 改）。

    為什麼存在（2026-09-09 實際事故，同一天第二次）：一份評估頁 18 項自檢全過、三個寬度都說沒跑版，開給使用者後方案表的「做法」「改動」兩欄一行只剩三四個字，「取捨」欄佔了一半寬。根因是為了讓 390px 的「文字被壓成直排」變綠，給表格末欄加了 white-space: nowrap——手機寬度確實過了，桌機上那欄把整列寬度吃光。直排檢查的門檻是「不到三個字寬」，一行四個字疊十行量不到；而作者改完只重跑同一支自檢、沒看畫面。這正是上一條「為了過檢查而改的東西一律要親自看渲染結果」講的事，規則已經寫在那裡、還是踩了——所以現在把截圖直接印在結果裡：跑完自檢必看 1440px 那張截圖，不看不算跑完。

    表格的正確寫法：table-layout: fixed ＋ <colgroup> 明定各欄百分比；只有「A／B」這種標籤欄可以 nowrap；手機寬度包一層 overflow-x: auto 讓整表橫向捲動，不要動欄位的換行。範例見 references/component-library.md § 方案對照表。

    ⚠️ 版面健檢證不了樣式有生效——它量的是溢出座標，樣式全失效時每個元素都還在自己位置上、量不出異常。兩項要一起看。 ⚠️ 不要用行號切 CSS 片段：要複用範本樣式就整段複製到規則邊界，或整份 head 一起帶。

    ⭐ 版面健檢（同一支指令內建，用 playwright 無頭 chromium 在 390 / 768 / 1440px（設定檔 checkWidths 可改）真的把頁面畫出來）：量整頁橫向溢出、凸出視窗的元素、被容器切掉的文字，以及樣式撞車的四種可讀性崩潰（文字被壓成直排／元素被壓扁到沒有高度／文字與背景對比不足看不見／被不透明元素蓋住），並指名是哪個元素。跑版不在標記裡——同一份 HTML 可以在桌機好好的、在手機整片凸出去，靜態掃 class 名稱永遠猜不到，只有量出來的座標算數（首次上線就在自家決策頁抓到 6 處手機跑版）。趕時間可加 --no-layout 跳過；找不到瀏覽器時同樣標「未驗證」而非通過。 pnpm 專案的 playwright 不會被提升到 node_modules/playwright，指令從專案根跑仍會說找不到；設 HTML_VISUALIZER_PLAYWRIGHT_ROOT=<repo>/node_modules/.pnpm/playwright@<版本>/node_modules 即可。

    ⭐ 可讀性三項＋回傳列（2026-10-27 加，版面健檢與呈現品質內建）：①小字對比不足——逐元素量 WCAG AA（小字 4.5:1、大字 3:1），列出「前景 在 背景」色碼與元素；改法是換墨色 token，不是調淡底色。②列印時看不見——模擬一次捲動後切到列印模式，量還停在透明的文字；捲入淡入沒寫列印規則時，讀者存 PDF 會整段空白（2026-10-27 範例實測 95 段）。③標題孤字——h1–h3 任一行只剩一個漢字。④回傳列＋反白留言——缺底部回傳列或全頁評論系統即 ✗。⑤拍板選項不預設勾選、⑥補充框被藏起來——兩條都是既定的使用偏好，範本曾同時違反兩條；⑦結束標籤不重複——存檔格式化工具會替片段補一組 </body></html>，拼回整頁後評論系統落在 </html> 之後。⑧拍板選項鍵盤選得到——拍板卡裡的 radio 用 display:none 或 visibility:hidden 藏起來即 ✗（Tab 落不到，鍵盤拍不了板）；視覺隱藏要用 opacity:0＋position:absolute，整張 label 在 :has(input:focus-visible) 時給 3px 外框（assets/base-template.html 的 .choice 即此寫法）。 為什麼存在：2026-10-27 用得獎網站評審標準重審六份範本，六份都沒過；原本 18 項自檢全綠，因為「看不見」只抓 1.6:1 以下，赤陶、橄欖綠、黃當小字（2.3–3.5:1）全數放行，一次掃出上百處。

    • 有 ✗ 就修完再 open，不要先開給人看。唯一例外：含 SVG 結構圖的頁面，版面健檢對 <svg> 的「凸出視窗」「文字被切掉」是已知誤報（.figure 受控橫向捲動），SVG 文字真正的檢查是 scripts/svg-text-check.mjs（references/structure-diagrams.md §9）
    • ⚠️ 別再自己現寫 grep：手打正則出錯會產生假警報（實測踩過——寫錯的檢查回報「每段都是純文字牆」，其實產出沒問題）

14. ⭐ 看截圖：版面健檢每個寬度都印了整頁截圖路徑，用你的看圖工具看 1440px 那張（手機版另看 390px）。這一步不是可選——2026-09-09 兩次同型事故都是自檢全綠、畫面不能看。

15. ⭐ 人工確認指令標 ! 的兩項（機器判斷不了）：

    • UI 決策題的畫面對照：指令只報「幾個畫面樣張 / 幾題」，要你自己判斷哪些題涉及畫面。它認得的樣張結構是 class 名含 mock（base／explainer）、ba-col（Before-After 對照）、cmp-col、mkf（editorial 的 .cmp 兩欄對照）、screen（spec-alignment 的角色畫面）的元素，巢狀的只算最外層一張；自己做的樣張外層掛其中一個 class 才數得到。流程圖、數字對照這類具象示意不算畫面樣張、不會被數到，那題本來就不涉及畫面時，0 是對的。marathon 範本目前沒有內建這類結構（頁面 / 按鈕 / 欄位顯示 / modal / 排版 / 順序 / 文案）。涉及畫面的題每題至少 2 個樣張（現況 + 改後），判準見 references/do-and-dont.md § UI/UX 決策題
    • 純展示的骨架順序：指令只列出段落 id，要你自己對照骨架 A / B（見 references/examples/explainer/README.md）。骨架 A 缺「一句話定義 / 核心模型 / 邊界」任一、骨架 B 缺「結論先講 / 待觀察」任一，即違規

16. 跑完才 open（存放路徑與索引見 § 開檔方式）

例外情境（規則不適用、不需審稿）：

• AI 內部思考 / 規劃 / inter-agent 溝通的 markdown — 中英混雜 OK（AI 看 markdown）
• code / commit message / spec markdown 內部技術討論 — dev audience、保留

必含元素

每個 HTML 產出必須有：

🤖 何時切 subagent 跑此 skill（軟提醒）

預設主 session 跑。以下少數場景才考慮 subagent：

判斷準則：HTML 寫完後 user 會不會 follow-up？會 → 主 session（subagent 退出後重接成本更高）；不會 → 可 subagent。

嚴格禁止

模板擴展原則

當有新類型場景需要新模板時：

1. 在 references/component-library.md 加一段新元件範例（含 HTML snippet + 何時用）
2. 在 references/examples/ 加一個完整實例 folder（含 README 說明用途 + 完整 HTML）
3. 不動 SKILL.md 主檔（除非觸發機制變了）

模板隨用隨加、不需要事先規劃完整。

使用者的設定檔

位置 ~/.config/html-visualizer/profile.json（HTML_VISUALIZER_PROFILE 可覆寫），只記使用者明確選過的項目，沒寫的沿用範本原值。兩半：tokens（字型、字級倍率、配色、寬度、密度——自檢蓋章套用）＋ rules（寫不成數值的口味，Step 1 讀）；另有 checkWidths（版面健檢寬度）與 checks.noEmoji。

set 只接受已知的鍵，打錯字會被拒絕、不會默默寫進去。可用的鍵見 profile.py set 的錯誤訊息或檔頭說明。

頁面上「設定檔變更」段裡的 profile.py 路徑是產頁當時 skill 的位置；路徑不存在時（例如 plugin 升版換了快取目錄），改用本 skill 目錄下的 scripts/profile.py，參數照抄。

開檔方式

寫完 HTML 後：

產出歸檔（不是丟暫存區），寫完更新索引再開：

bashCopy code
# 1. 存到歸檔目錄（依月份分）
#    ~/Documents/claude-html/{YYYY-MM}/{slug}-{date}.html
# 2. 重建索引頁（依日期倒序 + session 顏色分組 + 即時篩選）
python3 <本 skill 目錄>/scripts/reindex.py
# 3. 開給使用者看
open ~/Documents/claude-html/{YYYY-MM}/{slug}-{date}.html   # Linux 用 xdg-open、Windows 用 start

不要等使用者問「在哪裡看」、寫完直接 open。{slug} 是內容主題的 kebab-case、{date} 是 YYYY-MM-DD。

為什麼不用 /tmp：這些產出常被回頭參照（規格、盤點結果、健檢報告），暫存區重開機就清空。索引頁 ~/Documents/claude-html/index.html 讓「上週那份在哪」有地方找——顏色點與產出頁首色帶同一套雜湊，同一個 session 的東西顏色一致。

如果使用者明確要寫到別的位置（如專案的 docs 目錄）、聽他的、覆蓋歸檔預設。

跨 agent 使用

本 skill 沒有綁定任何一家 agent：frontmatter 只用通用的 name 與 description，scripts/ 只依賴 python3 與（選配的）node，模板與 references/ 全部共用。安裝方式見 repo 根目錄的 install.sh。

只有三件事會因執行環境而異，腳本都已自動處理：

使用者明確要求「在對話裡直接讀」時，給完整文字內容、不強迫走 HTML；HTML 只在使用者要的時候另附。

引導去 references

每次跑此 skill 不需要全讀 references、依當下需求 read 對的部分即可。

範例觸發 prompt

反例：什麼時候錯選了範本

• ✗ 內容是 marathon 收尾簡報、但用 anthropic-gallery 純展示風 → user 拍板沒地方拍、要打字回 chat
• ✗ 內容是純技術評估、但塞 sticky bottom bar + radio → 過度設計、user 沒事可選
• ✗ 內容含「未 commit」「pending QA」「待 user 拍板」字眼、但用 base-template → 漏掉拍板互動

判斷小心法：素材裡 grep 一下「拍板 / 追認 / pending / 未 / 待 / TODO / 等 user / approve / confirm」、≥3 個 → 這份要有拍板互動。接著數實際題數決定份量：≥ 5 題走 marathon-decision-sheet，< 5 題看主體：主體是拍板走輕量決策頁（base-template + 就地拍板卡），主體是報告走 editorial-report 原樣。⚠️ 別再只憑關鍵字次數就套重型範本。