编程 Obsidian Skills 深度解析：当 Agent Skills 规范让 AI Agent 真正"接管"本地知识库

2026-04-09 07:23:15 +0800 CST views 24

Obsidian Skills 深度解析：当 Agent Skills 规范让 AI Agent 真正"接管"本地知识库

背景：当 CEO 亲自下场开源"技能包"

2026年1月，Obsidian CEO Steph Ango（社区人称 kepano）在 GitHub 发布了一个只有 37 个 commit 的小型仓库：kepano/obsidian-skills。项目上线仅 9 天，斩获 6.6k Star，成为 Obsidian 社区最受瞩目的效率神器。更引人注目的是 kepano 亲自写的 README：不是插件，不是主题，而是一套让 AI Agent 真正理解 Obsidian 文件格式的技能包。

这个举动之所以引发社区震动，是因为它代表了一种截然不同的 AI 集成思路。当 Notion、飞书、Noteworthy 们都在往 UI 里塞"Ask AI"按钮时，Obsidian 选择了一条相反的路：不改变 UI，让 Agent 学会 Obsidian 的底层文件格式。

这不是一个插件，这是一次理念的降维打击。

一、Agent Skills 规范：比 MCP 更"知识驱动"的 AI 集成标准

理解 Obsidian Skills 的价值，首先要理解它所基于的规范：Agent Skills。

1.1 什么是 Agent Skills 规范

Agent Skills 是由 Anthropic 在 Claude Code 中推广的一种开放标准，定义在 agentskills.io 上。与我们熟悉的 MCP（Model Context Protocol）相比，Skills 的定位有本质区别：

MCP 是工具协议：定义 AI 如何调用外部工具（浏览器、文件系统、API），强调"能做什么"
Skills 是知识包：定义 AI 如何正确理解特定领域格式和任务规范，强调"怎么做对"

换句话说，MCP 告诉 Agent"你有一把锤子"，而 Skills 告诉 Agent"这是一把羊角锤，拔钉子时要这样握"。对于 Obsidian 这样拥有独特文件格式生态的工具来说，后者才是真正的痛点。

1.2 Agent Skills 的标准结构

每个 Skill 目录结构遵循统一规范：

obsidian-skills/
├── skills/
│   ├── obsidian-markdown/     ← 技能目录
│   │   ├── SKILL.md           ← 核心定义文件（必需）
│   │   ├── instructions.md   ← 详细指令
│   │   └── examples/          ← 示例文件
│   ├── obsidian-bases/
│   ├── json-canvas/
│   ├── obsidian-cli/
│   └── defuddle/
└── README.md

SKILL.md 是核心，它包含 AI Agent 需要遵循的格式规范、语法规则和最佳实践。Claude Code、Codex CLI、OpenCode 等主流 Agent 平台都会在执行任务前读取这些文件，将技能知识注入上下文。

1.3 Obsidian Skills 完整技能矩阵

当前仓库包含 5 个核心技能，覆盖 Obsidian 生态的完整能力层：

技能名称	覆盖格式	核心能力
obsidian-markdown	.md	wikilinks、embeds、callouts、properties、Obsidian Flavored Markdown
obsidian-bases	.base	views、filters、formulas、summaries（Obsidian 数据库）
json-canvas	.canvas	nodes、edges、groups、connections（Canvas 画布文件）
obsidian-cli	CLI	vault 管理、插件开发、主题开发
defuddle	-	从网页提取干净 Markdown，消除噪音节省 Token

二、架构解析：五把钥匙打开 Obsidian 的五道门

2.1 obsidian-markdown：让 AI 读懂 Obsidian 的 Markdown 方言

标准 Markdown 简单优雅，但 Obsidian 在此基础上扩展了一套完整的方言体系。obsidian-markdown 技能的目标就是让 AI Agent 精确掌握这套方言。

Wikilinks 语法是 Obsidian 最标志性的特性：

