obsidian-vault

obsidian-vault skill 概览

obsidian-vault skill 能做什么

obsidian-vault skill 用于让 agent 在一个特定的 Obsidian 知识库中工作：搜索笔记、创建新笔记、用 [[wikilinks]] 建立链接，并通过索引笔记而不是文件夹来组织内容。它是一个面向 Knowledge Capture 的细分实用 skill，不是通用型的笔记框架。

谁适合使用 obsidian-vault

如果你已经在 Obsidian 里沉淀知识，并希望 agent 遵循你现有 vault 的约定，而不是自己发明一套结构，那么这个 skill 很适合你。它尤其适合以下需求：

• 在创建重复笔记前先查找已有内容
• 按 vault 现有命名风格添加新笔记
• 创建或扩展索引笔记
• 通过 wikilinks 和 backlinks 发现相关笔记

真正要解决的问题

大多数用户并不只是笼统地需要“用于笔记的 AI”。他们真正需要的是：一个能在真实 vault 里安全操作、且不破坏本地约定的 agent。obsidian-vault 的核心价值在于，它给了 agent 一套明确可执行的工作流：

• 先按文件名或内容搜索
• 笔记名称保持 Title Case
• 优先使用扁平化 vault 结构
• 用链接和索引笔记组织内容，而不是靠文件夹

这个 obsidian-vault skill 的差异点在哪里

它最大的区别在于足够具体。这个仓库并不试图覆盖所有 Obsidian 工作流，而是为某一个 vault 编码了一套轻量级操作模型：

• 一个已知的 vault 路径
• 根目录层级的扁平化组织方式
• 以 [[wikilinks]] 作为主要连接机制
• 用索引笔记作为聚合节点

这让它比泛泛的“帮我记笔记”提示词更可执行，但代价是：如果你的 vault 组织方式差异很大，它的可迁移性就没那么强。

最适合与不适合的使用场景

最适合：

• 你希望 agent 搜索、创建并连接 Markdown 笔记
• 你的 Obsidian 已经大量使用链接
• 你偏好简单约定，而不是依赖大量插件自动化

不太适合：

• 你的 vault 严重依赖多层文件夹结构
• 你需要插件专属的元数据工作流、Dataview 查询或模板体系
• 你想要的是通用 Obsidian 指南，而不是某个 vault 的具体工作模式

如何使用 obsidian-vault skill

obsidian-vault 的安装上下文

如果你使用 Skills system，常见安装方式是：

npx skills add mattpocock/skills --skill obsidian-vault

安装后，先看 obsidian-vault/SKILL.md。在这个仓库里，这个文件就是唯一的事实来源；没有额外规则、脚本或参考文件来补充边界情况。

使用 obsidian-vault 前先读这个文件

先从这里开始：

• SKILL.md

这个 skill 很精简，所以你能很快理解它的实际行为。最关键的信息包括：

• vault 位置
• 命名约定
• wikilink 的使用方式
• 搜索命令
• backlink 和索引笔记的发现模式

先了解它内置的 vault 假设

当前的 obsidian-vault skill 默认假设：

• vault 路径：/mnt/d/Obsidian Vault/AI Research/
• 笔记大多平铺在根目录
• 笔记名称使用 Title Case
• 通过链接和索引笔记组织内容，而不是文件夹

如果你的环境不同，请在提示词里明确说明。否则，agent 可能会去错误路径搜索，或者按错误结构创建笔记。

使用 obsidian-vault skill 需要提供哪些输入

想把 obsidian-vault 用好，建议提供：

• 你的真实 vault 路径（如果与默认值不同）
• 任务类型：搜索、创建、整理，或查找相关笔记
• 主题或关键词
• 你希望看文件名匹配、内容匹配、backlinks 还是索引笔记
• 你关心的任何笔记命名约束

弱输入：

• "Help with my Obsidian notes"

强输入：

• "Use obsidian-vault to search my vault at /Users/me/Obsidian/Research for notes about retrieval augmentation, then suggest whether to update an existing note or create a new Title Case note with wikilinks."

