Obsidian Skills：让你的 AI Agent 真正驾驭知识库

Smars
技能 , 开源
08 Jun, 2026

AI Agent 能写代码、会翻网页，但碰你自己的文档就傻眼了。不管 Claude Code 多聪明，它不知道你的 Obsidian vault 里 wikilink 怎么写、callout 怎么嵌套、properties 怎么配。结果就是 agent 给你的 markdown 在 Obsidian 里渲染错乱，或者干脆就是个空壳。

Obsidian Skills 解决了这个问题。一个 35k Star 的开源项目，专门教 agent 使用 Obsidian 生态的标准格式。核心思路很简单：不是给 agent 一段泛泛的”你是知识管理者”提示词，而是给它一份精确的操作手册——每个文件类型的语法、每种命令的参数、每个错误该怎么处理。这不是提示工程的问题，这是知识注入的方式问题。

为什么你需要这个

你在 Obsidian 里积累了成百上千个笔记。想用 AI 帮你做点事：整理标签、提取摘要、生成数据库视图、批量修改格式。你打开 Claude Code，告诉它”帮我把这些笔记转成结构化数据”，它给你一段标准 markdown。你贴进 Obsidian，发现三级标题没缩进、引用块断了、链接全变成 URL 而不是 wikilink。

Agent Skills 规范的出现让这个问题有了系统解法。它定义了一种标准化的 SKILL.md 格式，任何兼容 agent（Claude Code、Codex、OpenCode）都能读取并遵循。Obsidian Skills 是这套规范的典型实现：把 Obsidian 专有格式的每一个操作场景写成规则，agent 照着执行即可。

内置技能一览

这个项目目前提供了五个核心 skill：

obsidian-markdown — 创建和编辑 Obsidian Flavored Markdown。包括 wikilinks（[[链接]]）、embeds（![[嵌入]]）、callouts（> [!info] 注释块）、frontmatter properties、以及所有 Obsidian 特有的 markup 语法。agent 学会的是完整规范的 OFM 语法，不是一知半解的”大概长得像 markdown”。

obsidian-bases — 创建和编辑 Obsidian Bases 文件（.base）。这是 Obsidian 类似 Notion Database 的表格功能。skill 覆盖视图配置、filter 表达式、formula 语法、summary 聚合函数。agent 能直接生成可运行的 .base 文件。

json-canvas — 操作 JSON Canvas 文件（.canvas）。Canvas 是 Obsidian 的白板功能，支持节点、连线、分组、连接关系。skill 定义了 canvas 文件的 JSON schema 结构，agent 写入的数据能被 Canvas 正确渲染。

obsidian-cli — 通过 Obsidian CLI 与 vault 交互。覆盖了插件开发、主题开发相关的命令行接口。CLI 是给 agent 最直接的 programmable 操作路径。

defuddle — Web 内容抓取清洗。用 Defuddle 把网页转换为干净的 markdown，去除导航栏、广告、脚本等噪音，节省 token 用量，同时保持内容结构和可读性。这个项目本身就是 kepano 开发的，说明作者有实际的 web scraping 经验。

安装方式

三种方式都行，选一个顺手的：

# Marketplace（推荐）
/plugin marketplace add kepano/obsidian-skills
/plugin install obsidian@obsidian-skills

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

# 手动安装（OpenCode）
git clone https://github.com:kepano/obsidian-skills.git ~/.opencode/skills/obsidian-skills

OpenCode 会自动发现在 ~/.opencode/skills/ 下的所有 SKILL.md，不需要改任何配置文件，重启后就生效。

Claude Code 把仓库内容复制到 vault 根目录的 .claude 文件夹下。Codex 把 skills 目录拷贝到 ~/.codex/skills。

它和其他方案的区别

很多教程会说”在你的 system prompt 里告诉 agent 怎么用 wiki 语法”。这能勉强工作几次，但很快会暴露出问题：system prompt 太长塞不下所有语法细节、agent 每次对话都在消耗宝贵的上下文窗口、换一个新的 agent 又要重写一遍。

Skill 文件的优势在于它被设计为按需加载。agent 只有在需要操作某类特定文件格式时才会读对应 skill 的内容。这意味着你的主 prompt 可以保持精简——只有真正需要 Obsidian 技能时才激活相应模块。这和传统的 monolithic system prompt 完全不同。

还有一个容易被忽略的点：一致性。一个 monolithic prompt 靠记忆维护，不同人写的 prompt 效果差异很大。一个经过团队测试的 SKILL.md 文件可以被任何人复用，质量可控。这对团队协作很关键。

适用场景

个人知识库自动化：批量修改笔记格式、自动归类、生成索引
内容生产管线：从收集到整理到发布的完整工作流自动化
团队协作共享标准：团队统一笔记格式和元数据规范
plugin/theme 开发辅助：CLI skill 帮助 agent 编写 Obsidian 插件

适用场景

个人知识库自动化：批量修改格式、自动归类、生成索引
内容生产管线：从收集到整理到发布的完整工作流自动化
团队协作共享标准：团队统一笔记格式和元数据规范
plugin/theme 开发辅助：CLI skill 帮助 agent 编写 Obsidian 插件

踩坑提醒

Obsidian 自身迭代很快，OFM 语法的边缘特性可能在新版本里有行为变化。如果 agent 生成的 callout 样式在某版 Obsidian 里不显示，先检查版本兼容性。另外，JSON Canvas 文件的 schema 仍在演进，写入前最好在 Obsidian 里手动验证一下渲染结果。

项目本身维护状态良好，最近一个月内更新频繁。Star 数增长很快，社区活跃度不错。Issues 响应速度看作者的投入节奏。

Agent 不会自动懂你的工具。它需要明确的规则，而不是一份模糊的任务描述。Obsidian Skills 的价值不在于多创新——它把一件简单的事情系统化地做干净了。

安装命令汇总

# OpenCode（推荐）
git clone https://github.com:kepano/obsidian-skills.git ~/.opencode/skills/obsidian-skills

# Codex
npx skills add https://github.com/kepano/obsidian-skills

# 其他兼容 Agent Skills 规范的 tool
cp -r obsidian-skills/skills/* ~/.YOUR_AGENT/skills/