开源推荐

其他

21.8k Stars！Claude Code + Obsidian 的最强组合，这个开源项目让 AI 彻底接管笔记

发表于 2026年04月09日阅读 10 评论 0

大家好，我是何三，独立开发者

你有没有试过让 Claude Code 帮你写 Obsidian 笔记？

大概率翻车了。

AI 帮你写出来的 markdown，放到 Obsidian 里面渲染出来就是一堆乱码——wikilinks 被当普通文本，callout 语法被识别不了，canvas 文件更是完全不知道怎么生成。

这不是 AI 笨，是它根本不认识 Obsidian 的"方言"。

obsidian_skills_cover

最近 Obsidian 的创始人 kepano 干了一件正经事——他在 GitHub 上开源了一个项目叫 obsidian-skills，目前 21.8k Stars，专门解决这个问题。本质上就是给 AI Agent 写了一套"技能说明书"，让 Claude Code、Codex CLI 这些工具真正理解 Obsidian 的各种文件格式。

说白了，以前 AI 往你 Obsidian 里塞笔记，就像一个不懂中文的老外往中文文档里填内容，格式全靠蒙。现在，有了这套 Skills，AI 终于拿到了"考试大纲"。

什么是 Agent Skills？

在聊 obsidian-skills 之前，得先搞明白 Agent Skills 这个概念。

Agent Skills 是一个开放规范（specification），由 agentskills.io 维护。它的想法很直白：给 AI Agent 提供一种标准化的"技能包"格式。

一个 Skill 就是一个文件夹，核心是一个 SKILL.md 文件，里面用 YAML frontmatter 定义元信息（名称、描述），用 Markdown 写详细的指令和规则。

skill-name/
├── SKILL.md        # 必需：元信息 + 指令
├── scripts/        # 可选：可执行脚本
├── references/     # 可选：参考文档
└── assets/         # 可选：模板、资源

渐进式加载是这套规范最聪明的地方——不是一股脑把所有技能塞进上下文，而是分三步走：

发现（约100 tokens）：Agent 启动时只加载所有技能的 name 和 description
激活（建议 < 5000 tokens）：匹配到相关技能后，加载完整的 SKILL.md 指令
按需读取：需要时才加载 references/ 和 scripts/ 中的文件

这种设计对上下文窗口非常友好，你装 50 个技能也不会把 context 撑爆。

obsidian-skills 到底干了什么？

obsidian_skills_01

obsidian-skills 目前包含 5 个技能模块，覆盖了 Obsidian 的核心使用场景。

1. obsidian-markdown — 让 AI 懂 Obsidian 的 Markdown

普通 AI 写 Markdown 没问题，但 Obsidian 的 Markdown 是"加料版"。

比如 wikilinks [[笔记名]]、嵌入语法 ![[图片.png]]、callout > [!note]、frontmatter 属性、标签层级 #嵌套/标签——这些语法标准 Markdown 里都没有，AI 自然就不认识。

obsidian-markdown 技能把所有 Obsidian 特有的语法规则写成了详细的指令文档，包括：