把模糊目标改写成更好的提示词

一个好的 obsidian-vault guide 提示词通常包含：

1. vault 路径
2. 搜索意图
3. 你想要的输出
4. 你期望的链接行为

示例：

• "Use obsidian-vault for Knowledge Capture. Search by filename and content for prompt caching in /Users/me/Obsidian/AI Vault. If relevant notes exist, list them and suggest backlinks to add. If not, draft a new Title Case note and a short index-note entry."

这比直接让它“写一篇关于 prompt caching 的笔记”要好得多，因为它能降低重复建笔记的风险，也更能让 skill 按 vault 的工作流执行。

最重要的搜索工作流

仓库里展示了两种主要搜索模式。

按文件名搜索：

find "/mnt/d/Obsidian Vault/AI Research/" -name "*.md" | grep -i "keyword"

按内容搜索：

grep -rl "keyword" "/mnt/d/Obsidian Vault/AI Research/" --include="*.md"

如果你预期会有一个明确的笔记标题，优先用文件名搜索。若某个概念可能只是出现在更大的笔记内部，就用内容搜索。

如何在不污染 vault 的情况下创建笔记

用 obsidian-vault 创建笔记时，尽量遵循仓库里的简单规则：

• 文件名使用 Title Case
• 内容应聚焦为一个单一的学习单元
• 相关笔记放在底部，以 [[wikilinks]] 形式列出
• 如果主题属于编号序列的一部分，就使用层级编号

一个实用的创建提示词：

• "Create a new Title Case note called Context Engineering.md only if no close match exists. Keep it focused on one concept and add related [[wikilinks]] at the bottom."

如何查找相关笔记和 backlinks

这个 skill 支持通过搜索某个笔记的 wikilinks 来做 backlink 风格的发现：

grep -rl "\\[\\[Note Title\\]\\]" "/mnt/d/Obsidian Vault/AI Research/"

这点很重要，因为在扁平化 vault 里，链接承担了大量组织职责。如果你让 agent“查找相关笔记”，最好明确你要的是：

• 在内容里提到该主题的笔记
• 直接链接到某个特定笔记的笔记
• 可能聚合该主题的索引笔记

索引笔记在工作流中的位置

这里的索引笔记并不是那种元数据很重的 dashboard，而是简单的聚合型笔记，通常由一组 [[wikilinks]] 列表组成。仓库中的示例名称包括：

• RAG Index.md
• Skills Index.md

如果你希望 agent 帮你整理某个主题，让它更新或建议一个索引笔记，通常比让它凭空发明文件夹结构更安全。

查找方式：

find "/mnt/d/Obsidian Vault/AI Research/" -name "*Index*"

新用户建议的第一套 obsidian-vault 工作流

一个合理的首次 obsidian-vault usage 模式是：

1. 先按文件名搜索该概念
2. 如果文件名搜索结果太少，再按内容搜索
3. 查看相关的 wikilinks/backlinks
4. 决定是扩展已有笔记，还是创建新笔记
5. 如果该主题属于某个合集，就更新对应索引笔记

这套顺序可以减少重复笔记，也能保持 vault 结构一致。

提升输出质量的实用细节

提示词中的一些小细节，会明显影响结果：

• 明确写出 vault 的准确路径
• 告诉 agent 是否禁止创建文件夹
• 要求它创建前先搜索
• 如果你已知道目标笔记，就直接点名
• 如果你想和 skill 保持一致，就要求在笔记底部添加相关链接

例如：

• "Do not create folders. Search first. If creating a note, use Title Case and add related wikilinks at the bottom."

obsidian-vault skill 常见问题

obsidian-vault 比普通提示词更好吗？

对于 vault 内操作来说，通常是的。普通提示词可能能写出一篇漂亮的笔记，但未必遵守你的 vault 规则。obsidian-vault skill 更适合需要 agent 扮演“谨慎的 vault 维护者”时使用：先搜索、遵循命名规范、链接笔记，并用索引笔记替代文件夹蔓延。

obsidian-vault 对新手友好吗？

