SkillLens：使用与维护
SkillLens 将任何 SKILL.md 转换为动画泳道流程图：卡片代表步骤，菱形代表决策，实线向前推进，虚线循环返回，发光圆点沿连线移动，亮起的卡片为当前步骤。界面和固定的图表文字支持英文（默认）和中文；右上角的“中 / EN”按钮可切换。
title: SkillLens
subtitle: 输入 SKILL.md · 自动提取 · 动画流程图输出
hero: SkillLens | 导入 · 提取 · 调整 · 导出
trigger start: 想要理解一个技能 [When] {bell}
读取工作流
检查或展示它
lane L1: 导入 [import] (green)
step open: 打开 SkillLens [start.bat] {play}
列出所有本地技能
每次保存时重绘
step add: 拖拽或粘贴 [drop] {upload}
文件夹、.md 文件
或粘贴文本
lane L2: 提取 [extract] (blue)
decide has: 存在 skillflow 块？ [skillflow?]
step auto: 启发式提取 [auto] {sparkles}
章节 → 泳道
步骤 / 决策 / 循环
step check: 对照源文件检查 [review] {scan-eye}
点击卡片查看其文本
查看其连接关系
step tune: 在结构面板中调整 [edit] {pencil}
应用后重绘
复制为代码块
lane L3: 输出 [export] (purple)
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 Name=<path>，或在仓库根目录放置skillviz.config.json：{"roots":[{"label":"团队技能","dir":"<path>"}]}。
编写易于图表化的技能
提取规则位于 src/extract.js。按以下方式编写的 SKILL.md 无需 skillflow 块即可正确生成图表：
- 将流程放在
## Workflow/## Steps/## Process等标题下，使用有序列表或带编号的###子章节；每个步骤写作**简短标题**：说明。 - 以“如果…”/“是否…”开头表示决策；
如果 X，则执行 Y会变成一个带“是”出口的菱形。 - 路由表写作两列表格，左列标题为“状态 / 条件 / 如果”，右列标题为“动作 / 执行 / 路由”：将变为一系列优先匹配的决策。
- 循环写作“返回步骤 N 直到…”。
- 可选步骤前加
[如果必要]/[可选]；卡片会有虚线边框。 ## Rules/## Notes下的规则变为琥珀色备注；## Reference下的内容变为无连接的参考泳道。
skillflow 块（精确控制）
当 SKILL.md 中包含 ```skillflow 块时，SkillLens 仅绘制该块。最快的编写方式：在结构面板中修正自动提取的图表，点击“复制为代码块”并粘贴到 SKILL.md 中。语法：
| 行 | 含义 |
|---|---|
title: subtitle: `hero: title | subtitle footer: window: cols: 4` |
trigger id: 标题 [标签] {图标} | 顶部的触发卡片；下方缩进行为它的描述 |
lane id: 标题 [标签] (颜色 类型) | 泳道；颜色：green / blue / purple / teal / rose / amber / slate；类型：flow（默认，链式）/ ref（引用，无连接）/ bare（无框架） |
step id: 标题 [标签] {图标} +optional +end | 步骤卡片；+end 为结束步骤（实心图标），+optional 为虚线卡片 |
decide id: 问题？ [副标题] | 决策菱形 |
note: 文字 | 泳道内的备注 |
a -> b -> c : 标签 位于 flow: 下方 | 前进线；~> 为虚线循环；a -> "文字" : 是 为指向简短文字的出口 |
没有 flow: 时，非参考泳道的卡片按顺序链接。图标使用 Lucide 名称，列于 src/icons.js；要添加新图标，从 lucide-static 复制其 SVG 主体。
修改 SkillLens
- 分层架构：
markdown.js解析 →extract.js/dsl.js构建结构 →layout.js放置卡片和路由连线 →render.js绘制 SVG 并播放动画 →app.js为用户界面。所有界面和图表字符串位于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 <skill> --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。