Agent 实践

obsidian-skills：Obsidian 工作流的 Agent 操作手册

4 分钟阅读项目研究开源AIObsidian
文章目录
  1. 「这是什么」一句话定性
  2. 「它怎么转」逻辑全景图
  3. 「怎么升级」三段位路线图
  4. 入门段（能用）
  5. 进阶段（用好）
  6. 高手段（用活）
  7. 「能用在哪」场景迁移
  8. 直接平移的场景
  9. 部署这个项目的好处和坑
  10. 一句话总结
  11. 资料核对（2026-10-13）
蓝色像素虾在 Obsidian 知识库方言卡片前工作
图 1：obsidian-skills 的价值，是让 Agent 按 Obsidian 的方言改笔记。

仓库：github.com/kepano/obsidian-skills 作者：Steph Ango（网名 kepano） 许可：MIT，复用时保留相应声明 本质：遵循 Agent Skills 规范、面向 Obsidian 的技能集合；不是 Anthropic 对这个仓库的“官方参考实现”认证

「这是什么」一句话定性

它是 kepano 写给 AI Agent 的“操作手册”：让兼容 Agent 按 Obsidian 的格式处理 [[双链]]、![[嵌入]] 和 > [!note] callout，降低误改风险，而不是保证绝不破坏。旧稿讨论五张配方卡，当前 README 已增加 knap，列出六个技能。官方 README

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

「它怎么转」逻辑全景图

笔记语法数据视图画布桌面命令网页正文和模板笔记的职责图
图 2：按任务选用技能，说明书和实际执行工具分开理解。
├─ 触发层：什么时候需要它？
│   ├─ 你用 Claude Code / Codex / OpenCode 让 AI 改 Obsidian 笔记
│   ├─ AI 编辑后打开发现：双链断、callout 消失、frontmatter 错乱、canvas 节点错位
│   └─ 想批量把网页内容扒进 Obsidian（保留 markdown 结构）
│
├─ 核心层：当前 6 张“专家配方卡片”（原图展示的是旧版 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
│   │   └─ 负责 .base 语法说明，不是另写了一个数据库执行引擎
│   │
│   ├─ json-canvas ── JSON Canvas 思维导图（.canvas）
│   │   ├─ 节点（nodes）：text / file / link / group
│   │   ├─ 边（edges）：节点之间的连接关系
│   │   └─ 分组（groups）：视觉上的区域划分
│   │
│   ├─ obsidian-cli ── 通过命令行操作 Obsidian
│   │   ├─ 插件开发（创建/调试/打包）
│   │   ├─ 主题开发
│   │   └─ 批量任务（移动/重命名/导出）
│   │
│   ├─ defuddle ── 把网页扒成干净 Markdown
│   │   ├─ 去掉导航、广告、弹窗
│   │   ├─ 保留正文结构（标题、列表、代码块）
│   │   └─ 通过去杂减少正文外的内容，没有通用节省百分比
│   └─ knap ── 用 JSON/CSV 数据渲染 Markdown 模板，可批量生成笔记
│
├─ 输出层：怎么判断做对了？
│   ├─ Obsidian 打开笔记无报错、无黄底警告
│   ├─ 双链能正常跳转、嵌入能正常显示
│   ├─ callout 渲染成彩色块（不是普通引用）
│   └─ canvas 在 Canvas 视图里能正常布局
│
└─ 卡点层：新手最容易翻车的 3 个地方
    ├─ ❌ 复制目录路径错了：OpenCode 必须 clone 整个 repo 到 ~/.opencode/skills/obsidian-skills/，而不是只复制里面的 skills/ 子目录
    ├─ 加载方式因 Agent 而异：按当前运行时确认技能已发现，仓库明确提示 OpenCode 安装后重启
    └─ 把 skill 当引擎：Bases、CLI、Defuddle、Knap 各有自身版本和依赖，不能由一份提示词保证功能可用

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

入门段（能用）

做一件事：选一个常用 Agent，按仓库 README 安装所需技能，再在副本 vault 上验证格式保持。跨运行时可参考 README 的 npx skills add https://github.com/kepano/obsidian-skills，本次并未执行安装。

  • 手动安装要让每个技能的 SKILL.md 落在运行时实际扫描的目录，别把 skills/skills/ 多套一层
  • README 的 Claude Code 方法是把仓库内容放进 vault 根目录的 .claude/，其中已经包含 skills/；不是再把整个仓库塞到 .claude/skills/ 下
  • README 的 Codex 方法是把 skills/ 内各技能放入其技能路径；路径和发现机制以所用版本为准
  • README 的 OpenCode 方法是 clone 整仓到 ~/.opencode/skills/obsidian-skills/，保留内部 skills/<name>/SKILL.md

