给 AI Agent 装上「Obsidian 使用手册」

你有没有过这种经历：花了一整晚在 Obsidian 里精心整理笔记，第二天却发现 AI 根本读不懂你的 wikilink、callout、或者 .canvas 画布文件？问题的根源在于——主流 AI Agent 默认只会写标准 Markdown，而 Obsidian 那套独特的扩展语法（双链、嵌入、数据库视图），对它来说就像一门从未学过的方言。

kepano/obsidian-skills 就是来解决这个问题的。这个由 Obsidian 创始人 kepano 亲自维护的项目，本质上是一套 AI Agent 的「Obsidian 使用手册」。它用 Agent Skills 规范 编写，让 Claude Code、Codex CLI、OpenCode 这些主流 AI 编程工具，能够准确理解并生成 Obsidian 专有的文件格式。

背景故事：Obsidian 创始人的 AI 布局

2025 年初，kepano 在 X 上发了一条动态，宣布要开发一套专门给 AI 看的 Obsidian 技能包。他提到自己在使用 Claude Code 时，发现 AI 根本无法正确处理 .md 文件里的双链语法——它会把 [[Note Name]] 当成普通方括号文本对待。这促使他决定自己动手，给 AI 写一份「Obsidian 方言速成指南」。

目前 kepano 在 GitHub 上拥有超过 7100 名关注者，是 Obsidian 生态最核心的开发者之一。这个项目不仅解决了他的个人痛点，也填补了 Agent Skills 生态中 Obsidian 垂直场景的空白。

核心技术：5 个技能模块的分工协作

这套技能包包含 5 个独立模块，每个模块负责一种 Obsidian 文件类型的读写规范：

最核心的是 obsidian-markdown，它详细规定了 wikilinks 的 8 种写法（普通链接、锚点、块引用、同笔记内链接等），callout 的所有类型（note/tip/warning/danger/query 等），以及 frontmatter 属性的标准写法。AI 拿到这个技能包之后，就知道 ![[embed]] 是嵌入语法、> [!tip] 是提示框，而不是把它当作普通引用符号处理。

obsidian-bases 则让 AI 理解 Obsidian Bases——一种用 YAML 定义的数据视图格式，支持 table/cards/list/map 四种展示模式，还能写公式做数据聚合。

json-canvas 模块基于 JSON Canvas 1.0 规范，教 AI 正确创建和编辑 .canvas 文件，包括节点的唯一 ID 生成规则（16位十六进制）、边连接的 fromNode/toNode 引用关系，以及位置坐标的布局逻辑。

部署方式：一条命令搞定

项目遵循 Agent Skills 规范，所以安装方式高度标准化。

最简单的方式是通过 npx 一键安装：

# SSH 方式
npx skills add git@github.com:kepano/obsidian-skills.git

# HTTPS 方式（国内推荐）
npx skills add https://github.com/kepano/obsidian-skills

安装完成后，AI Agent 就自动具备了 Obsidian 格式的读写能力。Claude Code 用户可以把仓库内容放到 /.claude 文件夹；Codex CLI 用户放到 ~/.codex/skills；OpenCode 用户则 clone 到 ~/.opencode/skills/obsidian-skills。

此外还支持 Claude Code 的 /plugin marketplace 方式安装，以及通过 npx skills 的插件市场安装，整个过程不超过 2 分钟。

典型使用场景

想象这样一个场景：你让 Claude Code 帮你整理一年的读书笔记。传统的 AI 可能会生成这样的链接：[参见《深度工作》笔记](./深度工作.md)——这是一个 Markdown 标准链接，一旦你重命名文件，链接就失效了。

但有了 obsidian-markdown 技能后，AI 会自动生成 [[深度工作]] 这样的 wikilink。Obsidian 的双链机制会自动追踪重命名，笔记之间的联系不会因为文件改名而断裂。这就是「让 AI 理解 Obsidian 语法」的实际价值。

再比如，你想用 Obsidian Bases 做一套读书管理数据库。AI 会帮你生成符合规范的 .base YAML 文件，定义 filters 筛选条件、formulas 聚合公式、以及 table/cards 等视图配置，而不是输出一个四不像的 JSON。

局限与边界

这个项目本质上是一个技能定义包（SKILL.md 文件集合），不包含实际的运行时代码。它不提供 API 服务、不需要 GPU、不需要 Docker，甚至不需要安装任何依赖——只要你的 AI Agent 支持 Agent Skills 规范，就能直接使用。

值得注意的是，defuddle 模块依赖 npm 安装的 defuddle CLI 工具，如果未安装 npm install -g defuddle，该技能无法正常工作。另外，目前 5 个技能都是纯规范定义，缺少示例 Obsidian vault 的演示项目，新用户需要一定的 Agent 使用经验才能快速上手。

行业意义：从「让 AI 用工具」到「让 AI 懂工具」

obsidian-skills 的出现代表了一种新趋势：不是让 AI 学会使用 Obsidian，而是让 AI 理解 Obsidian 的思维方式。传统 MCP（Model Context Protocol）方案是让 AI 通过 API 调用 Obsidian，而 Agent Skills 方案是直接让 AI「学会」Obsidian 的文件格式规范。

后者更轻量、更灵活——不需要部署服务端、不需要配置 OAuth、不需要维护 API 版本兼容。但它也有局限：技能包只能处理格式正确的文件，如果 vault 中存在损坏的 YAML 或格式混乱的 canvas，AI 同样会困惑。

kepano 在 X 上的粉丝和社区反馈表明，很多用户发现这套技能包比 MCP 方案更稳定、更易维护。目前项目在 GitHub 上已有 32,800+ Stars，是 obsidian-skills 这个 topic 下最受关注的项目。

总结一句话：如果你在用 Obsidian 管理知识，同时又在用 Claude Code 或 Codex CLI 辅助编程，obsidian-skills 是目前让两者无缝协作的最简方案。