Article

项目研究：obsidian-skills — Obsidian CEO 给 AI Agent 的操作手册

项目研究：obsidian-skills

蓝色像素虾在 Obsidian 知识库方言卡片前工作
图 1：obsidian-skills 的价值，是让 Agent 按 Obsidian 的方言改笔记。

仓库：github.com/kepano/obsidian-skills 作者：Steph Ango（网名 kepano）——Obsidian 官方 CEO 本人 星标：9 天 6.6k Star，Obsidian 社区当红炸子鸡 本质：Anthropic Agent Skills 规范的官方参考实现，专为 Obsidian 知识库定制

「这是什么」一句话定性

它是 Obsidian CEO 写给 AI Agent 的"操作手册"——5 张"专家配方卡片"，让 Claude Code / Codex / OpenCode 等 AI 助手在编辑你的笔记时，按 Obsidian 的规矩来，不会把你的 [[双链]]、![[嵌入]]、> [!note] callout 写成普通 Markdown 废掉。

比喻：以前 AI 是个不懂 Obsidian 规矩的实习生，你让它改笔记，它把 [[红楼梦]] 改成 [红楼梦]，把 callout 改成普通引用，把 .canvas 文件结构破坏。现在 kepano 给它发了一本"内部 SOP 手册"，它照着规矩动手。

「它怎么转」逻辑全景图

五张 Obsidian Skills 配方卡组合成知识库操作手册
图 2：5 个 skill 像配方卡一样，分别约束笔记、数据库、Canvas、CLI 和网页清洗。
├─ 触发层：什么时候需要它？
│   ├─ 你用 Claude Code / Codex / OpenCode 让 AI 改 Obsidian 笔记
│   ├─ AI 编辑后打开发现：双链断、callout 消失、frontmatter 错乱、canvas 节点错位
│   └─ 想批量把网页内容扒进 Obsidian（保留 markdown 结构）
│
├─ 核心层：5 张"专家配方卡片"
│   ├─ obsidian-markdown ── Obsidian 风格 Markdown 标准
│   │   ├─ 双链语法 [[]] 和嵌入 ![[]]
│   │   ├─ Callout 块 > [!note]/[!warning]/[!tip]
│   │   ├─ Frontmatter（YAML 元数据）
│   │   ├─ 标签 #tag 和 MOC（Map of Content）
│   │   └─ 代码块、数学公式、Mermaid 图
│   │
│   ├─ obsidian-bases ── Obsidian 的数据库视图（.base）
│   │   ├─ Views（table / cards / list）
│   │   ├─ Filters / Formulas / Summaries
│   │   └─ ⚠️ 实测：此 skill 还在早期，复杂查询支持有限
│   │
│   ├─ json-canvas ── JSON Canvas 思维导图（.canvas）
│   │   ├─ 节点（nodes）：text / file / link / group
│   │   ├─ 边（edges）：节点之间的连接关系
│   │   └─ 分组（groups）：视觉上的区域划分
│   │
│   ├─ obsidian-cli ── 通过命令行操作 Obsidian
│   │   ├─ 插件开发（创建/调试/打包）
│   │   ├─ 主题开发
│   │   └─ 批量任务（移动/重命名/导出）
│   │
│   └─ defuddle ── 把网页扒成干净 Markdown
│       ├─ 去掉导航、广告、弹窗
│       ├─ 保留正文结构（标题、列表、代码块）
│       └─ 省 token（实测可减 60-80%）
│
├─ 输出层：怎么判断做对了？
│   ├─ Obsidian 打开笔记无报错、无黄底警告
│   ├─ 双链能正常跳转、嵌入能正常显示
│   ├─ callout 渲染成彩色块（不是普通引用）
│   └─ canvas 在 Canvas 视图里能正常布局
│
└─ 卡点层：新手最容易翻车的 3 个地方
    ├─ ❌ 复制目录路径错了：OpenCode 必须 clone 整个 repo 到 ~/.opencode/skills/obsidian-skills/，而不是只复制里面的 skills/ 子目录
    ├─ ❌ 装了不重启：装完必须重启 Claude Code / Codex，新 skill 才被加载
    └─ ❌ 期待 obsidian-bases 万能：这是个高频踩坑点，CSDN 实测报告说"专注于 Obsidian 数据库功能，但实测不可用"——复杂查询和公式支持还很粗糙

