SkillLens：使用與維護
SkillLens 將任何 SKILL.md 轉換為動畫泳道流程圖：卡片代表步驟，菱形代表決策，實線表示前進，虛線表示迴圈，發光小點沿著線條移動，而發光卡片則是當前步驟。UI 和固定的圖表文字提供英文（預設）和中文；右上角的「中 / EN」可切換。
title: SkillLens
subtitle: SKILL.md 輸入 · 自動提取 · 動畫流程圖輸出
hero: SkillLens | 匯入 · 提取 · 調整 · 匯出
trigger start: 想了解某項技能 [當] {bell}
讀取工作流程
檢查或簡報
lane L1: 匯入 [匯入] (綠色)
step open: 開啟 SkillLens [start.bat] {play}
列出所有本地技能
每次儲存時重新繪製
step add: 拖放或貼上 [drop] {upload}
資料夾、.md 檔案
或貼上的文字
lane L2: 提取 [提取] (藍色)
decide has: 有 skillflow 區塊？ [skillflow?]
step auto: 啟發式提取 [auto] {sparkles}
區段 → 泳道
步驟 / 決策 / 迴圈
step check: 對照來源檢查 [review] {scan-eye}
點選卡片查看其文字
檢視其連線位置
step tune: 在結構中調整 [edit] {pencil}
套用以重新繪製
複製為程式碼區塊
lane L3: 輸出 [匯出] (紫色)
step draw: 從區塊繪製 [render] {layers}
泳道 · 卡片 · 菱形
小點沿線流動
step out: 匯出 [export] {download} +end
HTML / SVG / PNG
錄製 mp4
flow:
start -> open -> add -> has
has -> auto : 否
has -> draw : 是
auto -> check -> tune -> draw -> out
check ~> auto : 修正來源文字
開啟方式
- 雙擊
start.bat：啟動本地伺服器並開啟瀏覽器。清單中包含儲存庫的skills/和examples/目錄，以及本地 Claude 使用者和外掛技能，並在 SKILL.md 變更後的 2 秒內重新繪製。與npm start相同；npm run start:project則僅列出儲存庫自己的技能。 - 直接開啟
index.html：無需伺服器，但清單來自data/skills.js，因此需要先執行npm run scan。影片錄製和自動翻譯需要伺服器。 - 額外資料夾：
--root 名稱=<路徑>，或在儲存庫根目錄中放置skillviz.config.json：{"roots":[{"label":"團隊技能","dir":"<路徑>"}]}。
撰寫能良好繪製圖表的技能
提取規則位於 src/extract.js。遵循以下方式撰寫的 SKILL.md 無需 skillflow 區塊即可正確繪製圖表：
- 將程序放在
## 工作流程/## 步驟/## 程序等標題下，使用有序清單或帶編號的###子標題；將每個步驟寫成**短標題**：說明。 - 以「如果…」/「是否…」開頭撰寫決策；「如果 X，則執行 Y」會變成帶有「是」出口的菱形。
- 將路由器撰寫為兩列表格，左欄標題為「狀態 / 條件 / 如果」，右欄為「動作 / 執行 / 路由」：它會變成一串優先比對的決策。
- 將迴圈撰寫為「返回步驟 N，直到…」。
- 以開頭的
[如有必要]/[可選]標記可選步驟；該卡片會獲得虛線邊框。 ## 規則/## 注意事項下的規則會變成琥珀色備註；## 參考資料下的內容會變成未連線的參考泳道。
skillflow 區塊（精確控制）
當 SKILL.md 包含 ```skillflow 區塊時，SkillLens 僅繪製該區塊。撰寫的最快方式：在「結構」面板中修正自動提取的圖表，按一下「複製為程式碼區塊」並貼上到 SKILL.md 中。語法：
| 行 | 意義 |
|---|---|
title: subtitle: hero: 標題 | 副標題 footer: window: cols: 4 | 頁面文字和每列卡片數 |
trigger id: 標題 [標籤] {圖示} | 頂部的觸發卡片；縮排的下面幾行是其描述 |
lane id: 標題 [標籤] (顏色 種類) | 一個泳道；顏色：綠 / 藍 / 紫 / 青 / 玫瑰 / 琥珀 / 石板灰；種類：flow（預設，鏈接）、ref（參考，未連線）、bare（無框架） |
step id: 標題 [標籤] {圖示} +optional +end | 一個步驟卡片；+end 是結束步驟（實心圖示），+optional 是虛線卡片 |
decide id: 問題？ [副標題] | 一個決策菱形 |
note: 文字 | 泳道內的備註 |
在 flow: 下方：a -> b -> c : 標籤 | 前進線條；~> 為虛線迴圈；a -> "文字" : 是 是指向簡短文字的出口 |
如果沒有 flow:，非參考泳道的卡片會按順序鏈接。圖示為 Lucide 名稱，列於 src/icons.js 中；若要新增，請從 lucide-static 複製其 SVG 本體。
修改 SkillLens
- 圖層：
markdown.js解析 →extract.js/dsl.js建立結構 →layout.js放置卡片和路由線條 →render.js繪製 SVG 並播放 →app.js為 UI。所有 UI 和圖表字串位於i18n.js中；每個鍵都需同時新增到en和zh。 - 頁面必須能透過雙擊開啟，因此使用純
<script>標籤，不使用 ES 模組。每個腳本都寫成SV.mod.name = function (SV) {…}，以便獨立匯出可用toString()內嵌程式碼。 - 每個影格必須是時間 t 的純函數（無 CSS 動畫、
Math.random或實際時鐘），否則逐幀影片錄製會失效。 - 主題：Blueprint（預設）、Midnight 和 Glass。圖表顏色在
render.js的THEMES中，UI 顏色在style.css頂部的 CSS 變數中；必須同時修改兩者。僅限 Blueprint 的細節（網格、尺規、角落刻線、卡片編號、琥珀色啟用步驟）位於P.blueprint後方。 - 字型：Noto Sans SC（中文）、Inter（拉丁）、JetBrains Mono（標籤和路徑）來自 Google Fonts，離線時回退到系統字型。版面配置使用 canvas 測量文字，因此必須等待字型載入：
app.js在loadingdone時清除度量快取並重新繪製，錄製模式和獨立匯出會先呼叫document.fonts.load載入圖表文字。請保持index.html中的字型連結、layout.js中的FONT/MONO以及獨立範本中的連結同步。 - 自動翻譯：
scripts/lib/translate.mjs（伺服器端，/api/translate）和src/app.js中的useTranslation（決定圖表中哪些字串被翻譯）。僅翻譯圖表文字和開啟的原始文字；標籤、檔案名稱、路徑以及「是」/「否」保留不譯。後端順序：當設定 API 金鑰且已安裝@anthropic-ai/sdk時使用 Anthropic SDK，否則使用本地 Claude Code CLI（在 Windows 上直接呼叫node_modules/@anthropic-ai/claude-code/bin/claude.exe以避免.cmd引號問題）。快取鍵在兩端均為lang + \u0001 + text。 - 在無頭瀏覽器中檢查變更：執行
npm run scan，然後執行node scripts/record.mjs <技能名稱> --seconds 3，或透過scripts/lib/cdp.mjs截圖。若要進行迴歸測試，請將每個技能送入SV.extract→SV.layout→SV.render.toSVG，確保沒有擲出錯誤且沒有文字溢出卡片。 - 錄製需要本地 Chrome / Edge 和 ffmpeg；如果找不到，請設定
SV_CHROME/SV_FFMPEG。 - README 主圖媒體：
docs/promo.webp（內嵌顯示的動畫）連結到原始docs/promo.mp4（含聲音的完整影片）。GitHub 永遠不會播放儲存庫的 MP4：無論檔案大小為何，都無法在 README 中內嵌播放或檔案檢視中播放，因此原始連結會直接下載；若要內嵌播放器，必須透過 github.com 編輯器上傳影片（使用user-attachmentsURL）。請使用動畫 WebP，而非 GIF：在暗色 Blueprint 漸層上，30 秒的 GIF 超過 20 MB，而 WebP 保持在 8 MB 以下且色彩更清晰。從 1080p 主檔案：ffmpeg -i master.mp4 -vf "fps=15,scale=960:-1:flags=lanczos" -c:v libwebp -quality 70 -compression_level 6 -loop 0 -an docs/promo.webp以及ffmpeg -i master.mp4 -c:v libx264 -preset slow -crf 23 -pix_fmt yuv420p -c:a aac -b:a 160k -movflags +faststart docs/promo.mp4。