kepano/obsidian-skills · 上手攻略

• 仓库：kepano/obsidian-skills
• 链接：https://github.com/kepano/obsidian-skills
• 分类：skill · ai
• 作者：Tom
• 更新：2026-07-05

这是什么

obsidian-skills 是由 kepano（Obsidian 核心插件开发者）维护的 Agent Skills 集合，让 AI 编程助手（Claude Code、Codex、OpenCode 等）能够理解并操作 Obsidian 的专有格式。遵循 Agent Skills 规范，以 .claude/skills/ 目录结构 + SKILL.md 元数据格式提供 5 个原子 Skill，覆盖 Obsidian Markdown、Bases 数据库、JSON Canvas、CLI 操作和网页内容提取。

仓库 stars 39K+，周增 +539，是目前 Obsidian 生态面向 AI Agent 最系统的技能包。

解决什么问题

Obsidian 的核心资产——笔记、知识库、Canvas 图谱——以一套独特的文件格式存储（Obsidian Flavored Markdown、Bases、JSON Canvas）。通用 AI Agent 由于不了解这些格式的细节（wikilink 语法、callout 块写法、Bases 的视图语法、Canvas 节点格式），写出的内容往往格式错误或无法被 Obsidian 正确解析。

obsidian-skills 通过提供精确的格式规范和操作指南，让 Agent 能够正确读写 Obsidian 各类文件，实现"用自然语言管理 Obsidian 知识库"的体验，适合： - 将 Obsidian 作为第二大脑，希望 AI 辅助组织笔记 - 有大量历史笔记需要批量整理/迁移 - 希望 AI 参与知识图谱构建、数据库维护

快速安装

安装到 Claude Code

# 方式一： marketplace（如果 Claude Code 版本支持）
/plugin marketplace add kepano/obsidian-skills

# 方式二：手动 clone 到 .claude 目录
git clone https://github.com/kepano/obsidian-skills.git \
  ~/.claude/skills/obsidian-skills
# 注意：不是只复制 skills/ 子目录，而是整个仓库
# 最终路径：~/.claude/skills/obsidian-skills/skills/<skill-name>/SKILL.md

安装到 Codex

# 复制 skills/ 目录到 Codex skills 路径
cp -r skills/ ~/.codex/skills/obsidian-skills/

# 或直接 clone
git clone https://github.com/kepano/obsidian-skills.git \
  ~/.codex/skills/obsidian-skills

安装到 OpenCode

# clone 到 OpenCode skills 目录
git clone https://github.com/kepano/obsidian-skills.git \
  ~/.opencode/skills/obsidian-skills

# OpenCode 自动发现 ~/.opencode/skills/ 下所有 SKILL.md
# 无需修改 opencode.json，重启 OpenCode 即可生效

前置要求

• Obsidian vaults（至少一个本地 vault 路径，Skill 需要知道 vault 位置）
• 对应 AI 编码助手（Claude Code / Codex / OpenCode）
• 部分 skill 需要 Obsidian CLI（obsidian 命令），可通过 Obsidian 设置 → 选项 → 第三方服务开启

核心用法

5 个 Skill 速览

obsidian-markdown 核心语法

---
uid: 2026-07-05-note
tags: [ai, agent, tutorial]
created: 2026-07-05
---

# 标题

普通正文。链接到另一篇笔记：[[another-note]]

## Callout 块（Obsidian 特有）

> [!note] 这是一个 Callout
> Callout 内容可以跨行

## 属性（Frontmatter）

笔记顶部用 YAML frontmatter 存储元数据。
Obsidian 支持 `uid`、`tags`、`created`、`modified` 等标准字段。

## 嵌入（Embed）

