Obsidian CEO 做了 5 个 Markdown 文件，重新定义了 AI 与工具之间的关系

——kepano/obsidian-skills 深度解析：一个被低估的生态转折点

不是 AI 变聪明了，是工具开始主动配合

你大概遇到过这个场景：

打开 Claude，让它帮你整理一篇 Obsidian 笔记。它生成了内容，格式看起来差不多——但仔细一看，[[wikilinks]] 写成了普通超链接，callout 语法完全不对，frontmatter 缺字段，标签格式乱七八糟。

你花了 10 分钟手动修正。

下次又是一样。

这不是 AI 不够聪明。Claude 处理复杂推理、代码生成、多语言写作的能力，早就远超大多数人的需求。

问题出在别的地方：AI 学的是"标准 Markdown"，但 Obsidian 说的是自己的"方言"。

这个格式鸿沟一直存在。它不是 Bug，而是一个从未被正式命名、也从未被系统性解决的结构性问题。

直到 2026 年 1 月，Obsidian CEO Steph Ango（GitHub ID：kepano）把 5 个 Markdown 文件推送到了 GitHub。

Obsidian CEO Steph Ango（kepano）做了一件"quintessentially Obsidian"的事：没有在产品里塞一个"问 AI"按钮，而是发布了一个开源仓库，教 AI 如何正确地使用 Obsidian。

这个仓库叫 kepano/obsidian-skills。

目前，它在 GitHub 上已积累超过 21,400 颗星，Fork 数突破 1,300。

但星数不是重点。重点是这件事背后的逻辑——它代表了一种范式的转变，而不只是一个新工具。

第一章：kepano 是谁，他为什么亲自动手

要理解这个项目的意义，必须先理解做这件事的人。

他叫 Steph，你也许认识他的另一个名字：kepano，目前是 Obsidian 的 CEO。

Steph Ango 是一位设计师、作家、创业者和工具制造者。他的教育背景横跨生物学和工业设计，是一位真正的跨界创作者，涉足软件、硬件、供应链、文字、木工、家具、色彩方案和开源系统等多个领域。最重要的是，他制造工具——带有强烈主张的工具——设计目的是减少自己和他人在创造过程中的摩擦。

Steph 从一位热情用户转型为 Obsidian CEO，他加入公司的过程本身就说明了一切：先是以用户身份深度参与、贡献反馈和想法，最终打动了创始人 Shida Li 和 Erica Xu。2023 年 2 月正式加入后，他将优先用户所有权而非数据提取的设计哲学融入产品的每一个决策。

他的个人网站用 Obsidian 写作和编辑，并坚守一个核心哲学：File over app（文件优于应用）。他的纯文本 Obsidian 文件通过 Jekyll 自动编译成网页。

这不是一句口号，这是他真实的工作方式。

所以当 AI Agent 的浪潮到来，大多数工具厂商的选择是：把 AI 塞进产品，做一个光鲜的"AI 问答"按钮，然后告诉用户这是"革命性功能"。

kepano 的选择截然不同。

他的发布最令人欣喜之处在于：这不是"把 AI 硬植入产品"。这是一套清晰解释 Obsidian 文件语法的技能包。Obsidian 继续坚守开放格式（Markdown、.base、JSON Canvas），AI 只是另一个可选工具，负责读写这些格式。

你选择自己的平台。你选择自己的模型。

这句话，是整个项目最核心的设计哲学。

第二章：Agent Skills 规范——一个被低估的生态基础设施

在拆解这 5 个文件之前，有一个概念必须先讲清楚：Agent Skills 规范是什么，它和你已经知道的其他东西有什么本质区别？

很多人会把 Agent Skills 和 AGENTS.md、.cursorrules 混为一谈。这是一个需要在开始就澄清的误解。

三者的本质区别

Obsidian Skills 并不与 AGENTS.md 或 .cursorrules 竞争——它们服务于不同的目的。AGENTS.md 给 Agent 提供通用的项目指令。Obsidian Skills 则教 Agent 特定工具的文件格式。

你应该同时使用两者。

用一张表格说清楚三者的关系：

三者不是替代关系，而是不同层级的配合。

Agent Skills 规范的技术本质

Agent Skills 规范定义了一种标准格式：一个 Skill 是包含至少一个 SKILL.md 文件的目录。SKILL.md 文件必须包含 YAML frontmatter，后跟 Markdown 内容。

