每日一个开源项目（第148篇）：obsidian-skills - Obsidian CEO 亲写的 AI Agent 格式规范，让 Agent 不再破坏你的 Vault

引言

"大多数 Agent 把 Obsidian vault 看成普通文件夹，不理解 Obsidian 的语法规范。这意味着它们写出来的'笔记'要么破坏现有格式，要么根本无法在 Obsidian 里正常渲染。"

这是"每日一个开源项目"系列的第148篇文章 。今天的主角是 obsidian-skills------Obsidian CEO Steph Ango（kepano）亲手编写的官方 AI Agent Skill 集合。

你让 Claude Code 帮你在 Obsidian vault 里创建一些笔记，然后打开 Obsidian 一看：wikilink 被写成了 [Note Name](note-name.md) 而不是 [[Note Name]]，embed 语法全错了，callout 没有正确格式，Properties 的 YAML frontmatter 被放到了文件正文里......

这是一个真实的痛点：AI Agent 没有学过 Obsidian 特有的语法扩展，默认按照标准 Markdown 的方式来处理，结果就是格式错误的文件。Obsidian 的内部链接跟踪系统依赖 [[wikilink]] 格式，用了标准 Markdown 链接就脱离了 Obsidian 的链接图谱。

obsidian-skills 是官方的解答。由 Obsidian CEO 本人写，在 2026 年 1 月发布，39.3k Stars------这个数字说明 Obsidian 重度用户对于"让 AI Agent 真正理解 vault"这个需求有多强烈。

你将学到什么

AI Agent 在操作 Obsidian vault 时会犯哪些典型错误
5 个 Skill 各自教会 Agent 什么：obsidian-markdown / obsidian-bases / json-canvas / obsidian-cli / defuddle
obsidian-markdown SKILL.md 的详细内容：wikilink、embed、callout、Properties 的完整规范
在 Claude Code、OpenCode、Codex 里的安装方式
defuddle：从网页提取干净 Markdown 来节省 token 的工具

前置知识

日常使用 Obsidian（了解 wikilink、callout 等基本概念）
使用过 Claude Code 或类似 AI 编程工具
希望让 AI 帮助管理 Obsidian 知识库

项目背景

项目简介

obsidian-skills 是一套专为 Obsidian 设计的 Agent Skill 集合，遵循 agentskills.io 开放标准，让 Claude Code、Codex、OpenCode 等支持 Skill 的 AI Agent 能够正确处理 Obsidian 特有的文件格式。

"正确处理"是关键词。Obsidian 在标准 CommonMark Markdown 之上增加了大量扩展语法------wikilink、embed、callout、Properties、内联标签......这些语法在训练数据里占比很低，AI Agent 没有很好地学到它们，会默认退回到标准 Markdown 的处理方式，结果就是格式损坏的文件。

作者介绍

作者: Steph Ango（GitHub: kepano）------Obsidian CEO，Minimal 主题作者
身份意义: 这是 Obsidian 的创始人亲手写的官方 Skill，不是第三方实现
License: MIT
发布时间: 2026 年 1 月

项目数据

⭐ GitHub Stars: 39,300+
🍴 Forks: 2,800+
📄 License: MIT

AI Agent 操作 Obsidian 时的典型错误

安装 obsidian-skills 之前，Agent 面对一个 Obsidian vault 会这样处理：

1. wikilink 变成标准链接

markdown 复制代码

# Agent 写的（错误）：
[相关笔记](related-note.md)

# 正确的 Obsidian 格式：
[[相关笔记]]

用标准链接的后果：Obsidian 的双向链接图谱失效，重命名文件时链接不会自动更新。

2. embed 语法错误

markdown 复制代码

# Agent 写的（错误）：
![图片](attachment.png)