![[another-note]]   <!-- 嵌入整篇 -->
![[another-note#section]]  <!-- 嵌入章节 -->
![[image.png]]      <!-- 嵌入图片 -->

obsidian-bases 核心语法（.base 文件）

{
  "type": "view",
  "views": [
    {
      "type": "table",
      "columns": ["名称", "分类", "完成状态"],
      "filter": "完成状态 != 'done'"
    }
  ],
  "formula": {
    "字段名": "=row['A'] + row['B']"
  }
}

⚠️ 注意：Bases 语法较新（Obsidian 1.6+ 内测），正式发布后可能存在 Breaking Changes，建议搭配 Obsidian 官方 Bases 文档（https://help.obsidian.md/bases/syntax）对照使用。

json-canvas 核心语法（.canvas 文件）

{
  "nodes": [
    {
      "id": "node-1",
      "type": "text",
      "text": "# 主节点\n这是核心概念",
      "x": 100, "y": 100, "width": 300, "height": 200
    },
    {
      "id": "node-2",
      "type": "text",
      "text": "相关概念",
      "x": 450, "y": 100, "width": 200, "height": 150
    }
  ],
  "edges": [
    {
      "id": "edge-1",
      "fromNode": "node-1",
      "fromSide": "right",
      "toNode": "node-2",
      "toSide": "left"
    }
  ]
}

defuddle：干净的网页抓取

# defuddle 通常作为 Skill 在 Agent 内部调用
# Agent 调用时自动去除网页中的广告、侧边栏、Cookie 弹窗等
# 输出纯 Markdown，保留标题、段落、代码块等核心内容
# 常用于：
# - 将博客文章保存为 Obsidian 笔记
# - 批量将网页资料整理入库
# - RAG 场景下的网页内容抓取

# GitHub: https://github.com/kepano/defuddle

Agent 使用示例（自然语言驱动）

用户：帮我把浏览器里那篇关于 HyperFrames 的文章保存到我的 Obsidian vault，
      存到 AI/Tools 文件夹，标签打上 ai 和 video。

Agent（加载 obsidian-markdown + defuddle skill）：
1. 使用 defuddle skill 抓取网页内容
2. 解析标题、正文、代码块
3. 生成 frontmatter（tags: [ai, video]）
4. 写入 vault 路径：AI/Tools/hyperframes-notes.md
5. 报告完成

典型适用场景

① 批量知识库整理 有大量零散笔记或收藏的网页，想用 AI 批量提取内容并规范化为 Obsidian 格式，配合 defuddle 和 obsidian-markdown 可实现全自动。

② 多智能体知识管理 在 OpenCode 或 Codex 中，多 Agent 协作管理同一个 Obsidian vault——一个 Agent 负责抓取网页，一个负责分类打标签，一个负责更新索引卡片。

③ Canvas 可视化知识图谱 用 json-canvas skill 让 Agent 按文本描述生成知识图谱 Canvas 文件，适合将一本书的章节关系或一个项目的依赖结构可视化。

④ Obsidian 插件/主题开发 obsidian-cli skill 支持通过命令行操作用户仓库和插件，适合 CI 自动化测试 Obsidian 插件。

坑与注意

1. Vault 路径告知 Agent：Skill 不会自动发现 vault 位置，需要用户告知 Agent vault 根目录路径，Agent 才能正确写入文件。
2. Bases 格式仍在演进：.base 文件格式在 Obsidian 1.6+ 仍为实验性功能（2026 年中），生产使用前请确认 Obsidian 版本和 Bases 功能是否已稳定。
3. 不处理插件特有内容：Skill 覆盖 Obsidian 核心格式，但不支持社区插件的专有格式（如 Dataview 的 inline field、 Templater 模板语法等），这类内容需要单独安装对应 skill。
4. defuddle 依赖 Kepano 维护的 defuddle 服务：抓取质量取决于该服务的可用性，大规模抓取需考虑速率限制。
5. OpenCode skill 发现机制：OpenCode 从 ~/.opencode/skills/ 递归搜索 SKILL.md，目录结构必须是 ~/.opencode/skills/<name>/SKILL.md，否则不会加载。
6. 安全边界：Skill 赋予 Agent 对 vault 内文件的读写权限，建议在有快照或 Git 版本控制的环境下使用，避免意外覆盖重要笔记。

与同类对比

kepano/obsidian-skills 的核心优势：开发者本人是 Obsidian 核心插件贡献者，格式规范权威；唯一同时覆盖 Markdown、Bases、Canvas 三大 Obsidian 专有格式的多合一 Skill 包；遵循标准化 Agent Skills 协议，Claude Code、Codex、OpenCode 通用。

一句话推荐结论

如果你用 Obsidian 管理知识，同时使用 Claude Code、Codex 或 OpenCode 等 AI 编程助手，安装 obsidian-skills 是让 AI 真正理解并安全操作你的 vault 最直接的方式——一次安装，覆盖 Obsidian 所有核心格式，零学习成本。

数据来源：GitHub README、Agent Skills 规范（agentskills.io/specification）、Obsidian 官方文档。Bases 格式截至 2026 年中仍为实验性功能，建议在 Obsidian 最新稳定版中确认支持情况后再做重度使用。