夜雨聆风让AI学会用Obsidian：kepano开源神器「Obsidian Skills」全解析
作者：Steph Ango（Obsidian联合创始人）
项目地址：https://github.com/kepano/obsidian-skills
许可证：MIT
一、这是什么？
Obsidian Skills 是一套 Agent Skills（AI智能体技能包），由 Obsidian 联合创始人 Steph Ango（kepano）开源发布。它让你的 AI 编程助手（Claude Code、OpenAI Codex、OpenCode 等）真正 学会操作 Obsidian 笔记库——创建、编辑、搜索笔记，操作 Canvas 画布，编写数据库视图，甚至通过 CLI 控制 Obsidian 本体。
它遵循 Agent Skills 规范，因此任何兼容该规范的 AI 智能体都可以直接加载使用。
这套技能包含 5 个核心模块：
| obsidian-markdown | |
| obsidian-bases | |
| json-canvas | |
| obsidian-cli | |
| defuddle |
二、安装方式
2.1 通过 Hermes Agent 市场安装
/plugin marketplace add kepano/obsidian-skills
/plugin install obsidian@obsidian-skills2.2 通过 npx skills 安装
# SSH 方式
npx skills add git@github.com:kepano/obsidian-skills.git
# HTTPS 方式
npx skills add https://github.com/kepano/obsidian-skills2.3 手动安装
Claude Code 用户： 将仓库内容复制到 Obsidian 笔记库根目录下的 /.claude/ 文件夹。详见 官方文档。
Codex 用户： 将 skills/ 目录复制到 ~/.codex/skills/。
OpenCode 用户： 完整克隆仓库到 ~/.opencode/skills/obsidian-skills/，OpenCode 会自动发现所有 SKILL.md 文件，无需修改配置。
三、技能详解
3.1 obsidian-markdown — Obsidian 风味 Markdown
这是最核心的技能，教你 AI 如何编写 Obsidian 笔记。它支持以下扩展语法：
Wikilinks（维基链接）
[[笔记名称]] 链接到笔记
[[笔记名称|显示文字]] 自定义显示文字
[[笔记名称#标题]] 链接到标题
[[笔记名称#^块ID]] 链接到块
[[#同一笔记内的标题]] 同笔记标题链接在任意段落末尾添加 ^块ID 即可定义可引用块：
这段内容可以被引用。^my-block-idEmbeds（嵌入）
使用 ! 前缀即可内嵌内容：
![[笔记名称]] 嵌入整篇笔记
![[笔记名称#标题]] 嵌入特定章节
![[图片.png]] 嵌入图片
![[图片.png|300]] 嵌入图片并限定宽度
![[文档.pdf#page=3]] 嵌入PDF指定页支持嵌入音频（.mp3/.ogg）、视频、外部图片（通过标准 Markdown 图片语法）、Base 视图和搜索查询结果。
Callouts（标注框）
> [!note]
> 基本的标注框。
> [!warning] 自定义标题
> 带自定义标题的标注框。
> [!faq]- 默认折叠
> 可折叠的标注框（- 折叠，+ 展开）。支持的类型：note、tip、warning、info、example、quote、bug、danger、success、failure、question、abstract、todo。标注框可以嵌套，也可以通过 CSS 自定义样式和图标。
Properties（属性 / 前置元数据）
---
title: 我的笔记
date: 2024-01-15
tags:
- 项目
- 进行中
aliases:
- 备选名称
cssclasses:
- custom-class
---支持文本、数字、布尔值、日期、日期时间、列表和链接等多种属性类型。标签支持层级嵌套（如 #nested/tag）。
其他特色语法
==高亮文本== 高亮语法（类似荧光笔）
$e^{i\pi} + 1 = 0$ LaTeX 行内数学公式
%%这是隐藏注释%% 注释（阅读视图下不可见）支持 Mermaid 图表、脚注（[^1] 和行内脚注 ^[这样]）、任务列表等。
参考： Obsidian Flavored Markdown 官方文档
3.2 obsidian-bases — 数据库式笔记管理
Obsidian Bases 是 Obsidian 中类似 Notion 数据库的功能，以 .base 文件存储结构化笔记视图。
基础结构
# 全局过滤器（作用于所有视图）
filters:
and:
- 'status == "active"'
- not:
- 'file.hasTag("archived")'
# 公式定义
formulas:
total: "price * quantity"
status_icon: 'if(done, "✅", "⏳")'
# 视图配置
views:
- type: table
name: "任务列表"
limit: 10
order:
- file.name
- status
- formula.status_icon过滤器语法
支持 and、or、not 逻辑组合，可以深度嵌套：
filters:
or:
- file.hasTag("book")
- and:
- file.hasTag("book")
- file.hasLink("Textbook")支持比较运算符：==、!=、>、<、>=、<=
丰富的公式函数
Bases 支持强大的计算引擎，包括日期函数（now()、today()、date()、日期格式化）、字符串函数（contains()、startsWith()、replace()、slice()）、数值函数（round()、floor()、ceil()）、列表函数（filter()、map()、reduce()、sort()），以及丰富的文件属性引用：
formulas:
days_until_due: 'if(due_date, (date(due_date) - today()).days, "")'
formatted_price: 'if(price, price.toFixed(2) + " 元")'
created: 'file.ctime.format("YYYY-MM-DD")'
days_old: '(now() - file.ctime).hours.round(0)'参考： Obsidian Bases 语法官方文档
3.3 json-canvas — 可视化画布编辑
Obsidian Canvas 是一个无限画布工具，可用于制作思维导图、流程图、项目看板。它基于 JSON Canvas 1.0 规范，以 .canvas 文件存储。
文件结构
{
"nodes": [],
"edges": []
}节点类型
文本节点：
{
"id": "6f0ad84f44ce9c17",
"type": "text",
"x": 0, "y": 0,
"width": 400, "height": 200,
"text": "# 欢迎\n\n这是 **Markdown** 内容。"
}文件节点：
{
"id": "a1b2c3d4e5f67890",
"type": "file",
"x": 500, "y": 0,
"width": 400, "height": 300,
"file": "Attachments/diagram.png"
}链接节点：
{
"id": "c3d4e5f678901234",
"type": "link",
"x": 1000, "y": 0,
"width": 400, "height": 200,
"url": "https://obsidian.md"
}分组节点：
{
"id": "d4e5f6789012345a",
"type": "group",
"x": -50, "y": -50,
"width": 1000, "height": 600,
"label": "项目总览",
"color": "4"
}连接线（Edges）
{
"id": "0123456789abcdef",
"fromNode": "6f0ad84f44ce9c17",
"fromSide": "right",
"toNode": "a1b2c3d4e5f67890",
"toSide": "left",
"toEnd": "arrow",
"label": "指向"
}画布支持 6 种预设颜色（1=红、2=橙、3=黄、4=绿、5=青、6=紫），坐标可为负值（无限画布），建议节点间距 50-100 像素。节点 ID 为 16 位小写十六进制字符串。
3.4 obsidian-cli — 命令行操作 Obsidian
这个技能让 AI 能通过 Obsidian CLI 直接与正在运行的 Obsidian 交互（前提：Obsidian 必须已打开）。
常用命令
# 读取笔记
obsidian read file="我的笔记"
# 创建笔记
obsidian create name="新笔记" content="# 标题" template="模板" silent
# 追加内容
obsidian append file="我的笔记" content="新的一行"
# 搜索
obsidian search query="搜索词" limit=10
# 操作日记
obsidian daily:read
obsidian daily:append content="- [ ] 新任务"
# 设置属性
obsidian property:set name="status" value="done" file="我的笔记"
# 任务管理
obsidian tasks daily todo
# 标签统计
obsidian tags sort=count counts
# 反向链接
obsidian backlinks file="我的笔记"插件开发工作流
# 1. 重载插件
obsidian plugin:reload id=my-plugin
# 2. 检查错误
obsidian dev:errors
# 3. 截图验证
obsidian dev:screenshot path=screenshot.png
# 4. 查看控制台
obsidian dev:console level=error还支持在 Obsidian 上下文中执行 JavaScript、查看 CSS 属性值、切换移动端模拟等高级功能。
参考： Obsidian CLI 官方文档
3.5 defuddle — 网页转纯净 Markdown
这个工具由 Steph Ango 开发（https://github.com/kepano/defuddle），用于从网页中提取干净的 Markdown 内容，去除导航栏、广告等噪音。对 AI 来说，这意味着更少的 token 消耗和更高的内容质量。
# 安装
npm install -g defuddle
# 提取为 Markdown
defuddle parse https://example.com --md
# 保存到文件
defuddle parse https://example.com --md -o content.md
# 获取元数据
defuddle parse https://example.com -p title
defuddle parse https://example.com -p description相比直接抓取网页，Defuddle 能显著减少 token 用量，特别适合 AI 处理在线文档的场合。
四、项目特点与意义
4.1 为什么重要？
这是 Obsidian 迈向 AI 原生化 的关键一步。以前，AI 只能读 Markdown 文件来"理解"笔记内容。现在，AI 能：
用正确的语法创建笔记——不是普通的 Markdown，而是 Obsidian 风味 操作可视化 Canvas 画布 管理数据库式视图 通过 CLI 直接操控 Obsidian
4.2 开放的技能规范
该项目遵循 Agent Skills 规范，而不是绑定在某个特定平台上。这意味着 Claude Code 用户能用，Codex 用户能用，OpenCode 用户也能用。这是一个开放的生态。
4.3 开发者友好的设计
CLI 技能中还包含了完整的插件开发工作流——热重载、错误检测、截图验证、DOM 检查——让开发者可以用 AI 辅助开发 Obsidian 插件。
五、总结
kepano/obsidian-skills 是一个小而精的项目，它用 5 个 Agent Skills 打通了 AI 和 Obsidian 之间的壁垒。无论你是用 Claude Code 管理知识库，还是用 Codex 自动化笔记流程，这套技能都能让你的 AI 助手真正成为 Obsidian 的高效用户。
项目地址： https://github.com/kepano/obsidian-skills
作者： Steph Ango
许可证： MIT
#Obsidian#AI#知识管理#开源#效率工具#笔记#AgentSkills#ClaudeCode#Codex#PKM#自动化