首页 › skills-review › Obsidian官方下场，文件就是Agent的API

Obsidian官方下场，文件就是Agent的API

概述

本期不追新星榜单，拆一组特殊来头的东西：Obsidian 官方打包上架的 Claude Code 插件 obsidian-skills（本机缓存版本 1.0.0），内含三个官方技能——obsidian-markdown、obsidian-bases、json-canvas；再用一个社区件 obsidian-mermaid 作对照。核心发现有三：官方在 SKILL.md 第一句就写"skills-compatible agents"而不提 Claude；三件全是零脚本的纯手册型技能，把官方文档镜像进上下文；而社区件走了完全相反的守则型路线。一个领域、两种流派，恰好凑成一篇 SKILL.md 写法教科书。以下全部分析基于本机装机实测的原文。

一、这四件是怎么凑到一起的

先交代来源。本机安装路径暴露了身份：/root/.claude/plugins/cache/obsidian-skills/obsidian/1.0.0/skills/。也就是说，Obsidian 官方不是零散上架技能，而是打成了一个 Claude Code 插件包，一次带出三个技能，走插件市场分发，目前版本 1.0.0。

三个官方技能各管一种文件格式：

flowchart TD
    AG["Agent 拿到任务"]
    AG --> S1
    AG --> S2
    AG --> S3
    AG --> S4
    subgraph OFF["官方插件三件"]
        S1["obsidian-markdown"]
        S2["obsidian-bases"]
        S3["json-canvas"]
    end
    S4["obsidian-mermaid 社区件"]
    S1 -->|写对 .md| MD
    S2 -->|建对 .base| BASE
    S3 -->|画对 .canvas| CANVAS
    S4 -->|渲染不炸| MM
    subgraph VAULT["Obsidian 仓库"]
        MD["笔记文件"]
        BASE["数据库视图"]
        CANVAS["无限画布"]
        MM["内嵌图示"]
    end

拼起来看意图就很清楚了：一个 Agent 装上这套东西，等于拿到了“住进 Obsidian 仓库”的整套手艺——会写带 wikilink 和 callout 的笔记，会建笔记数据库视图，会生成画布板，画内嵌图也不会踩渲染坑。官方没有给 Agent 开任何 API，因为 Obsidian 的本质是本地纯文本文件，文件格式本身就是 API。这是所有本地优先软件做 Agent 集成时最聪明的一条路，而 Obsidian 是第一个把它做成官方插件的大厂（笔记软件范畴内）。

二、主角拆解：obsidian-bases 逐段讲

四个里最值得逐行看的是 obsidian-bases。Bases 是 Obsidian 较新版本推出的笔记数据库功能：用 .base 后缀的 YAML 文件，把整个仓库里带特定标签/文件夹/属性的笔记聚合成表格、卡片、列表视图——相当于给文件系统装了一层查询引擎。

这份 SKILL.md 的结构是一条完整的“知识产线”：

第一段：一句话定位。 开头是 "This skill enables skills-compatible agents to create and edit valid Obsidian Bases (.base) files including views, filters, formulas"。注意两个细节：一是主语是 "skills-compatible agents"——通篇没有出现 Claude 字样，这份手册是写给所有兼容 Agent Skills 规范的 Agent 的，Claude Code 只是读者之一；二是 "valid" 这个词，它预告了整份文档的核心目标不是“教思想”，而是保证产出物语法合法。

第二段：总览与格式声明。 两句话说清 Bases 是什么（"YAML-based files that define dynamic views of notes"），并点出 .base 文件也能内嵌进 Markdown 代码块——一句话堵住了 Agent 后面可能犯的存放位置错误。

第三段：完整 Schema。 直接给一个带注释的 YAML 全家福，把 filters、formulas、properties、summaries、views 五个顶层区块一次摆齐，每个字段旁边挂行内注释（type: table | cards | list | map）。这是手册型的典型手法：一个带注释的骨架，胜过十段散文。Agent 写文件时回翻这一段就能对齐结构。

第四段起：分区块深挖。 过滤器部分给了单条件、AND、OR、NOT、嵌套五种写法各配代码块；接着是两张大表——过滤运算符表（==、!=、> 直到逻辑非）和 file.* 文件属性全表（file.mtime、file.tags、file.backlinks 等十几个元数据字段）。尤其贴心的是专门列出三类属性的区分：笔记 frontmatter 属性、文件元数据属性、公式计算属性——这是 Bases 新手最容易混的概念，文档用“三选一”的方式先立框架。

第五段：公式语言全量函数表。 这是全文最重的部分，按类型分了十几张表：全局函数（date()、now()、if()、icon()）、字符串函数（contains、slice、split）、列表函数（filter/map/reduce 一应俱全，连 acc 归并都写了）。一张技能文件硬生生写成了语言规范。

第六段：那个最重要的 IMPORTANT。 全文的高光在这一段：

