开发者指南：如何为 axton-obsidian-visual-skills 扩展自己的可视化 Skill（SKILL.md + references 结构实战）

开发者指南如何为 axton-obsidian-visual-skills 扩展自己的可视化 SkillSKILL.md references 结构实战【免费下载链接】axton-obsidian-visual-skillsVisual Skills Pack for Obsidian: generate Canvas, Excalidraw, and Mermaid diagrams from text with Claude Code项目地址: https://gitcode.com/gh_mirrors/ax/axton-obsidian-visual-skills本文以 Obsidian 可视化技能包 axton-obsidian-visual-skills 为例教你用「SKILL.md references」结构扩展自己的可视化 Skill。这个 Skill 包让 Claude Code 仅凭一句自然语言就能生成 Excalidraw、Mermaid 和 Obsidian Canvas 三类图表——而整个项目没有任何一行运行时代码核心就是几份 Markdown 文件。读完本文新手也能复刻出属于自己的第一套可视化 Skill。效果预览三种可视化 Skill 的产出先看看这个 Skill 包的最终效果。下面的手绘风关系图由 excalidraw-diagram 技能生成文本中的概念、关系和层级被自动转换为带颜色编码的图表三个技能各有分工技能目录产出格式擅长场景excalidraw-diagram/.md/.excalidraw手绘风流程图、思维导图、对比图mermaid-visualizer/Mermaid 代码块流程图、时序图、状态图obsidian-canvas-creator/.canvas思维导图画布、自由布局画布看懂 SKILL.md references 目录结构整个 Skill 包的目录长这样每个技能就是一个独立文件夹axton-obsidian-visual-skills/ ├── excalidraw-diagram/ │ ├── SKILL.md # 技能定义触发条件核心规则 │ └── references/excalidraw-schema.md # 完整 JSON Schema 参考 ├── mermaid-visualizer/ │ ├── SKILL.md │ └── references/syntax-rules.md # 语法规则与报错预防 └── obsidian-canvas-creator/ ├── SKILL.md ├── assets/ # 现成模板画布文件 │ ├── template-mindmap-simple.canvas │ └── template-freeform-grouped.canvas └── references/ ├── canvas-spec.md # Canvas JSON 格式规范 └── layout-algorithms.md # 布局与防重叠算法这个「三层分工」正是本项目最值得抄的写法SKILL.md 是入口只放触发条件、工作流程和硬性规则模型每次都会加载它references/ 是资料库完整规范、算法细节、语法表都放这里模型按需才去读取assets/ 是锚点放可运行的示例文件如 template-mindmap-simple.canvas给模型一个标准答案。SKILL.md 头部写出让模型叫得醒的 description打开 mermaid-visualizer/SKILL.md最上面是一段 YAML frontmattername: mermaid-visualizer description: Transform text content into professional Mermaid diagrams... Use when users ask to visualize concepts, create flowcharts...这里藏着 Skill 开发的黄金法则name技能唯一标识和目录名保持一致最好description决定 Skill 何时被调用。要同时写清做什么 什么时候用 覆盖哪些触发词。对比 excalidraw-diagram/SKILL.md 的 description它直接列出了中英双语触发词Excalidraw、画图、流程图、动画图……。用户说什么词Skill 就该在描述里出现什么词——这是让技能被稳定触发的关键。references 分工原则主文件讲怎么做参考资料讲按什么标准做以 Mermaid 技能为例SKILL.md 里只保留 5 条致命语法规则如列表符号冲突、subgraph 命名末尾一句话指向 references/syntax-rules.md完整语法参考和边界情况见 syntax-rules.md而 400 多行的完整语法表、排查清单全部沉在 references 里。Canvas 技能同理SKILL.md 写工作流与间距常量格式细节放 canvas-spec.md定位算法放 layout-algorithms.md。这样分层的收益很明显SKILL.md 保持精简模型每次加载不浪费上下文参考资料又随时可达复杂问题不会答非所问。四步扩展你自己的可视化 Skill第一步新建独立目录SKILL.md 放顶层在技能目录下创建SKILL.md需要深度资料再建references/需要示例产物就建assets/。一个文件夹一个技能互不干扰。第二步frontmatter 埋好触发词仿照本项目的写法description里写清做什么、何时用、触发词列表中英文触发词都要覆盖。比如你的技能是画架构图就加上架构图、architecture diagram等词。第三步主文件只留工作流 硬规则参考三个现成技能的共性结构Overview一句话说清产出物Workflow编号步骤分析内容 → 选类型 → 生成 → 校验 → 输出Critical Rules不可违反的硬约束字符替换、间距下限、禁用 Emoji 等Common Mistakes踩坑清单这是提升输出质量最划算的部分References明确写出何时去读哪个 reference 文件。第四步用 assets 模板兜底obsidian-canvas-creator/assets/ 里放了两份可直接打开的模板画布等于给模型提供了金标准。你的技能如果输出 JSON、YAML 等结构文件也建议放一份最小合法示例模型照着模仿远比照着描述猜要稳。另外两种效果Mermaid 与 Canvas下面的 Mermaid 层级流程图由 mermaid-visualizer 生成配色自带语义输入绿、决策红、处理紫而 Canvas 技能生成的彩色卡片画布则可以在 Obsidian 中直接拖动、连线适合做项目规划与知识整理三个常见坑新手最容易写错的地方⚠️坑一把规范全部堆进 SKILL.md。主文件越写越长模型每次加载都在浪费上下文。记住SKILL.md 讲怎么做references 讲按什么标准做。⚠️坑二description 只写功能不写触发词。技能没被叫起来写得再好也白搭。对照 excalidraw-diagram/SKILL.md 的写法把用户口头可能说出的词都列进去。⚠️坑三references 文件没人引用。模型不会主动翻文件夹。必须在 SKILL.md 中显式写出遇到 X 情况时读取 references/xxx.md参考 canvas-spec.md 在 SKILL.md 中的Load these references when写法。总结一份 SKILL.md 编写清单✅ 目录名 技能名SKILL.md 放顶层✅ frontmatter 含 name 带触发词的 description✅ 主文件结构Overview → Workflow → Critical Rules → Common Mistakes → References✅ 细节规范拆到 references/并写明读取时机✅ assets/ 放最小可运行示例对照 README.md 了解三个技能的用法再结合本文的四步法你就可以为 Obsidian 扩展出属于自己的可视化 Skill 了。更多许可信息见 LICENSE。【免费下载链接】axton-obsidian-visual-skillsVisual Skills Pack for Obsidian: generate Canvas, Excalidraw, and Mermaid diagrams from text with Claude Code项目地址: https://gitcode.com/gh_mirrors/ax/axton-obsidian-visual-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考