内部链接：[[笔记名#标题]]、[[笔记名#^block-id]] 的正确写法
嵌入：笔记、图片、PDF 页码的嵌入方式
Callout：12 种预置类型（note、tip、warning、bug 等），以及折叠语法
Frontmatter：tags、aliases、cssclasses 等属性规范
数学公式：LaTeX 语法支持
Mermaid 图表：包括与 Obsidian 笔记的链接写法

装了这个技能后，你跟 Claude Code 说"帮我创建一篇带 callout 的笔记"，它真的能生成标准的 Obsidian 格式，而不是一堆普通 markdown。

2. obsidian-bases — 数据库视图不用手动配

Obsidian 1.7+ 引入了 Bases 功能（.base 文件），可以在笔记库上构建类似 Notion Database 的视图——表格、卡片、列表、地图。但 YAML 配置语法对不少人来说上手就有门槛。

obsidian-bases 技能把这个门槛压到了零。

AI 现在可以根据你的描述直接生成 .base 文件：

filters:
  and:
    - file.hasTag("task")
    - 'file.ext == "md"'

formulas:
  days_until_due: 'if(due, (date(due) - today()).days, "")'
  is_overdue: 'if(due, date(due) < today() && status != "done", false)'
  priority_label: 'if(priority == 1, "🔴 High", if(priority == 2, "🟡 Medium", "🟢 Low"))'

properties:
  status:
    displayName: Status

views:
  - type: table
    name: "Active Tasks"
    filters:
      and:
        - 'status != "done"'
    order:
      - file.name
      - status
      - formula.priority_label
      - due
      - formula.days_until_due
    groupBy:
      property: status
      direction: ASC

你只需要说"帮我建一个任务跟踪 Base，显示所有未完成的任务，按优先级排序，高亮过期的"，AI 就能生成上面这种完整的配置。支持过滤、公式、多种视图类型、分组汇总。

3. json-canvas — 白板也能 AI 生

obsidian_skills_02

Obsidian Canvas 用的是 JSON Canvas 格式，一种开放规范（jsoncanvas.org）。手动编辑 .canvas 文件？基本不可能。

json-canvas 技能让 AI 直接生成 canvas 文件——包括文本节点、文件节点、链接节点、分组节点和连接边。

{
  "nodes": [
    {
      "id": "6f0ad84f44ce9c17",
      "type": "text",
      "x": 0,
      "y": 0,
      "width": 400,
      "height": 200,
      "text": "# 项目规划\n\n这是一个 **思维导图** 节点。"
    },
    {
      "id": "a1b2c3d4e5f67890",
      "type": "file",
      "x": 500,
      "y": 0,
      "width": 400,
      "height": 300,
      "file": "Attachments/diagram.png"
    }
  ],
  "edges": [
    {
      "id": "0123456789abcdef",
      "fromNode": "6f0ad84f44ce9c17",
      "fromSide": "right",
      "toNode": "a1b2c3d4e5f67890",
      "toSide": "left",
      "toEnd": "arrow",
      "label": "参考"
    }
  ]
}

技能文档里还写了详细的布局指南：节点间距 50-100px、对齐网格线、不同节点类型的建议尺寸。所以 AI 生成出来的 canvas 排版不会乱成一团。

4. obsidian-cli — 命令行操控 Obsidian

这个技能比较硬核——通过 Obsidian CLI 与正在运行的 Obsidian 实例交互。

# 读取笔记
obsidian read file="My Note"

# 创建笔记（使用模板）
obsidian create name="New Note" content="# Hello" template="Template" silent

# 搜索
obsidian search query="关键词" limit=10

# 追加内容
obsidian append file="My Note" content="- [ ] 新任务"

# 管理属性
obsidian property:set name="status" value="done" file="My Note"

对插件开发者来说更实用，支持插件重载、错误检查、DOM 检查、截图验证、CSS 检查等：

# 开发插件时的调试循环
obsidian plugin:reload id=my-plugin
obsidian dev:errors
obsidian dev:screenshot path=screenshot.png
obsidian dev:dom selector=".workspace-leaf" text

5. defuddle — 网页内容干净提取

这个技能解决的是一个很实际的问题：你让 AI 读一个网页 URL，它经常把导航栏、广告、侧边栏全吃进来，白白浪费大量 Token。

defuddle 是一个命令行工具（npm install -g defuddle），专门提取网页中的核心内容，去掉干扰信息：

# 提取干净的 Markdown
defuddle parse https://example.com/article --md

# 保存到文件
defuddle parse https://example.com/article --md -o content.md

# 只提取元信息
defuddle parse https://example.com/article -p title

这个技能的说明里有一句很到位的话："Use instead of WebFetch when the user provides a URL to read or analyze"。能用 defuddle 就别用原始抓取。

怎么安装？

安装方式有好几种，取决于你用什么 AI Agent。

Claude Code（推荐）

最简单的方式——直接把仓库内容放到 Obsidian 库的 .claude 文件夹下：

# 在你的 Obsidian vault 根目录
npx skills add git@github.com:kepano/obsidian-skills.git

或者手动把 skills/ 目录复制到 /.claude/ 下。

Codex CLI

# 复制 skills/ 到 Codex 的技能目录
cp -r skills/ ~/.codex/skills/

OpenCode

# 克隆整个仓库
git clone https://github.com/kepano/obsidian-skills.git ~/.opencode/skills/obsidian-skills

Claude Desktop（Plugin Marketplace）

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

装好之后重启对应的 Agent，技能就自动生效了。不需要额外配置什么。

几个真实的使用场景

我自己试了几天，总结几个确实好用的场景：

场景一：批量整理笔记

我有一堆散乱的读书笔记，格式不统一。把 Claude Code 指向笔记库，装上 obsidian-markdown 技能，让它"帮我把这 50 篇笔记统一加上 frontmatter、分类标签，互相之间建立 wikilinks 关系"。

效果出乎意料——它不仅加了 tags 和 aliases，还根据内容主题自动建了几个 MOC（Map of Content）笔记作为索引。

场景二：快速建知识库视图

"帮我把所有带 #project 标签的笔记建成一个 Base，显示项目名、状态、截止日期，按状态分组，过期的标红。"

一句话的事儿。

场景三：读书笔记 → Canvas

"根据这篇读书笔记的章节结构，生成一个 Canvas 思维导图。"

生成的 canvas 直接在 Obsidian 里打开，节点排列还挺整齐的。

场景四：网页 → 笔记

丢一个 URL 给 Agent："用 defuddle 提取这篇文章，整理成 Obsidian 笔记格式保存到我的库。"

省去了手动复制粘贴、清理格式、添加标签的整个过程。

一些槽点和局限

说完好的，也得聊聊现实。

Claude Code 的上下文限制依然存在。如果你的笔记库特别大（几千篇笔记），Claude Code 搜索和遍历的时候会吃掉不少 context，复杂任务容易中途断片。obsidian-cli 的 search 功能能缓解一点，但治标不治本。

obsidian-bases 的公式语法有点坑。Duration 类型的日期运算容易出错，官方技能文档里专门写了"Duration does NOT support .round()"这种踩坑提醒。AI 生成公式时偶尔还是会犯这种错，需要人工检查。

json-canvas 的布局还是不够智能。虽然技能文档里写了间距和对齐建议，但复杂白板的节点排列逻辑 AI 还是处理不太好，简单流程图可以，几十个节点的大白板还得手动调。

兼容性问题。目前这套技能主要针对 Claude Code 做了深度适配，Codex CLI 和 OpenCode 的支持程度我还没完全验证。如果你用的是其他 Agent（比如 Cursor），可能需要手动适配。

Agent Skills 规范的更大意义

说实话，obsidian-skills 本身只是一个具体实现。我觉得更有价值的是它背后的 Agent Skills 规范。

这个规范解决了一个核心问题：怎么让 AI Agent 学会使用特定工具，而且是可以标准化的、可复用的。

想想看，如果每个工具——Notion、VS Code、Figma、Linear——都有一套标准的 Skills，AI Agent 就能真正变成"全栈助手"。不需要每个工具都自己搞一套插件系统，也不用每次都跟 AI 解释"我的工具是这样的"。

kepano 作为 Obsidian 创始人，亲自下场写这套 Skills，某种程度上也是在推动这个规范的普及。目前 agentskills.io 上已经有不少客户端支持了，包括 Claude Code、Codex CLI、OpenCode、ClawdBot 等。

这个方向，大概率会成为 AI Agent 生态的基础设施。

项目地址：https://github.com/kepano/obsidian-skills

如果你是 Obsidian 重度用户 + Claude Code 用户，这个项目建议直接 Star 加装上。如果你还没用过 AI Agent 辅助笔记，这也许是个不错的入门契机。

本文使用 MGO 编辑并发布

关注"何三笔记"，回复"mgo" 免费下载使用

版权声明：如无特殊说明，文章均为何三笔记原创，转载请注明出处

本文链接：https://www.h3blog.com/article/773/

什么是 Agent Skills？
obsidian-skills 到底干了什么？
怎么安装？
几个真实的使用场景
一些槽点和局限
Agent Skills 规范的更大意义