IMPORTANT: Duration does NOT support .round(), .floor(), .ceil() directly. You must access a numeric field first (like .days), then apply number functions.

后面紧跟正误对照：(date(due_date) - today()).days 是对的，((date(due) - today()) / 86400000).round(0) 标注 "WRONG - will cause error"。这一段的设计价值远超一张语法表——它预判了模型最可能犯的错（把日期差当数字直接运算），用大写警告加反例的方式在出错路径上提前设卡。给 LLM 写文档，反例比正例更省 token，因为它直接封死了幻觉的出口。

第七段：四个完整示例。 Task Tracker、Reading List、Project Notes、Daily Notes Index，每个都是可直接落盘的成品 YAML，覆盖了表格、卡片、分组、汇总列、正则过滤文件名（/^\d{4}-\d{2}-\d{2}$/.matches(file.basename) 过滤日记）等典型场景。示例即测试用例，Agent 可以照抄改造，比从零组装可靠得多。

结尾：References 尾链。 挂了 help.obsidian.md/bases/syntax、/bases/functions、/bases/views 三个官方文档链接。这个尾巴有两层作用：给 Agent 一个“原文在哪”的出口，同时也是权威性声明——我这份手册不是民间口口相传，是官方文档的镜像。

三、另外两件官方件：同模板，不同侧重

obsidian-markdown 和 json-canvas 与 bases 件共用同一个写作模板（一句话定位 → 总览 → 全量语法 → 示例 → References），但侧重不同。