Agent Skills 是结构化的文档文件，为 AI Agent 提供领域特定的知识和能力。与传统 API 文档不同，Skills 用自然语言配合示例和规范来书写，Agent 可以直接将其解读并应用到推理循环中。每个 Skill 定义在一个 SKILL.md 文件中。Agent Skills 规范确保任何兼容的 Agent 都能自动发现、加载和使用这些 Skills，无需自定义集成代码。

这一点很关键：Skills 不是专有格式，它是开放规范。

这些 Skills 遵循 Agent Skills 规范，可被任何兼容 Skills 的 Agent 使用，包括 Claude Code 和 Codex CLI。

还有一个细节值得注意：

SKILL.md frontmatter 中的 name 和 description 字段至关重要。Agent 仅根据 description 来决定是否加载某个 Skill。描述模糊，Skill 就永远不会被激活。要写明这个 Skill 适用和不适用的场景。

这意味着：安装 Skill 只是第一步，Skill 的描述质量直接决定了它能不能在正确的时机被触发。

第三章：5 个 SKILL.md 的完整拆解

仓库包含 5 个技能目录：defuddle、json-canvas、obsidian-bases、obsidian-cli、obsidian-markdown。

让我们逐一拆开，不只是讲"它能做什么"，更重要的是讲清楚它为什么需要存在、设计意图是什么、真实的边界在哪里。

Skill ① obsidian-markdown——方言教材的核心卷

它解决什么问题：

AI 默认输出的是标准 CommonMark 或 GitHub Flavored Markdown（GFM）。但 Obsidian 在此基础上添加了大量专有扩展。

Claude Code 默认不了解 Obsidian 的专有文件格式。当它创建笔记时，可能破坏 wikilink 语法；当它编辑 .base 文件时，会生成无效的 JSON；当它写 .canvas 文件时，输出的内容在 Obsidian 中根本无法打开。

它教 AI 什么：

obsidian-markdown 技能用于创建和编辑带有 wikilinks、嵌入、callouts、属性和其他 Obsidian 特有语法的 Obsidian Flavored Markdown；在处理 Vault 中的 .md 文件，或用户提到 wikilinks、callouts、frontmatter、标签、嵌入时激活。

Obsidian 在 CommonMark 和 GFM 基础上扩展了 wikilinks、嵌入、callouts、属性、注释等语法。这个技能只覆盖 Obsidian 特有扩展——标准 Markdown 语法视为已知前提。

这个设计决策非常克制：只教差异，不重复已知。

这既节省了 Token，也避免了 AI 在读取技能时被大量冗余信息分散注意力。

最重要的一条规则：

wikilinks 和 Markdown 链接的选择原则：Vault 内部的笔记用 [[wikilinks]]（Obsidian 会自动跟踪重命名），外部 URL 才用标准 Markdown 链接格式。

这一条规则，是 AI 生成 Obsidian 内容时最常出错的地方。一旦混用，链接图谱就会碎掉。

一个真实对比：

没有这个 Skill 时，AI 生成的笔记大概是这样：

Markdown