# 正确的 Obsidian embed：
![[attachment.png]]     ← 嵌入文件
![[Note Name]]          ← 嵌入另一篇笔记
![[Note#Section]]       ← 嵌入特定章节

3. callout 格式不对

markdown 复制代码

# Agent 写的（错误）：
> **注意**：这是一个重要提示

# 正确的 Obsidian callout：
> [!note] 这是标题
> callout 内容在这里

4. Properties/frontmatter 位置错误

Properties 必须是文件的第一个内容块，用三横线包裹。Agent 经常把 YAML 元数据混入正文，或者格式写错导致 Obsidian 解析失败。

5 个官方 Skill

Skill 1：obsidian-markdown

功能：教会 Agent Obsidian Flavored Markdown 的完整规范。

SKILL.md 里包含一个 6 步工作流：

markdown 复制代码

1. 添加 frontmatter（Properties）
2. 写正文内容
3. 用 wikilink 链接相关笔记
4. 用 embed 嵌入内容
5. 用 callout 强调重要信息
6. 验证格式（确保渲染正确）

详细规范涵盖：

Internal Links（Wikilinks）：

markdown 复制代码

[[笔记名]]                    ← 基本 wikilink
[[笔记名|显示文字]]           ← 自定义显示文字
[[笔记名#章节标题]]           ← 链接到特定章节
[[笔记名#^block-id]]         ← 链接到特定块

Embeds：

markdown 复制代码

![[笔记名]]                   ← 嵌入整篇笔记
![[图片.png]]                 ← 嵌入图片
![[文档.pdf#page=3]]          ← 嵌入 PDF 特定页

Callouts：

markdown 复制代码

> [!note] 可选标题
> callout 内容

> [!warning]- 折叠的 callout
> 这个 callout 默认折叠

> [!tip]+ 展开的 callout
> 这个 callout 默认展开

可用类型：note、warning、tip、info、success、question、failure、bug、quote

Properties（YAML frontmatter）：

yaml 复制代码

---
tags: [标签1, 标签2]
aliases: [别名1, 别名2]
cssclasses: [custom-class]
created: 2026-07-02
---

其他 Obsidian 扩展语法：

内联标签：#标签、#嵌套/标签
隐藏注释：%%这里是注释，不在预览模式显示%%
高亮：==高亮文字==
LaTeX 数学：行内 $公式$ 、独立行 $$公式$$
Mermaid 图表（支持 Obsidian 笔记链接）

Skill 2：obsidian-bases

功能：教会 Agent 创建和编辑 .base 文件------Obsidian 的本地数据库视图格式。

.base 文件可以把 vault 里的笔记当成数据库来查询和展示：

diff 复制代码

功能覆盖：
- 创建和编辑视图（表格视图、画廊视图等）
- 设置过滤条件（按标签、日期、Properties 字段筛选）
- 定义公式（类似电子表格的计算）
- 配置摘要（聚合统计）

这是 Obsidian 相对新的功能（原生数据库），Agent 训练数据里几乎没有覆盖，Skill 是目前最权威的格式文档之一。

Skill 3：json-canvas

功能：教会 Agent 创建和编辑 .canvas 文件------Obsidian 的白板格式，也是 JSON Canvas 开放标准。

json 复制代码

// .canvas 文件格式示例
{
  "nodes": [
    {"id": "node1", "type": "text", "text": "想法 A", "x": 0, "y": 0, "width": 200, "height": 100},
    {"id": "node2", "type": "file", "file": "相关笔记.md", "x": 300, "y": 0, "width": 200, "height": 100}
  ],
  "edges": [
    {"id": "edge1", "fromNode": "node1", "toNode": "node2"}
  ]
}

Agent 可以用代码方式创建复杂的思维导图和知识地图，而不只是在 GUI 里拖拽。

Skill 4：obsidian-cli

功能：教会 Agent 通过命令行与 Obsidian vault 交互，以及进行插件和主题开发。

覆盖场景：

批量操作 vault 中的文件
使用 Obsidian URI 协议触发操作
插件开发的目录结构和 API 规范
主题开发的 CSS 变量和规范

Skill 5：defuddle

功能：从网页提取干净的 Markdown 内容，去除广告、导航、侧边栏等噪声------专为节省 token 而设计。

css 复制代码

输入：一个 URL 或者 HTML 内容（包含广告、导航菜单、侧边栏等）
输出：干净的 Markdown 正文

应用场景：
  "帮我把这篇文章保存到 vault 里"
  → Agent 用 defuddle 提取干净内容
  → 生成格式正确的 Obsidian 笔记
  → 不用把整个带噪声的 HTML 塞进上下文

Defuddle 同时有独立的开源项目（kepano/defuddle），obsidian-skills 里的 Skill 教会 Agent 如何调用它。

项目详细剖析

为什么 39.3k Stars

这个数字对于"本质上是 5 个 Markdown 文件"的项目来说出奇地高，说明几件事：

Obsidian 用户群的特点：Obsidian 的核心用户对于知识管理和工具整合有很高的热情，是最早拥抱 AI Agent 工具的群体之一。

需求的真实性：AI 把 Obsidian vault 格式破坏这个问题，是 Obsidian 用户社区里讨论了很久的痛点，官方解答一出来就迅速传播。

作者身份的信号：Obsidian CEO 亲写，意味着这不是社区摸索出来的近似方案，而是基于最权威的格式理解写的规范。

安装方式

Claude Code（推荐方式）：

把仓库内容放到 vault 根目录的 /.claude 文件夹里：

bash 复制代码

# 进入你的 Obsidian vault 根目录
cd /path/to/your/vault

# 克隆到 .claude 目录
git clone https://github.com/kepano/obsidian-skills .claude/skills/obsidian-skills

或者用 npx：

bash 复制代码

npx skills add https://github.com/kepano/obsidian-skills

OpenCode：

bash 复制代码

git clone https://github.com/kepano/obsidian-skills.git ~/.opencode/skills/obsidian-skills

注意：克隆的是整个仓库 ，不只是内部的 skills/ 目录，否则路径解析会出错。

Marketplace（在支持的 Agent 里）：

bash 复制代码

/plugin marketplace add kepano/obsidian-skills

Skill 自动激活

安装后，Agent 不需要每次手动指定用哪个 Skill。当检测到任务涉及 Obsidian 相关操作时，Agent 自动加载对应的 Skill：

lua 复制代码

你说："帮我在 vault 的 daily-notes 文件夹里创建今天的日记笔记，
       包含今天的待办事项和会议记录，并链接到相关项目笔记"

Agent 检测到 Obsidian 文件操作
    ↓
自动加载 obsidian-markdown SKILL.md
    ↓
按照 Skill 规范生成：
  - 正确的 YYYY-MM-DD.md 文件名
  - 包含 tags 和 date 的 Properties frontmatter
  - 用 [[项目笔记名]] 格式的 wikilink 链接
  - 格式正确的 callout 用于重要事项

与 Agent Skill 生态的关系

obsidian-skills 遵循 agentskills.io 开放标准，和 android/skills（Google 官方 Android 开发 Skill）、agent-skills（Addy Osmani 的工程规范 Skill）使用同一套格式。

这意味着：

同一套 Skill 文件跨 Claude Code、Codex、OpenCode 无修改可用
任何遵循 Agent Skills 标准的新工具发布后都能直接用

实际使用场景

场景一：研究资料归档

arduino 复制代码

"把这个 URL 的内容保存到我的 vault/research/ 目录，
 提取关键观点，用 callout 标注，并链接到相关已有笔记"

→ Agent 用 defuddle 提取干净 Markdown
→ 用 obsidian-markdown 规范生成格式正确的笔记
→ 自动创建 wikilink 指向相关笔记

场景二：知识整理

arduino 复制代码

"扫描 vault 里关于机器学习的笔记，
 创建一个 .canvas 思维导图，把它们的关系可视化"

→ Agent 用 obsidian-cli 读取 vault 内容
→ 用 json-canvas 规范生成 .canvas 文件
→ 节点和边按照正确格式生成

场景三：批量格式迁移

scss 复制代码

"把 vault 里所有用标准 Markdown 链接写的 [笔记](note.md) 格式
 转换成 Obsidian 的 [[笔记]] 格式"

→ Agent 知道 wikilink 的正确语法
→ 批量修改不会误伤其他链接类型
→ 外部链接不受影响

项目地址与资源

🌟 GitHub : kepano/obsidian-skills
🌐 Obsidian 官网 : obsidian.md
🔧 Defuddle 独立项目 : kepano/defuddle
📖 JSON Canvas 标准 : jsoncanvas.org
🌐 Agent Skills 标准 : agentskills.io

总结

obsidian-skills 的价值有两层。

表面层：解决了 AI Agent 破坏 Obsidian 格式的具体问题------5 个 Skill 文件，教会 Agent 正确使用 wikilink、embed、callout、Properties，让你的 vault 不再被 AI 写出的格式错误文件污染。

更深的一层：这是 Obsidian CEO 亲手写的官方信号------Obsidian 这类工具正在把 AI Agent 当作第一类公民来对待，个人知识库正在变成 Agent 可以读写的基础设施，而不只是你自己打字的地方。

对于 Obsidian 重度用户，这个 Skill 几乎是必装的：它让 Claude Code 从"会破坏 vault 格式的危险工具"变成了"真正能帮你管理第二大脑的助手"。

探索 PrimeSkills ------ 精选 AI Agent 与技能的市场，每一个都经过真实企业工作流验证，去掉浮夸，留下真正有用的。

欢迎访问我的个人主页，发现更多有价值的见解和有趣的产品。