obsidian-markdown 是四件里最“重”的——篇幅最长，覆盖了 Obsidian 方言的全部表面：[[wikilink#标题#^块引用]]、十三种 callout 类型表、可折叠 callout 的 -/+ 后缀、![[图片|300]] 尺寸语法、PDF 嵌页 ![[doc.pdf#page=3]]、frontmatter 属性类型表、%%隐藏注释%%、脚注、以及表格里竖线要转义 \| 这种细到牙缝的坑。它的定位其实是：模型都会 Markdown，但不会 Obsidian 的方言——所以通用语法（标题、列表、表格）一带而过，篇幅全砸在方言差异上。这是手册型技能的正确花钱方式。

json-canvas 有个容易被忽视的亮点：除了 JSON Canvas 1.0 规范全量搬运（四类节点、边的六种挂点、色板 "1"-"6"），它还附了两张规范里没有的表——推荐节点尺寸（小文本 200-300 × 80-150，文件预览 300-500 × 200-400）和间距指南（节点间留 50-100px、组内留 20-50px 内边距、坐标对齐 10/20 的倍数）。这是把“排版审美”也写进了规格，Agent 生成的画布因此不会出现节点叠成一团的惨案。另外它对最高频翻车点专门设卡：JSON 字符串里换行必须写 \n，写成 \\n 会渲染出字面的反斜杠和 n——并给了两个示例对照。小瑕疵是这个对照没有标明哪个是错例，读者要靠上文自己分辨，比 bases 件的 WRONG 标注略欠一档火候。

还有个命名细节：三件里只有它不带 obsidian- 前缀。因为 JSON Canvas 是 Obsidian 推动的开放格式（规范独立挂在 jsoncanvas.org），官方自己都刻意不让品牌绑死开放标准。门牌上的克制是一以贯之的。

四、对照件：obsidian-mermaid，守则型的活标本

社区件 obsidian-mermaid（本机装在 ~/.claude/skills/，个人技能）走的是完全相反的路线。它不教你 Mermaid 语法——默认你会——只列六条“必须遵守”和五条“禁止事项”，每条都带原因和正误代码对照：

用 flowchart 不用 graph，原因是兼容性；
换行用 <br> 不用 <br/>，"may cause parsing errors in Obsidian"；
sequenceDiagram 里禁用一切 style 语句，这是 Obsidian 的实测坑，文档连报错信息的样子都复现给你看（"Parse error on line 28"）；
mindmap 语法在 Obsidian 里不受支持，直接别用；
六节点以上必须用竖版 TD 布局，还给了决策标准（≤5 节点可用 LR，≥6 必须 TD）。

它甚至有“验证工作流”一节（先在 mermaid.live 调通 → 套兼容规则 → 粘进 Obsidian 实测）和一个支持度矩阵表（哪些图型全支持、哪些不支持 style）。另外它是四件里唯一用了渐进式披露的：正文末尾挂 references/PATTERNS.md，模板库下沉到子文件，正文只留守则。

对比一下就看出两种流派的分工：

	手册型（官方三件）	守则型（mermaid件）
解决的问题	不会写	会写但会写错
知识形态	全量规范+示例库	规则清单+反例库
token 成本	重（触发后数K常驻）	轻
适用领域	模型没见过的私有格式（.base/.canvas）	模型自以为会的通用格式（Mermaid）
防幻觉手段	正确Schema先行	WRONG/CORRECT对照设卡

选择的判据就一条：这个领域模型的失败模式是“不会”还是“会错”。.base 是 2025 年才出现的新格式，模型必然不会，所以官方写手册；Mermaid 是训练语料里的老熟客，模型不是不会而是自信地写出 Obsidian 不认的语法，所以守则比手册有效。官方三件里 markdown 件其实是个混合体——通用部分当手册写，方言坑（转义、嵌套代码块）部分已经在悄悄用守则的写法了。

五、评测对比表

技能	功能完整度	设计质量	实战效果	上手难度	社区活跃	总评
obsidian-bases	★★★★★	★★★★★	★★★★☆	★★★★☆	★★★★☆	4.7
obsidian-markdown	★★★★☆	★★★★☆	★★★★☆	★★★★★	★★★★☆	4.3
json-canvas	★★★★☆	★★★★☆	★★★★☆	★★★★☆	★★★★☆	4.3
obsidian-mermaid	★★★☆☆	★★★★☆	★★★★☆	★★★★★	★★★☆☆	3.8

说明：实战效果基于本机对四份原文的可生成性评估（产出物为纯文本文件，无脚本依赖，生成即可用）；社区活跃度上官方插件有 Obsidian 团队背书，mermaid 件为个人技能无法验证热度，故保守给分。

分维度排行榜：

最值得装：obsidian-bases——新格式+全量手册+坑位标注，三要素齐活，装了就能让 Agent 给仓库建索引视图；
最被低估：json-canvas——那两张布局指南表是同类技能里罕见的“审美规格化”，做路线图、读书板的人直接受益；
最有学习价值：obsidian-mermaid——想学守则型 SKILL.md 怎么写，四百行不到的它就是模板；
最快见效：obsidian-markdown——零学习成本，装上之后 Agent 写的 callout 和 wikilink 立刻不出错。

六、适用与不适用

适合装：已有成规模 Obsidian 仓库、想让 Agent 批量整理笔记/建数据库视图/生成画布板的人；用 Agent 写带 Mermaid 图的文档、受够了渲染报错的人；想研究 SKILL.md 写法的技能作者（这是本期隐藏彩蛋——四份原文本身就是两流派的范本库）。

不适合：不用 Obsidian 的人（markdown 件的方言知识也随仓库绑定，离开 wikilink 生态价值减半）；期待“Agent 操控 Obsidian 应用内操作”的人——这套技能只产出文件，不会帮你点应用菜单；Obsidian 版本较旧的用户——.base 是较新版本才支持的格式，老版本打不开产出物。

七、安装与使用

官方三件以 Claude Code 插件形式分发，在 Claude Code 会话内运行：

/plugin

在插件市场里搜索 obsidian-skills（发布方 obsidian，本机版本 1.0.0），安装后三个技能随插件自动挂载，触发词对准“写 Obsidian 笔记 / 建 base 视图 / 生成 canvas 画布”即可。社区件可用 skills 生态的检索工具定位后安装：

npx skills find obsidian-mermaid

或直接把技能目录复制进 ~/.claude/skills/（本机即为此形态）。装完用一句话验证：让 Agent “给标签为 #book 的笔记建一个带阅读状态图标的卡片视图 base”，产出物落盘后在 Obsidian 里打开不出红字，即为验收通过。

参考来源

Obsidian Bases Syntax 官方文档 — obsidian-bases 技能 References 尾链所指的官方语法页
JSON Canvas Spec 1.0 — json-canvas 技能遵循的开放格式规范
obsidianmd/jsoncanvas — JSON Canvas 官方仓库，Obsidian 官方组织的开放格式项目
Obsidian 基础格式语法 — obsidian-markdown 技能 References 首条
本机实测：obsidian-skills 插件 1.0.0 缓存目录及 ~/.claude/skills/obsidian-mermaid 原文 — 本文全部逐段引用均出自上述四份 SKILL.md

[!tip] 51学通信知识星球 星主：爱卫生（微信：gprshome201101）——公众号「51学通信」创办者，19 年通信行业运维与讲师经验，著有《GPRS网络信令实例详解》《EPC原理与实践》《5G核心网原理与实践》三本纸质书（各大电商平台有售）。 星球定位：深耕 5G 核心网、IMS、NFV/AI、云原生等 ICT 领域，主打运维岗位与信令分析。 当前规模：5200 篇主题 / 990 个回答，198 元/年。 加入福利：加入星球后请加爱卫生微信，拉您进知识星球年度陪伴与答疑群——不限量回复您的各种问题，另有群内分享。 AI 加持：51学通信知识星球已作为 skill 接入 WorkBuddy，使用 deepseek-4-flash 在海量星球帖子中精准找贴、找视频、找 FAQ 和案例，做总结、找文档和 PPT 等场景全覆盖。

51学通信知识星球海报-扫码加入