點睛
為已經完成或接近發佈的程式碼庫完成視覺風格設計與裝修，讓倉庫從「放程式碼的地方」變成美觀、可信、易懂、可安裝、可傳播的產品門面。
把一個完成的產品轉化為別人看得懂、信得過、裝得上、會使用、願意傳播的公開倉庫。把美觀、動效和可信度作為同一項產品交付，而不是只改 README 文案或堆裝飾圖片。
不可妥協的規則
- 先核驗產品，再包裝產品。 確認真實倉庫邊界、當前提交、運行狀態、功能、許可證、發佈渠道和已有素材。不要發明功能、指標、用戶評價、相容性或發佈狀態。
- 先審計，後修改。 先運行
scripts/audit_repository.py，閱讀源碼入口、產品文件、現有 README、資產和 Git 狀態。保留用戶已有修改，不覆蓋無關工作。 - 產品價值先於安裝說明。 README 先回答「這是什麼、給誰、解決什麼、真實狀態如何」，再進入安裝、首次成功、升級和排錯。
- 真實素材優先。 優先複用真實 Logo、產品截圖、介面錄影和輸出結果。新生成的視覺只能解釋真實產品，不能偽造尚不存在的介面或能力。
- 動效機會必須評估。 每次都評估動態 Hero、真實操作 GIF、演示影片和 Release 媒體；只有 README 無法承載關鍵體驗時才評估展示網站。不得預設只交付靜態 README，也不得為了顯得高級而預設建站。動效不改善理解、信任或品牌時，記錄不採用原因。
- 平台能力必須分層。 README、Social Preview、Release 媒體和 GitHub Pages 是不同表面。不要把 README 當成可任意執行 JavaScript、CSS 或動畫 SVG 的網頁。
- 美觀必須可用。 動效不延遲關鍵資訊，提供靜態首幀和
prefers-reduced-motion，檢查行動端、深淺背景、檔案大小、循環節奏和許可證。 - 能力本體與分髮層分開。 產品源碼、Skill、插件、安裝器、官網和市場設定只有在真實存在時才寫入；避免複製出第二份會漂移的核心實現。
- 發佈狀態按證據表達。 分開本地完成、遠端推送、Tag、Release、可安裝、首次使用、真實行為驗證和官方目錄/商店狀態。
- 遠端動作不自動授權。 本地裝修請求允許修改目標倉庫內相關檔案；推送、建立 Release、修改倉庫 Settings、上傳 Social Preview、啟用 Pages 或部署仍需用戶明確要求。
工作流
1. 界定交付與權限
確認目標倉庫和本輪終點：
- 只輸出裝修方案
- 完成本地倉庫裝修
- 加入動態 README
- 評估並按需建設展示網站
- 準備發佈但不推送
- 完成遠端發佈與公開驗收
若用戶說「裝修好」「直接做」，預設完成安全的本地實現與驗證；不要因此推送或修改遠端設定。
2. 審計真實倉庫
執行：
python3 <skill-dir>/scripts/audit_repository.py <repo-path>
再讀取 audit-and-positioning.md，核驗：
- Git 根目錄、remote、當前分支/提交、工作區修改
- 產品真實入口、可運行程度、許可證、版本和發佈渠道
- README、docs、治理檔案、測試和 Release 記錄
- Logo、截圖、錄影、GIF、影片、社交圖和已有官網
- 本機絕對路徑、佔位文案、斷開的相對連結和疑似敏感檔案
不要把 not a git repository 直接診斷成發佈失敗；先定位真正 checkout。不要修改用戶未授權的產品邏輯。
3. 建立產品裝修建報
從真實材料提煉：
- 用戶交給產品什麼
- 產品完成什麼
- 用戶最終得到什麼
- 最適合誰、不適合誰
- 一個最強差異點
- 當前真實狀態和重要邊界
- 希望傳達的氣質
- 第一次成功的定義
需要落盤時複製並填寫 repository-brief-template.md。缺少品牌方向時根據產品本身做一套明確選擇，避免把設計決策全部推回用戶。
4. 選擇必做底座與條件模組
先完成所有公開倉庫都需要的底座，再按產品任務選擇模組。不要把模組數量當作完成度或高階程度。
必做底座：
- 產品定位與事實邊界
- README 資訊架構
- 安裝與第一次成功
- 真實視覺素材
- 許可證、版本和發佈狀態
- 基礎治理與公開驗收
條件模組：
| 模組 | 採用條件 |
|---|---|
| 動態表達 | 動態 Hero、真實操作 GIF 或影片能明顯改善理解、信任或品牌識別 |
| 展示網站 | README 無法承載關鍵互動、視覺體驗、非開發者轉化或線上 Demo，且沒有可複用的正式官網 |
| 發佈傳播 | 產品確實進入版本發佈、外部分享或持續傳播階段，需要 Social Preview、Release 媒體、雙語入口或升級排錯 |
| 深度文件 | 安裝、API、設定或維護複雜到 README 已不適合作為唯一文件 |
展示網站是條件性交付，不是更高裝修等級。Agent Skill、CLI、SDK、小型庫通常以 README 為主頁；UI 產品、遊戲、創意編碼、互動 Demo 或面向非開發者的產品更可能需要展示網站。產品已有正式官網時，優先連接並複用，不再建立重複的 GitHub Pages。
5. 設計 README 與文件
讀取 readme-and-documentation.md。按用戶理解路徑組織：
看懂產品
→ 建立使用動機
→ 看見真實證據
→ 理解能力與邊界
→ 安裝
→ 完成第一次成功
→ 排錯與升級
→ 了解測試、維護與許可證
不要機械套模板。CLI、庫、App、網站、Skill/插件和研究專案應選擇不同的展示、安裝和首次成功路徑。需要骨架時複製 readme-outline-template.md 後按產品刪改。
6. 設計視覺與動效系統
讀取 visual-and-motion.md。先盤點真實資產，再確定一套產品專屬的色彩、字體、構圖、圖示與動效語言。
如果 motion-anything-design 可用，必須先：
- 讀取當前 bundle。
- 搜尋適合產品氣質的設計系統。
- 搜尋
implementation_status: ready的真實動效。 - 讀取入選動效的
avoid_when、restraint、reduced_motion、依賴和許可證。 - 獲取真實實現檔案後再適配；不要憑記憶重寫已有實現。
- 搜尋並獲取準確圖示 SVG。
若需要新 Logo、Hero 或插圖，先複用已有品牌資產；確需生成時使用可用的圖像生成能力，並以真實產品截圖和介面為依據。
每個倉庫至少完成一次動效機會審計：
- 動態品牌 Hero 是否能更快說明產品
- 一個真實操作 GIF 是否比多張截圖更有效
- Release 是否需要短影片
- README 是否已經無法承載關鍵體驗；若是，現有官網或展示網站是否值得承載互動、流程和 CTA
- 靜態首幀、無動畫狀態和深淺背景是否都成立
7. 實現倉庫門面
在目標倉庫現有技術棧和約定內工作：
- 修改 README 和必要文件
- 複用或製作真實視覺媒體
- 按需增加
docs/、上手、排錯、維護和發佈說明 - 通過展示網站條件門後，才按需增加 Pages 源碼與部署設定
- 保持產品核心源碼單一，不為了展示複製實現
- 使用相對連結，避免本機路徑
- 不提交金鑰、Cookie、私有連結、未授權素材或不相容許可證
動效選擇遵循「一項動效承擔一個敘事任務」。預設每屏最多一個環境背景效果、一個主要文字動效和一個慶祝/高光效果；正文與關鍵操作保持穩定。
8. 驗證本地結果
重新執行審計腳本，並檢查 Git diff。然後：
- 渲染 README，檢查桌面與窄屏閱讀順序
- 實際打開所有圖片、GIF 和影片
- 檢查 GIF 首幀、循環接縫、字幕和檔案大小
- 若採用展示網站模組，對 Pages 或現有官網執行瀏覽器驗收：響應式、深淺模式、互動、主控台、性能、404
- 開啟減少動態偏好，確認內容立即可見且功能不遺失
- 檢查所有相對連結、安裝指令、版本、許可證和真實狀態
- 確認沒有覆蓋用戶無關修改
9. 驗證公開產物
用戶授權發佈後，讀取 release-and-acceptance.md。從公開倉庫或 Tag 全新檢出，重新驗證 README、媒體、已採用的展示網站、安裝、第一次成功和升級路徑。
分別報告：
- 本地裝修完成
- 遠端源碼可見
- Tag / Release 已發佈
- 已採用的 Social Preview / 展示網站已生效
- 用戶首次成功已驗收
- 尚未完成或僅由用戶口頭確認的部分
需要正式記錄時複製 acceptance-report-template.md。
停止條件
- 產品真實狀態無法確認：先報告證據缺口，不用視覺掩蓋問題。
- 缺少真實產品畫面：可以製作品牌與結構素材，但不要偽造產品截圖。
- 動效與 README 不相容：優先轉成 GIF 或影片；只有通過展示網站條件門時才轉到 Pages，不聲稱 README 會執行不受支援的腳本。
- 現有工作區修改與裝修檔案衝突：保留用戶修改並說明衝突，必要時請求方向。
- 需要推送、部署、付費素材或修改遠端設定但未獲授權：完成本地可交付部分後停止。