友好，前提是你的需求比较基础：找笔记、建笔记、连笔记。这个 skill 很小，也容易理解。但它默认你能接受 Markdown 文件和基于路径的搜索方式，而不只是停留在 Obsidian UI 里点点点。

obsidian-vault 需要 Obsidian 插件吗？

从仓库证据来看，没有描述任何插件依赖。这个工作流基于纯 Markdown 和 Obsidian 标准 wikilinks。

我可以把 obsidian-vault 用在自己的 vault 路径上吗？

可以，但如果你的 vault 不在默认位置，你应该在提示词里覆盖那个硬编码路径。仓库只记录了一个具体路径，所以它是否能顺利用在别处，取决于你有没有明确提供正确的本地路径。

什么情况下不该使用 obsidian-vault？

如果你的 vault 依赖以下结构，建议不要用它：

• 复杂的文件夹分类体系
• 重度 frontmatter 工作流
• 插件专属 schema
• skill 中没有提到的自动模板机制

在这些情况下，比起单独执行 obsidian-vault install，更适合使用更专业的 skill，或者写一套你自己的自定义指令。

obsidian-vault 只适合 Knowledge Capture 吗？

Knowledge Capture 确实是它最合适的场景，因为这个 skill 强调的是收集、链接和索引知识点。至于日常 journaling、任务管理，或重度依赖插件的 PKM 系统，它就没有那么明确地适配。

如何改进 obsidian-vault skill

每次使用 obsidian-vault 时，都先加上“先搜索再操作”的指令

最常见的失败模式，就是创建出重复笔记。想提高结果质量，告诉 agent：

• 先按文件名搜索
• 再按内容搜索
• 只有在没有接近匹配时才创建新笔记

这一条通常比要求“写得更好”更能改善 obsidian-vault usage 的效果。

给 agent 更明确的笔记目标

如果你已经大致知道内容应落到哪里，就直接说清楚：

• 精确的笔记标题
• 要更新的索引笔记
• 要链接的相关笔记
• 这是新笔记还是已有笔记

更好的说法：

• "Update RAG Index.md with a wikilink if the new note belongs there."

更差的说法：

• "Organize this somewhere in my vault."

明确保留 vault 的扁平结构

很多人会本能地用文件夹做组织，agent 也可能如此，除非你把约束说清楚。如果你的环境与这个 skill 一致，请加上：

• "Do not create folders"
• "Use links and index notes for organization"

这样能让输出更贴近仓库原本的意图。

要求输出分两步进行

为了让修改更安全，可以要求：

1. 先给出搜索结果和建议
2. 再给出拟议的笔记内容或修改方案

示例：

• "First show matching notes and whether you recommend update vs create. Then draft the note."

这样会让 obsidian-vault 在真实 vault 维护场景中更可靠，因为你可以在落笔前先拦住重复内容。

用链接导向的提示词提升笔记质量

如果你希望新笔记更好地融入 vault，不要只让它写正文。你还可以要求：

• 3 到 5 个候选 [[wikilinks]]
• 可能的 backlink 目标
• 索引笔记建议
• 笔记底部“相关链接”部分的精确内容

这样产出的笔记会更像网络中的一个节点，而不是孤立的 Markdown 文件。

在第一稿之后继续迭代

拿到初稿后，可以通过第二轮提示继续提升结果，比如：

• "Tighten the note to one unit of learning."
• "Replace generic related links with notes that actually exist in the vault."
• "Add an index-note entry."
• "Check whether the title should be more specific to avoid collision."

这些后续指令很重要，因为这个 skill 提供的是结构化工作流，不是自动质量控制。

如果你要长期使用 obsidian-vault，就把本地约定补充文档化

如果你打算频繁依赖这个 skill，投入产出比最高的改进方式，就是在上游模式之外补充你自己的本地规则：

• 真实 vault 路径
• 命名例外
• 偏好的索引笔记名称
• 是否使用编号体系
• 如何处理未完成笔记

这样才能把 obsidian-vault 从“有用的通用模式”，真正变成“适合你自己 vault 的可靠工作 skill”。