[[笔记标题]]           ← 链接到同仓库笔记
[[笔记标题#章节]]      ← 链接到特定章节
[[笔记标题|显示文本]] ← 自定义显示文字
![[图片.png]]         ← 直接嵌入（感叹号）

AI Agent 常见的错误是在生成笔记时混用标准 Markdown 链接和 Wikilinks，或者忽略 Obsidian 的嵌入语法。obsidian-markdown 技能通过详细的格式规范和代码示例，确保 AI 始终生成符合 Obsidian 规范的链接语法。

**Callouts（提示块）**是另一个关键扩展：

> [!note] 这是一个提示
> 内容在这里

> [!warning]- 可折叠的警告块
> 详细内容可以折叠

Callouts 支持多种类型：note、tip、warning、danger、bug、example、quote、success、todo。每种类型还有可选的折叠属性（- 展开，+ 折叠）。AI 如果不理解这套语法，要么生成丑陋的引用块，要么完全忽略这个强大的组织工具。

**Properties（前置元数据）**是 YAML Frontmatter 的 Obsidian 版本：

---
title: 笔记标题
tags: [标签1, 标签2]
created: 2026-01-01
modified: 2026-04-08
aliases: [别名1, "另一个别名"]
cssclasses: [highlight]
---

Properties 不仅用于元数据管理，还深度集成 Obsidian 的 Graph View、标签搜索和 Dataview 插件。AI 只有理解了这些字段的语义，才能真正参与 Obsidian 的知识管理自动化。

2.2 obsidian-bases：让 AI 学会"数据库笔记"

Obsidian Bases（代号"Datasette"）是 Obsidian 官方的数据库插件，允许用户用纯文本 YAML/JSON 格式定义数据表，并在笔记中用类 SQL 语法查询。

一个 Bases 数据库文件（.base）示例：

type: base
id: contacts
views:
  - id: default
    type: table
    columns:
      - name
      - email
      - department
      - joined
data:
  - name: 张三
    email: zhangsan@example.com
    department: 工程部
    joined: 2025-01-15
  - name: 李四
    email: lisi@example.com
    department: 产品部
    joined: 2025-03-20

在笔记中查询：

```dataview
TABLE name, email, department
FROM #员工
WHERE department = "工程部"
SORT joined DESC
```

obsidian-bases 技能教会 AI：如何创建符合规范的 .base 文件，如何在笔记中编写 Dataview 查询，以及如何将自然语言需求转化为精确的数据库查询。这对于构建个人 CRM、项目管理数据库、读书笔记系统等场景极为有用。

2.3 json-canvas：让 AI 画出一张知识地图

Obsidian Canvas 是 2023 年引入的画布功能，允许用户在一个视觉空间中组织笔记、图片、文档和链接。Canvas 文件本质上是 JSON：

{
  "nodes": [
    {
      "id": "node-1",
      "type": "text",
      "data": { "text": "核心概念" },
      "position": { "x": 0, "y": 0 },
      "width": 200,
      "height": 80
    },
    {
      "id": "node-2",
      "type": "file",
      "data": { "path": "笔记标题.md" },
      "position": { "x": 300, "y": 0 }
    }
  ],
  "edges": [
    {
      "id": "edge-1",
      "fromNode": "node-1",
      "fromSide": "right",
      "toNode": "node-2",
      "toSide": "left"
    }
  ]
}

json-canvas 技能让 AI Agent 能够：解析 Canvas 的 JSON 结构，理解节点坐标和尺寸的含义，生成符合规范的画布文件。这意味着 AI 可以根据用户的知识图谱描述，自动生成一张可视化的 Canvas 知识地图。

2.4 obsidian-cli：让 AI 操作保险库

Obsidian CLI（obsidian 命令）提供了命令行操作 vault 的能力：

# 打开特定 vault
obsidian --vault /path/to/vault

# 打开指定笔记
obsidian --vault /path/to/vault --file "笔记标题.md"

# 以只读模式打开
obsidian --vault /path/to/vault --readonly

# 开启新窗口
obsidian --vault /path/to/vault --new-window

obsidian-cli 技能不仅让 AI 知道这些命令，更重要的是：如何在插件开发场景下使用 CLI，如何通过命令行触发 Obsidian 的内部功能，以及如何结合 shell 脚本实现 vault 自动化管理。

2.5 defuddle：从网页提取干净 Markdown 的秘密武器

defuddle 是 kepano 开发的另一个独立工具（同样是开源项目），专门用于从任意网页提取干净的 Markdown 内容，剔除广告、导航栏、cookies 提示等噪音。

# 安装
npm install -g defuddle-cli

# 使用
defuddle https://example.com/article

在 Obsidian Skills 体系中，defuddle 的价值在于：当 AI Agent 需要为 Obsidian 笔记收集网页内容时（如研究型笔记），它可以直接调用 defuddle 获取干净的内容，节省大量 Token 成本。根据测试，使用 defuddle 提取的内容比直接抓取 HTML 省 60-80% 的 Token。

三、实战：Claude Code + Obsidian Skills 打造 AI 知识管理自动化

3.1 安装配置

安装 Obsidian Skills 支持多种主流 Agent 平台，kepano 在 README 中提供了详细的平台适配指南：

Claude Code：

# 方式1：通过 Claude Code plugin marketplace
npx skills add git@github.com:kepano/obsidian-skills.git

# 方式2：手动安装到 vault 的 .claude 目录
git clone https://github.com/kepano/obsidian-skills.git
cp -r obsidian-skills/skills /path/to/your-vault/.claude/

Codex CLI：

git clone https://github.com/kepano/obsidian-skills.git
cp -r obsidian-skills/skills ~/.codex/skills/obsidian-skills

OpenCode：

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

Claudian 插件（Obsidian 内置 Claude Code 界面）：

Claudian 是 Obsidian 的第三方插件，在 Obsidian 内置了一个 Claude Code 兼容界面，让用户直接在 Obsidian 中调用 AI 进行笔记管理。结合 Obsidian Skills，Claudian + Obsidian Skills 构成了一个完整的本地 AI 知识管理闭环。

# Claudian 插件安装（手动旁加载）
# 1. 下载 claudian 仓库的 main.js、manifest.json、styles.css
# 2. 放入 vault 根目录/.obsidian/plugins/claudian/
# 3. 重启 Obsidian，在"第三方插件"中启用

Claudian 还支持自定义模型，比如用智谱 GLM 或 DeepSeek 替换 Claude：

ANTHROPIC_BASE_URL=https://open.bigmodel.cn/api/anthropic
ANTHROPIC_API_KEY=你的智谱api_key
ANTHROPIC_DEFAULT_OPUS_MODEL=GLM-5.0

3.2 自动化场景演示

场景1：AI 自动整理阅读笔记

用户给 Claude Code 一个指令："帮我把这周收集的 20 篇论文摘要整理成 Obsidian 笔记，每篇按 title/author/date/journal/key-findings 结构化，用 callout 标注重要发现。"

在没有 Obsidian Skills 的情况下，Claude Code 可能：

使用标准 Markdown 链接而不是 Wikilinks
忽略 callout 语法，统一用普通引用块
忘记在 frontmatter 中添加 tags 和 created 字段
混用不同格式的列表和表格

有了 obsidian-markdown 技能后，Claude Code 会自动遵循 Obsidian 规范生成完全合规的笔记结构。

场景2：AI 自动生成知识图谱 Canvas

用户告诉 Claude Code："根据我的读书笔记《深度学习》和《强化学习》的内容关系，生成一张 Canvas 画布，节点是核心概念，边是它们之间的关系。"

Claude Code 读取两篇笔记 → 提取核心概念和关系 → 生成 JSON Canvas 文件：

{
  "nodes": [
    {"id": "n1", "type": "text", "data": {"text": "梯度下降"}, "position": {"x": 0, "y": 200}},
    {"id": "n2", "type": "text", "data": {"text": "反向传播"}, "position": {"x": 300, "y": 200}},
    {"id": "n3", "type": "file", "data": {"path": "深度学习.md"}, "position": {"x": 150, "y": 0}},
    {"id": "n4", "type": "text", "data": {"text": "Q-Learning"}, "position": {"x": 300, "y": 400}},
    {"id": "n5", "type": "file", "data": {"path": "强化学习.md"}, "position": {"x": 150, "y": 600}}
  ],
  "edges": [
    {"id": "e1", "fromNode": "n1", "toNode": "n2"},
    {"id": "e2", "fromNode": "n2", "toNode": "n3"},
    {"id": "e3", "fromNode": "n1", "toNode": "n4"},
    {"id": "e4", "fromNode": "n4", "toNode": "n5"}
  ]
}

3.3 与 MCP 的协同

Obsidian Skills 不是 MCP 的替代品，而是互补关系。MCP 提供运行时能力（"帮我打开 Obsidian 并切换到某篇笔记"），Skills 提供格式知识（"帮我生成符合 Obsidian 规范的笔记内容"）。

在实际工作流中，两者可以协同工作：

用户指令 → Claude Code（Skills 注入格式知识）
         → MCP 插件（调用 Obsidian CLI 执行操作）
         → 干净输出（Wikilinks + Callouts + Properties 完整合规）

四、核心洞察：为什么 Skills 比插件更有战略价值

4.1 "底层接管"策略的优势

大多数知识管理工具选择"AI 功能插件化"路线：Notion AI、Obsidian Sync with AI、Notability Smart Notes……这些方案的特点是：AI 功能是 UI 的一部分。

kepano 的思路截然不同：让 AI 理解底层文件格式，AI 功能通过文件格式本身实现。

这个策略的优势在于：

平台无关：生成的文件在任何 Obsidian 客户端都能正确打开
可移植：用户完全掌控自己的数据，不被特定 AI 服务绑定
可组合：Obsidian Skills 生成的文件可以无缝对接 Dataview、Templater、kanban 等插件
Token 高效：不需要在每次交互时传递大量上下文知识，Skills 文件本身就是知识

4.2 以小博大的工程哲学

从代码行数看，obsidian-skills 仓库只有 37 个 commit，每个技能不过几百行 SKILL.md 和示例。这与动辄数万行的 AI 插件形成鲜明对比。

但正是这种"少即是多"的设计哲学，让 Skills 的边际成本极低——Anthropic 推出 Agent Skills 规范后，kepano 只需一个人、一周时间，就让 Claude Code"学会"了 Obsidian 的全部格式知识。无需 SDK，无需 API 调用，只需写好 SKILL.md。

这正是 Obsidian 一直以来的工程哲学：用文本格式代替二进制存储，用约定优于配置代替复杂配置，用文件本身作为 API。

4.3 Obsidian Skills 在 AI Agent 叙事版图中的位置

回顾本博客构建的 AI Agent 技术叙事，我们已经覆盖了：

GitNexus：AI Agent 的"代码执行神经系统"——如何让 Agent 真正执行代码
MemPalace：AI Agent 的"宫殿记忆法"——如何让 Agent 持久化记住一切
Obsidian Skills：AI Agent 的"知识管理工具箱"——如何让 Agent 正确理解和操作本地知识库

三者构成了一个完整的能力三角：执行（GitNexus）× 记忆（MemPalace）× 知识管理（Obsidian Skills）。

加上本博客已经覆盖的 OpenHarness（Python Agent 编排）、Superpowers（AI 编程 Agent 技能框架）、Claw Code（Claude Code 的 Rust 重写版）、Everything Claude Code（Claude Code 性能优化系统），整个 AI Agent 的技术图谱已经覆盖了从底层执行引擎到中间编排层到上层知识管理的完整链路。

五、技术限制与使用建议

5.1 当前版本的技术限制

多 Vault 支持：Skills 目前假设单一 vault 工作区，多 vault 场景需要手动指定路径
实时同步冲突：当 Agent 和用户同时编辑同一笔记时，没有冲突解决机制
Plugin 状态理解：Skills 能生成笔记内容，但不理解自定义插件的元数据格式
中文搜索优化：Wikilinks 的中文别名支持在不同客户端间存在差异

5.2 使用建议

Vault 结构先行：在引入 AI Agent 之前，先设计好 vault 的目录结构和命名约定，AI Agent 会在这个框架内更高效工作
CLAUDE.md 是你的宪法：在 vault 根目录创建 CLAUDE.md，向 AI Agent 说明你的知识管理偏好和笔记规范
渐进式引入：先从 obsidian-markdown 开始，等熟悉了 Agent 的行为模式后再引入 Bases 和 Canvas
定期备份：虽然 Obsidian 是本地存储，但 AI Agent 的自动化操作可能产生意外修改，定期版本控制是必要的

总结：AI Agent 的"知识操作"新范式

Obsidian Skills 的出现，标志着 AI Agent 从"能做什么"向"如何做对"的进化。当 GitNexus 解决了 Agent 的代码执行问题，MemPalace 解决了 Agent 的记忆持久化问题，Obsidian Skills 则补完了 Agent 的最后一个关键能力：精确操作本地知识资产。

更重要的是，kepano 用一个只有 37 个 commit 的小型仓库，展示了 AI 集成的另一种可能性：不追求功能集成到 UI，而是追求 AI 对底层格式的深度理解。这条路的边际成本更低，可移植性更强，也许会成为未来 AI 与本地工具集成的主流范式。

Agent Skills 规范的价值，不仅限于 Obsidian。一旦这个规范被更多工具采用（已经有多个工具开始支持 Agent Skills），AI Agent 将能够以一种统一的方式与各种本地应用深度集成——不是通过 API，而是通过共享的"技能知识"。

这也许是 AI 与本地软件集成的下一场范式转移。