「怎么升级」三段位路线图

入门段（能用）

做一件事：选一个你常用的 AI 编程工具，按官方 README 装上 5 个 skill，重启验证。

  • Claude Code 用户：把仓库复制到 Obsidian vault 根目录的 /.claude/skills/
  • Codex 用户：复制 skills/ 目录到 ~/.codex/skills/
  • OpenCode 用户：git clone 整个仓库到 ~/.opencode/skills/obsidian-skills/

验证命令：在 AI 对话框问「列出你当前可用的所有 skill」——能看到 5 个 obsidian 开头就是装好了。

进阶段（用好）

补两个认知： 1. Skill = 协议，Agent = 引擎：这是 Anthropic 推的开放标准（agentskills.io/specification），不只是给 Claude 用，未来所有兼容 agent 都能用。理解了这一点，你就理解了 Skill 的本质——带目录结构的提示词包（SKILL.md 是说明书，scripts/ 是工具，examples/ 是样例）。 2. 5 个 skill 是组合拳，不是单选：让 AI 改笔记，先 obsidian-markdown 写格式 → 再 json-canvas 调整布局 → 最后 obsidian-cli 触发一次"重新加载"。三步走才有"丝滑感"。

高手段（用活）

本质差距在"自建 Skill"：kepano 的 5 个是官方参考答案。高手会看 skills/obsidian-markdown/SKILL.md 的写法，照样画葫芦，为自己的工作流写私有 Skill——比如： - 写一个「公司周报 Skill」，内置你们公司的固定章节模板 - 写一个「学术论文 Skill」，内置 GB/T 7714 引用格式 - 写一个「公众号 Skill」，内置你常用的开头结尾套路

真正的护城河不是用别人的 Skill，而是会造自己的 Skill。看 kepano 的仓库结构（每个 skill 一个目录 + SKILL.md），1 小时就能学会怎么写。

「能用在哪」场景迁移

直接平移的场景

场景 1：把这种"协议 + 配方卡"模式移植到 Notion / Logseq 这两个也是知识库工具，但没出官方 Skill。你可以照 kepano 的目录结构，给 Notion API 写一套 skill（处理 database、page、block 的 schema），给 Logseq 写一套（处理 block 引用、page 命名空间）。原理一模一样：让 AI 按工具的"方言"说话，而不是用通用英语。

场景 2：把 defuddle（网页→干净 Markdown）单独拿出来用 defuddle 不只是 Obsidian skill，它本身是个独立的网页抓取工具（github.com/kepano/defuddle）。你可以用在： - 公众号爬虫：抓竞品文章，剥掉广告和导航 - 学术资料归档：把 arXiv 摘要转成纯 markdown 入库 - 新闻聚合：每天自动抓 10 个行业站点，去重入 Obsidian

部署这个项目的好处和坑

Obsidian Skills 安装路径、重启加载和语法保持风险图
图 3：路径、重启、skill 冲突和 bases 成熟度，是落地时最容易踩的坑。

好处： - ✅ 零成本：纯文本 SKILL.md，不依赖任何 API key，不联网 - ✅ 跨平台：Claude Code、Codex、OpenCode 都能用，未来还会有更多 agent 支持 - ✅ 官方背书：Obsidian CEO 本人写的，权威性最强，不会突然弃坑

风险： - ⚠️ obsidian-bases 不成熟：实测报告指出这个 skill 还在早期，复杂查询容易翻车。如果你的核心场景是 .base 数据库操作，先观望 - ⚠️ Skill 加载顺序敏感：如果同时装了多个社区 Skill，可能有冲突。建议每个 Skill 先单独跑一遍验证 - ⚠️ 版本绑定：Obsidian 本身在快速迭代（canvas 2.0、bases 公测），skill 可能滞后于官方功能

一句话总结

obsidian-skills 的灵魂是"协议先行，配方跟上"——kepano 用它给整个 AI Agent 行业打了个样：知识管理工具和 AI 助手的协作，不应该是各自为战，而是用一套开放标准把"方言"统一起来。9 天 6.6k Star 不是因为 5 个 skill 多牛，而是因为这个"协议 + 配方"的范式被验证了。

返回列表