---
title: Claude Code 学习笔记
---
# Claude Code 学习笔记
参考了 [Obsidian Skills](https://github.com/kepano/obsidian-skills) 项目。
本笔记与 [个人工作流](workflow.md) 有关联。
> **注意**：安装前请先阅读文档。

安装 Skill 之后，AI 生成的笔记应该是这样：

Markdown

---
title: Claude Code 学习笔记
tags:
  - ai/agent
  - obsidian/skills
date: 2026-04-08
---
# Claude Code 学习笔记
参考了 [Obsidian Skills](https://github.com/kepano/obsidian-skills) 项目。
本笔记与 [[个人工作流]] 有关联。
> [!warning] 安装前注意
> 请先阅读完整文档，确认路径配置正确。

差异清晰：frontmatter 完整、wikilinks 正确、callout 格式符合规范。这些都是小细节，但累积起来，决定了你的 Vault 是否真的能被 Obsidian 的图谱系统正确识别。

Skill ② obsidian-bases——数据库层的格式说明书

它解决什么问题：

Bases 是经典的 Obsidian 风格：「看起来像数据库，但本质上还是文件」。一个 .base 文件定义视图、筛选器、公式、汇总等，让你在 Obsidian 中以表格或卡片的形式浏览笔记。如果没有严格的格式规范，AI 倾向于弄错字段名称、嵌套或结构。这个 Skill 就是把 AI 限定在正确的轨道上。

它教 AI 什么：

obsidian-bases 技能让 Agent 能够管理 .base 文件——这些文件定义了 Obsidian Vault 中动态的、类数据库的视图，利用筛选器、公式和汇总来聚合笔记数据。

一个真实边界（必须说清楚）：

Bases 有一个前置依赖：你的笔记必须有规范的 frontmatter。如果你的 Vault 里大量笔记没有 type、date 等属性字段，Bases 的过滤器就无法正确工作。

这意味着：使用 obsidian-bases Skill 之前，先用 obsidian-markdown Skill 让 AI 补全 frontmatter，是更合理的顺序。

Skill ③ json-canvas——可视化画布的格式说明书

它解决什么问题：

Canvas 背后是开放的 JSON Canvas 格式（Obsidian 甚至发布了规范文档）。一个 .canvas 文件是带有固定 Schema 的 JSON，包含节点、连接和分组。

没有这个 Skill 时，AI 会生成结构上看似正确的 JSON，但 Schema 字段有遗漏，导致文件在 Obsidian 中无法正常渲染——这是一种"打开就报错"的静默失败。

它教 AI 什么：

json-canvas Skill 针对 JSON Canvas 规范，使 Agent 能够以编程方式创建和修改由节点和边组成的可视化思维导图和流程图。

一个具体的使用示例：

对 Agent 说「创建一个 Canvas，解释 MCP 协议的核心概念和组件关系」——Agent 激活 json-canvas Skill，理解节点、边和分组的正确 JSON Schema，生成一个可直接在 Obsidian 中打开的 .canvas 文件。整个过程不需要你手动写一行 JSON。

Skill ④ obsidian-cli——命令行操控 Vault 的指令集

它解决什么问题：

在这 5 个 Skill 里，CLI Skill 是门槛最高、但潜力也最大的一个。它让 AI 可以不打开 Obsidian GUI，直接通过命令行与 Vault 交互。

通过 Obsidian CLI，Agent 可以读取、创建、搜索和管理笔记、任务、属性等。同时还支持插件和主题开发，包含重新加载插件、运行 JavaScript、捕获错误、截图和检查 DOM 等命令。

当用户要求与 Obsidian Vault 交互、管理笔记、搜索 Vault 内容、从命令行执行 Vault 操作，或开发和调试 Obsidian 插件和主题时，激活此 Skill。

真实的命令示例：

核心命令包括：obsidian read file="My Note"、obsidian create name="New Note" content="# Hello"、obsidian append file="My Note" content="New line"、obsidian search query="search term" limit=10、obsidian daily:append content="- [ ] New task"、obsidian backlinks file="My Note" 等。

一个重要的前提条件：

使用 Obsidian CLI 需要通过 CLI 与一个正在运行的 Obsidian 实例交互。Obsidian 必须处于打开状态。

这一点常被忽视：CLI Skill 不是完全后台运行的，它需要 Obsidian 应用本身处于运行状态。这影响了它在某些自动化场景下的适用性。

Skill ⑤ defuddle——输入管道的净化器

它解决什么问题：

Defuddle 负责在保存网页内容前将其剥离为干净的 Markdown，去除广告、导航栏和页面外壳，这显著降低了 Token 消耗。

原始网页内容噪音极大。没有预处理就直接处理，一次研究任务就能让你的上下文窗口被导航栏和页脚撑爆，广告内容也会大量堆积。

推荐使用顺序：

处理网页内容时，先运行 /defuddle 对页面进行清洗，再进行保存。在四个 Skill 中，/defuddle 是使用频率最高的一个。

这个 Skill 的价值在流程上：它是输入管道的第一道过滤，质量越高的输入，后续处理的效果越稳定。

第四章：安装路径的真实选择指南

这是大多数教程一笔带过的部分，但它直接决定你能不能顺利用起来。

三种路径，适合三种场景——选错了，轻则 Skill 不生效，重则需要重新配置整个环境。

路径一：Claude Code 用户（最推荐）

将本仓库内容添加到 Obsidian Vault 根目录的 /.claude 文件夹中，或你正在与 Claude Code 配合使用的任何文件夹。

具体操作：

Bash

git clone https://github.com/kepano/obsidian-skills.git
cp -r obsidian-skills/.claude /path/to/your/vault/

为什么推荐放在 Vault 内部，而不是全局目录？

放在 Vault 内的 .claude/skills/ 文件夹有一个隐藏优势：你可以用 Obsidian Sync 把 Skills 同步到所有设备，不需要在每台机器上重复配置。

一个关键细节：

克隆仓库并复制 .claude 目录后，这些 Skills 不会自动加载。在处理特定文件类型之前，需要手动运行对应的斜杠命令来激活。

激活方式：在 Claude Code 中运行 /obsidian-markdown、/obsidian-bases 或 /json-canvas。这会将格式规则加载到当前会话的上下文中。

这是一个非常重要的认知：Skills 是按需激活的，不是始终在后台运行的。

路径二：Codex CLI 用户

将 skills/ 目录复制到 Codex 的 skills 路径（通常是 ~/.codex/skills）。

路径三：OpenCode 用户（有一个常见错误）

将整个仓库克隆到 OpenCode 的 skills 目录：git clone https://github.com/kepano/obsidian-skills.git ~/.opencode/skills/obsidian-skills

这里有一个经常导致失败的操作：

不要只复制内层的 skills/ 文件夹——必须克隆完整仓库，确保目录结构是 ~/.opencode/skills/obsidian-skills/skills/<skill-name>/SKILL.md。OpenCode 会自动发现 ~/.opencode/skills/ 下的所有 SKILL.md 文件，无需修改任何配置文件。重启 OpenCode 后，Skills 自动生效。

安装路径选择总结

text

你用哪个 Agent？
├── Claude Code → 克隆仓库，复制 .claude/ 到 Vault 根目录
│                  （推荐放 Vault 内，方便多设备同步）
├── Codex CLI  → 复制 skills/ 目录到 ~/.codex/skills
└── OpenCode   → 克隆完整仓库到 ~/.opencode/skills/obsidian-skills
                  （注意：不能只复制内层文件夹）

第五章：社区正在用它做什么——真实画像，不夸大，不缩小

Reddit 上标题为「kepano 发布了 obsidian-skills 仓库——你在用它构建什么自定义技能？」的帖子引发了大量讨论。开发者们分享了自定义实现、初次设置流程，以及将 Vault 打造成 AI 管理的学习系统、客户数据库和项目追踪器的工作流。社区的共识是：AI Agent 终于「真正理解」了 Vault——frontmatter、Bases、Canvas 布局、Obsidian Flavored Markdown，全都能正确处理，不再出错。

有用户报告他们的 Vault 现在「以 CRM、Sprint 追踪器和知识图谱的形式运行，作为一个完整的商业操作系统」，由 Claude Code 处理「潜在客户研究、数据管道、邮件起草——完整的端到端自动化」。

这些报告是真实的，但需要一个清醒的补充：

社区共识里有一个值得警惕的叙事过度：

很多人在描述这套系统时，会说 AI「记住了你」、「学习了你的习惯」——但这是一个误导性的表述。

这些 Skills 是 Markdown 驱动的规范，教 Claude Code 等 Agent 如何在 Obsidian 独特环境中执行感知上下文的任务。

Skills 的本质是格式规范文档，不是记忆系统。Agent 加载 Skill 就像人类学会了读一份说明书，而不是建立了个人关系。这个区别很重要——它决定了你对这套系统的期望应该定在哪里。

真正的「记忆」需要另外建立：通过在 Vault 里写入结构化的 Session 日志，让 Agent 每次启动时读取。这是一个主动设计的机制，不是 Skills 自动提供的能力。

第六章：这件事真正的意义

表面上，这是一个 GitHub 仓库，5 个 Markdown 文件，解决了 AI 写错 Obsidian 格式的问题。

但如果只看到这一层，就低估了它的真实意义。

信号一：垂直领域 Skills 时代的开始

工具厂商开始拥抱 Agent Skills 规范，为自己的产品创建官方技能包。这不只是一个技能仓库——它标志着 Agent Skills 生态从通用技能向深度垂直领域整合的演进。Obsidian Skills 成为第一个由主流工具官方维护的 Agent Skills 实现。

随着更多工具厂商效仿，垂直领域技能将成为 AI Agent 与专业工具深度集成的标准模式，最终实现用自然语言操控复杂工具的愿景。

当 Figma、Notion、Linear 的官方 Skills 陆续出现——而这几乎是必然的——你的 AI Agent 将真正学会在任何主流工具里「说对语言」，而不是每次都需要你手动纠错。

信号二：Obsidian 哲学的延续，而不是妥协

kepano 的做法最值得关注的地方在于：他没有「把 AI 硬植入产品」。这是一套清晰解释 Obsidian 文件语法的技能包。Obsidian 继续坚守开放格式（Markdown、.base、JSON Canvas），AI 只是另一个可选工具，负责读写这些格式。

这与大多数厂商的做法形成了鲜明对比——他们通常选择做一个专有的 AI 接口，让用户通过他们的系统访问 AI，从而锁定数据和工作流。

kepano 的选择是相反的：教 AI 说自己的语言，而不是让用户迁移到自己的 AI 里。

这与 kepano 一直坚守的核心理念一脉相承：「File over app」——数据应该以独立于工具的格式存在。这不只是一个产品决策，更是对软件长期可用性的一种承诺。

信号三：「会说工具语言」将成为竞争优势

一项覆盖 124 个 PR 的对照研究显示，AGENTS.md 将运行时间缩短了 28.6%，Token 使用减少了 16.6%。

同样的逻辑适用于 Skill：给 AI 提供正确的上下文格式，直接影响输出质量和执行效率。

未来，一个人维护的 Vault 和 Skills 的质量，将直接决定他从 AI Agent 那里获得的价值量级。这不是夸张的说法，这是格式化知识的复利效应。

第七章：行动建议——分三层，对应三种准备度

不是所有人都应该今天就开始做所有事情。根据你现在的准备状态，选择对应的层级。

🟢 今天可以做（15 分钟）

目标：验证这件事对你是否有价值

1. 打开终端，克隆仓库：
   Bash

   git clone https://github.com/kepano/obsidian-skills.git
   

2. 根据你使用的 Agent，选择正确的安装路径（参考第四章）
3. 打开 Claude Code，激活 /obsidian-markdown Skill
4. 让 AI 帮你生成一篇笔记，对比「安装前」和「安装后」的格式差异

这一步的目的不是建立完整系统，而是亲眼看到那个格式鸿沟被填补——这会让你理解为什么这件事重要。

🟡 本周可以做（2 小时）

目标：找到最适合你的 Skill 组合

1. 根据你的主要使用场景，从 5 个 Skill 中选择 2-3 个安装
2. 用真实任务测试每个 Skill：
• obsidian-markdown：生成 10 篇格式正确的笔记
• obsidian-bases：为你的阅读列表或项目创建一个 Base 视图
• json-canvas：让 AI 可视化一个你正在思考的概念关系图
3. 记录：哪个 Skill 让你感到「对，这就是我需要的」

🔵 本月可以做（持续迭代）

目标：写出第一个属于你自己的流程类 Skill

这是整个系统最有价值的一步，也是大多数人不会做的一步。

官方的 5 个 Skill 是「工具类 Skill」——它们教 AI 说正确的格式语言。但还有另一类 Skill 更有价值：流程类 Skill——教 AI 遵循你个人独特的工作流程。

比如：你每次写读书笔记的固定结构；你处理 Inbox 的分类规则；你给笔记打标签的具体逻辑。

这些流程，只有你自己能写，因为它们是你 Vault 的基因。

一个简单的起点：

完成一次真实任务 → 记录你给 AI 的指令和所有修正 → 把「每次都要重复说的话」提炼进一个 SKILL.md → 下次直接调用

这个 Skill 不需要很长，哪怕只有 20 行，只要它精准捕捉了你的 Vault 特有的约定，它的价值就超过所有通用 Skill 的总和。

结语：插件是家具，Skills 是木工

kepano 的这 5 个文件，解决的是一个你可能没有意识到自己有的问题：AI 一直在用错误的格式写你的笔记，而你一直在默默地手动修正。

这些 Markdown 驱动的规范，教 AI 如何在 Obsidian 的独特环境中执行感知上下文的任务。通过提供 Obsidian 用户常见的模式、约定和工作流的正式描述，它们赋能 AI 工具给出更相关的建议、生成符合用户规范的内容，或执行尊重知识图谱和文件关系的复杂多步骤操作。

但有一件事需要说清楚：

kepano 提供的是起点，不是终点。

官方 Skills 解决了「格式语言」的问题——这是每个 Obsidian + AI 用户的共同障碍。但你的 Vault 的独特性，来自你自己的命名规范、文件夹结构、标签体系、笔记模板、思维习惯。

这些东西，没有任何官方 Skill 能替你定义。

Obsidian 插件像是你搬进房间里的家具——有人帮你选好款式、提供安装说明，你按步骤放进去就行。

Agent Skills 更像是你学会了木工——你从 kepano 的范例出发，理解了格式规范的逻辑，然后开始打造只属于你自己大脑的东西。

最有价值的那个 Skill，永远是你自己写的那一个。

下一篇预告：

现在你知道了「为什么要安装 Skills」和「怎么安装」。但 5 个官方 Skill 里，哪些是你必须装的，哪些对你的使用场景来说是过度设计？还有一个更关键的问题：「工具类 Skill」和「流程类 Skill」的本质区别是什么，为什么后者必须由你自己写？

→ 文章二：官方 5 个 Skill 文件全拆解：哪些是你必须安装的，哪些是你根本不需要的

松花酿酒，春水煎茶。

眉上风止，见字如晤。

一只阿木木