验证方式：检查当前运行时的技能清单及实际读取的 SKILL.md；六个名称是 obsidian-markdown、obsidian-bases、json-canvas、obsidian-cli、defuddle、knap，并非都以 obsidian 开头。再用小样本检查双链、callout、.base 和 .canvas，而不是只听 Agent 自报“装好了”。

进阶段（用好）

补两个认知： 1. Skill = 说明书，Agent 和工具 = 引擎：SKILL.md 约定任务、格式和步骤；遵循同一格式方便复用，但不保证所有运行时自动兼容所有工具。 2. 技能按任务组合，不是每次都全跑：普通笔记用 obsidian-markdown，Canvas 才需要 json-canvas；网页归档可串 Defuddle 和 Knap。改一篇 Markdown 不需要强制重载 Obsidian。

CLI 有硬前提：obsidian-cli/SKILL.md 调用的是正在运行的 Obsidian 应用，不是纯 headless 文件服务。官方 CLI 文档 要求相应安装器版本（当前说明 1.12.7+）、在设置里启用并注册命令。Defuddle 要安装独立 CLI，抓网页需要联网；Knap 要 Node.js 20+，负责模板渲染。

高手段（用活）

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

真正有积累的是把自己的规则写清楚，并给它配验收样本。每个 skill 一个目录 + SKILL.md 是起点，效果还要靠反复验证，不承诺一小时学会。

「能用在哪」场景迁移

直接平移的场景

场景 1：把这种"协议 + 配方卡"模式移植到 Notion / Logseq 可以借鉴目录结构，为你实际使用的 Notion API 或 Logseq 工作流写规则，分别处理 schema、引用和命名空间。这里不判断它们是否已有官方 Skill；可迁移的是让 AI 按工具的“方言”办事，不是把 Obsidian 命令原样复制过去。

场景 2：把 defuddle（网页→干净 Markdown）单独拿出来用 Defuddle 本身是独立的 HTML 正文提取工具，skill 调的是它的 CLI。可以用在有权获取的资料归档；登录、动态页面、来源许可和正文完整性需要另查。Defuddle 技能原文

例如： - 公众号爬虫：抓竞品文章，剥掉广告和导航 - 学术资料归档：把 arXiv 摘要转成纯 markdown 入库 - 新闻聚合：每天自动抓 10 个行业站点，去重入 Obsidian

部署这个项目的好处和坑

笔记在副本中修改并核对语法和应用显示
图 3：先改副本，再核对语法、链接和实际显示。

好处： - ✅ 规则文件可本地读取：无需给规则包单独配置 Key；Agent 模型、网页抓取、CLI 安装与同步各有联网和费用条件 - ✅ 跨平台：Claude Code、Codex、OpenCode 都能用，未来还会有更多 agent 支持 - ✅ 贴近格式：由 kepano 维护，链接了 Obsidian 官方语法资料；作者身份不等于维护承诺或不会弃坑

风险： - ⚠️ Bases 要按版本验收：官方已有过滤、公式与视图语法，不能用无原始测试记录的二手“实测不可用”给整个 skill 定性。先拿自己的 .base 样本检查结果 - ⚠️ Skill 加载顺序敏感：如果同时装了多个社区 Skill，可能有冲突。建议每个 Skill 先单独跑一遍验证 - ⚠️ 版本绑定与数据保护：skill 可能滞后于应用语法；批量改 vault 前保留备份/版本历史，审核 diff。网页和笔记是待处理内容，不是可执行指令

一句话总结

obsidian-skills 的灵魂是“格式先行，配方跟上”：把知识管理工具的方言写成 Agent 能读取的说明书。这个思路值得借鉴，但星标增长不能证明范式有效，更代替不了自己的笔记验收。

资料核对（2026-10-13）

本次读取官方仓库 README、MIT LICENSE、CLI/Defuddle/Knap 技能文件及 Obsidian CLI、Bases 官方文档，更新为六技能并删除无来源的实测与维护保证。未安装技能、运行 Obsidian 或测量 token 节省率。

记录到这里，判断留给实践。