obsidian-skills 的 5 个技能：让 AI 代理写出规范的 Obsidian 文件

obsidian-skills 的 5 个技能：让 AI 代理写出规范的 Obsidian 文件

【免费下载链接】obsidian-skillsAgent skills for Obsidian. Teach your agent to use Obsidian CLI and open formats including Markdown, Bases, JSON Canvas.项目地址: https://gitcode.com/GitHub_Trending/ob/obsidian-skills

你让代理给笔记加个标注框，它写出来的是标准 Markdown 引用而不是> [!note]；你让它建一个 Bases 数据库视图，它交出的 YAML 在 Obsidian 里打不开——这类问题正是 obsidian-skills 要解决的。这个项目不写代码、不起服务，只用 5 份 SKILL.md 教会代理 Obsidian 在标准 Markdown 之外的扩展语法和两种结构化文件格式，把"代理改保险库"从碰运气变成可验证的流程。

代理写 Obsidian 笔记时，错在哪

Obsidian 的 .md 不是标准 Markdown。维基链接[[链接]]用于内部引用，嵌入语法![[嵌入]]可以内联另一篇笔记或 PDF 的某一页，标注框用> [!warning]起头，文件顶部还有 frontmatter 属性。这些对只见过 CommonMark 的通用代理来说都不在"常识"里。

比 .md 更麻烦的是保险库里还有两类与 Markdown 完全不同的结构化文件：**Bases 数据库视图（.base）**本质是一个 YAML 文件，**画布文件（.canvas）**本质是一段 JSON。代理写这两种文件时连可参照的"标准"都没有，只能靠猜。大多数错误就出在这里：YAML 字符串少一个引号，整个视图打不开；canvas 节点漏掉一个必填字段，文件直接失效。

SKILL.md 如何自动触发

打开仓库，第一眼注意到的是结构有多平：skills/下五个子目录，每个目录一份 SKILL.md，必要时配一个references/目录放补充材料，比如 obsidian-bases 的 references/ 里就放着完整函数参考 FUNCTIONS_REFERENCE.md。

真正的设计点在每份 SKILL.md 的 YAML 头部。name声明技能名，description则是用自然语言写的触发条件。以 obsidian-markdown 为例："Use when working with .md files in Obsidian, or when the user mentions wikilinks, callouts, frontmatter, tags, embeds……" 也就是说，用户说一句"把这个标注框改一下"，代理自己会判断该调哪个技能，不需要你指名道姓。五个技能都遵循 Agent Skills 规范，所以同一套文件放进 Claude Code、Codex、OpenCode 都能被自动发现。

五个技能各管一种文件格式

Obsidian Markdown：只教标准里没有的

obsidian-markdown 明确只覆盖 Obsidian 扩展，标题、列表这些默认你会。它的价值在于把判断规则内置进去：库内笔记用[[维基链接]]（Obsidian 会自动跟踪重命名），外部 URL 才用标准 Markdown 链接；段落尾加^block-id即可被其他笔记按块引用。完整的属性类型、标注框类型、嵌入类型分别放在 references/ 的 PROPERTIES.md、CALLOUTS.md、EMBEDS.md 里供代理按需查阅。

Bases 过滤器与公式：YAML 的坑

一个 .base 文件就是一套 YAML 数据库：filters 决定哪些笔记进入视图，formulas 计算派生字段，views 决定用表格、卡片、列表还是地图展示。筛出未完成的任务，就是视图里一条status != "done"的条件。

写对这份 YAML 比看上去讲究。技能文档内置了三个坑：含冒号等特殊字符的字符串必须加引号；两个日期相减得到的是 Duration 而不是数字，必须先取.days再做四舍五入这类数值操作；属性可能缺失，要用if()兜底。算"距截止日还有几天"就是标准写法：

formulas: days_until_due: 'if(due, (date(due) - today()).days, "")'

工作流的最后一步是验证：YAML 是否合法、每个被引用的formula.X是否真的在 formulas 里定义过，确认无误再交给 Obsidian 渲染。

JSON Canvas 的节点与边

.canvas 文件只有两个顶层数组：nodes 和 edges。技能文档规定了生成纪律：每个节点用唯一的 16 位十六进制 ID，节点类型只有 text、file、link、group 四种，节点之间留 50 到 100 像素间距；改完后逐条过验证清单——ID 全文件唯一、每条边的 fromNode 和 toNode 都能解析到真实节点。思维导图、项目看板这类完整示例放在 references/EXAMPLES.md 里。

Obsidian CLI：直接跟运行中的应用对话

前三个技能操作的都是文件，obsidian-cli 则直接跟正在运行的 Obsidian 实例对话（要求应用处于打开状态）。常用操作包括：obsidian search query="..."全库搜索，obsidian property:set name="status" value="done" file="My Note"一步改属性，obsidian daily:append往每日笔记追加内容。它还覆盖插件开发：plugin:reload、dev:errors、dev:screenshot这几个 dev 命令，能让代理自己完成"改代码、重载、查错误、截图验证"的循环，不用你盯屏。随时跑obsidian help能拿到最新的命令列表。

Defuddle：把网页剥成干净 Markdown

最后一个技能管"资料进库"这一端。defuddle parse <url> --md从网页提取干净 Markdown，去掉导航、广告和版式噪音，内容入库前就干净了，代理读网页的 token 消耗也随之下降。文档里还特意写明：以 .md 结尾的 URL 跳过这一步，因为本来就是 Markdown，没必要二次解析。

安装：两条命令起步

/plugin marketplace add kepano/obsidian-skills /plugin install obsidian@obsidian-skills

也可以用 npx skills 或手动安装。手动装时三个平台放的位置不同：Claude Code 用户把仓库内容放进保险库根目录的.claude文件夹；Codex 用户把skills/目录复制到~/.codex/skills；OpenCode 用户则要把整个仓库克隆到~/.opencode/skills/obsidian-skills——README 专门警告不要只复制内层skills/文件夹，因为发现机制依赖 SKILL.md 处于再深一层的目录结构里。

Obsidian 的文件格式都是纯文本，但方言多，每一口都有代理会踩的坑。obsidian-skills 的做法是把每口方言写成一份可触发、可验证的 SKILL.md，让代理在下笔前先"翻书"，写完先自检。这个模式本身不绑定 Obsidian——任何需要代理写特定方言的场景，都可以照此办理。

【免费下载链接】obsidian-skillsAgent skills for Obsidian. Teach your agent to use Obsidian CLI and open formats including Markdown, Bases, JSON Canvas.项目地址: https://gitcode.com/GitHub_Trending/ob/obsidian-skills