用 AI Agent 操控 Obsidian 知识库：obsidian-skills 项目深度笔记
核心观点
obsidian-skills是 Obsidian CEOkepano亲自维护的开源项目，本质是一套「让 AI Agent 读懂并操控 Obsidian 的协议包」。它并不是新造一个 AI 工具，而是把 Obsidian 原生的五种数据格式/操作接口封装成符合Agent Skills 规范（agentskills.io）的标准技能包，从而让 Claude Code、Codex、OpenCode 等主流 AI Agent 无需定制适配就能直接操作 Obsidian Vault。
这件事处于一个关键节点：Agent 编程范式已经成熟到「技能标准化」阶段——MCP 解决了工具连接问题，而 Agent Skills 规范则进一步解决了「指令层」标准化问题。obsidian-skills 是后者的早期重要实践，不是渐进优化，是范式完成度的一个新台阶。
技术机制：SKILL.md 是关键
整个项目的最核心设计来自Agent Skills 规范定义的SKILL.md格式。每个技能是一个目录，核心文件结构如下：
skill-name/ ├── SKILL.md # 必须有：YAML frontmatter（元数据）+ Markdown（指令正文） ├── scripts/ # 可选：可执行脚本 ├── references/ # 可选：参考文档 └── assets/ # 可选：模板资源SKILL.md文件头部是 YAML frontmatter，示例：
--- name: obsidian-markdown description: Create and edit Obsidian Flavored Markdown with wikilinks, embeds, callouts. license: MIT compatibility: Requires Node.js for CLI features allowed-tools: Bash(git:*) Read Write --- # 正文：Agent 的操作指令（Markdown 自由格式）最巧妙的机制是「渐进式加载」（Progressive Disclosure）：
- Agent 启动时只加载所有技能的
name + description（约 100 tokens），用于技能发现 - 被激活的技能才完整加载
SKILL.md正文（建议 < 5000 tokens） - 脚本和资源按需加载
这个设计直接攻克了 AI Agent 最核心的瓶颈：context window 的浪费。相比早期「把所有说明塞进系统提示词」的粗暴方式，这里借鉴了软件按需加载的思路，是真正工程化的设计。
五项技能详解
| 技能名 | 格式 | 作用 |
|---|---|---|
obsidian-markdown | .md | Obsidian 方言 Markdown，含 wikilinks、callouts、properties |
obsidian-bases | .base | Obsidian Bases 数据库视图，含过滤器、公式、汇总 |
json-canvas | .canvas | JSON Canvas 可视化画布，含节点、边、分组 |
obsidian-cli | CLI | 直接调用 Obsidian CLI，支持插件/主题开发 |
defuddle | 网页 →.md | 从网页提取干净 Markdown，去噪节省 token |
五个技能的组合价值远大于单独使用。例如一个完整的知识入库工作流：用defuddle抓取网页 → 用obsidian-markdown写入 Vault → 用obsidian-bases构建知识索引 → 用json-canvas生成可视化关系图。这是 Agent 的乐高积木式编排，是单技能无法实现的。
安装方式
推荐方式（NPX）：
npx skills add https://github.com/kepano/obsidian-skillsClaude Code 手动安装：
将仓库内容放入 Obsidian Vault 根目录的/.claude文件夹。
OpenCode 手动安装（注意：必须 clone 完整仓库，不能只复制skills/子目录）：
git clone https://github.com/kepano/obsidian-skills.git ~/.opencode/skills/obsidian-skills交叉验证
信源一：agentskills.io 官方规范文档
与原文完全一致，且补充了更多细节：SKILL.md的 frontmatter 中name字段有严格命名规则（小写字母数字 + 连字符，不能有大写、前导/连续连字符），还提供了skills-ref validate校验工具。官方文档明确说这套规范面向 Claude Code、Codex CLI 和 Gemini CLI，原文只提到前两个——Gemini CLI 的支持是原文未提到的有效补充。
信源二：Text Matrix 的中文深度评测（txtmix.com，2026年4月）
该文认同 obsidian-skills 的核心价值，并指出了两个原文未明确说明的局限：
- 并发冲突：当多个 Agent 同时操作同一 Vault 时，会产生文件竞争，项目目前无文件锁机制，需人工串行操作；
- 移动端不可用：
obsidian-cli和defuddle依赖 Node.js，iOS/Android 端无法运行，移动端只能使用三个格式类技能（markdown/bases/canvas）。
这两点局限在官方 README 中均未直接说明，是重要的补充信息。
边界与局限（不该被过度夸大的部分）
- 不是低代码/无代码：用户仍需在终端手动执行安装命令，需要理解 Agent 工作流概念，门槛不低
- Agent Skills 规范还很新：目前整个 agentskills.io 生态处于早期，周边工具（Marketplace、目录站等）2026 年才开始出现，成熟度有限
- 单一维护者风险：kepano 一人维护，PR 积压（36个 open），迭代速度受限
- 与 MCP 的关系未厘清：obsidian-skills 是「指令层」，MCP 是「工具连接层」，两者并不互斥，但用户容易混淆「到底该用哪个」
- defuddle 技能的实际效果依赖目标网页结构，对反爬站点、动态渲染页面效果有限
个人启发
对重度 Obsidian 用户（知识工作者）：这个项目最直接的价值是把 Obsidian 从「手工维护」工具变成「可编程知识库」。以前你需要亲自整理 wikilinks、维护 Bases 视图；现在你可以用自然语言告诉 Claude Code「帮我把最近两周的读书笔记整理成一张 Canvas 知识图」，Agent 会自动调用多个技能完成。
对开发者：Agent Skills 规范本身值得研究。它的「元数据轻量 + 指令渐进加载 + 工具白名单」三件套，是构建任何领域技能包的通用模板。如果你在维护 MCP Server 或者 CLI 工具，考虑同步提供一个SKILL.md是成本极低但覆盖面大的做法。
具体行动建议：
- 如果你用 Claude Code + Obsidian，立刻安装，成本几乎为零（
npx skills add一行命令），收益是 Agent 能理解 Obsidian 方言而不是把[[wikilink]]当普通文本处理 - 如果你使用移动端 Obsidian 为主，暂时不必优先投入，等待移动端支持
- 不要同时开多个 Agent 会话操作同一 Vault，养成「单 Agent 串行」习惯，避免文件冲突
延伸思考
Agent Skills 规范 vs MCP 是否会走向融合？两者分别解决「指令层」和「工具连接层」，理论上互补，但生态碎片化风险很高——若 Anthropic 和 OpenAI 各自主推不同标准，这类「跨 Agent 通用技能包」项目会面临分裂压力。
「知识库可编程化」会改变笔记方法论吗？当 Agent 能批量生成 wikilinks、自动维护 Bases 视图，「笔记整理」这件事的人工部分将大幅压缩。GTD、PARA、Zettelkasten 这些方法论是否会演变为「提示词模板」？
defuddle 技能的更大意义：把「网页去噪 → 结构化 Markdown」标准化为一个可复用技能，实质上是在解决 RAG 的输入质量问题。如果这个模式推广，未来知识库的「摄入管道」可能会形成一套标准化的 Agent Skills 链，而不是每个人写各自的爬虫脚本。
📚 参考来源
- GitHub - kepano/obsidian-skills: Agent skills for Obsidian. Teach your agent to use Obsidian CLI and open formats including Markdown, Bases, JSON Canvas. · GitHub
安装Vulhub靶场)
