obsidian

Obsidian Vault 管理器

资源

此技能采用模块化资源架构。详细工作流、模板和辅助工具位于 assets/ 目录中：

• assets/modes/ - 2 种操作模式及其详细工作流
• assets/helpers/ - 用于 frontmatter、交叉引用、排序和批量操作的通用辅助工具

目录索引请参阅 assets/README.md。

元数据说明：此文件的 YAML frontmatter 定义运行时行为（auto_invoke 触发条件、allowed-tools、scope）。manifest.json 定义注册表元数据（version、tags、providers、dependencies）。Claude Code 技能加载器会读取 frontmatter；skills CLI 会读取 manifest，以进行安装和更新。

---

用途

用于所有 Obsidian 知识库操作的统一技能。它在 Agent 工作区与 Obsidian 知识库之间充当双向知识桥梁（优先使用 MCP，不可用时则回退到文件系统）：

• SYNC 模式：将工作区中的文档写入知识库（Markdown 报告、计划、分析）
• READ 模式：读取、搜索知识库笔记，并将其作为上下文知识来源进行推理

此技能整合了原有 obsidian-sync 和 obsidian-reader 技能的功能，通过渐进式披露构建为一个统一工具。

---

语言支持（i18n）

此技能支持双语操作（英语 + 西班牙语）：

• 触发关键词：检测模式时会识别英语（sync、read、search）和西班牙语（guardar、lee、busca）关键词。
• ## Referencias 章节标题：有意采用西班牙语形式，这是本项目沿用的 Obsidian 惯例。此技能生成的所有文档均使用 ## Referencias（而非 ## References）。
• 查询示例：文档包含两种语言的示例，以体现实际的双语使用情况。
• 输出语言：技能会以用户所用的语言作答。用户使用西班牙语提问时，请用西班牙语作答；使用英语提问时，请用英语作答。文档内容绝不翻译——同步或读取时均保持原样。

惯例：## Referencias 是固定章节标题。生成文档时，绝不要将其翻译为 ## References。

---

关键规则

规则 1 — 模式检测：根据用户意图自动选择

根据用户输入检测操作模式。切勿强制选择与场景不符的模式。

规则 2 — 保持内容完整性（SYNC 模式）

写入前完整读取源文件。绝不要修改文档正文内容（标题、段落、表格、代码块、## Referencias 章节）。只添加或合并 frontmatter 元数据。交叉引用修复只能更新 related frontmatter 数组，绝不修改文档正文。

规则 3 — 绝不编造内容（READ 模式）

只报告笔记中逐字存在的信息。引用来源时注明路径。区分“笔记写道 X”和“我根据笔记推断 X”。

规则 4 — 遵循 Obsidian Markdown 标准

所有操作均遵循 Obsidian markdown standard 规范，其中定义了 frontmatter、wiki-links、类型和交叉引用的标准。

---

工具依赖

此技能仅使用 Claude Code 原生工具：Read、Write、Edit、Glob、Grep、Bash、AskUserQuestion。无需 MCP 或外部依赖。

---

操作模式

模式检测

根据用户意图，利用以下信号自动检测模式：

模式	信号（EN）	信号（ES）	输入示例
SYNC	“sync”“save”“store”“write”“move” + “obsidian”	“guardar”“sincronizar” + “obsidian”	“sync this report to obsidian”“guardar en obsidian”
READ	“read”“search”“find”“check”“consult”“what do my notes say” + “obsidian”/“vault”/“notes”	“lee”“busca”“consulta” + “obsidian”/“vault”/“notas”	“read my vault notes about X”“busca en obsidian”

意图模糊时的处理： 如果用户意图与 SYNC 或 READ 信号不明确匹配（例如，“help me with obsidian”“manage my notes”或只说“obsidian”而没有动词），请询问用户以明确意图：

AskUserQuestion:
  question: "What would you like to do with your Obsidian vault?"
  header: "Mode"
  options:
    - label: "Read / Search"
      description: "Read notes, search for information, or get project context from your vault"
    - label: "Sync / Write"
      description: "Save or sync documents from your workspace to your vault"

模式能力矩阵

能力	SYNC 模式	READ 模式
写入库	✅	❌
从库读取	❌	✅
搜索库	❌	✅
生成 frontmatter	✅	❌
修复交叉引用（frontmatter）	✅	❌
诊断交叉引用	✅	✅
批量操作	✅	✅
浏览库	✅	✅
优先级排序	❌	✅
标准合规性检查	❌	✅
删除/归档笔记	✅	❌
移动/重新整理笔记	✅	❌
修补笔记（部分编辑）	✅	❌
仅读取元数据	❌	✅

---

资产加载（按模式控制）

检测模式后，只读取该模式列出的资产。不要读取其他模式的资产——它们会浪费上下文令牌。

模式	读取这些资产	不要读取
SYNC	assets/modes/SYNC.md	READ.md、priority-ranking.md、obsidian-linter.md
READ	assets/modes/READ.md	SYNC.md、frontmatter-generator.md、cross-ref-validator.md、batch-sync-pattern.md

每个模式资产都会在内部引用所需的辅助文件和标准。按照模式工作流的指示按需读取，而不是预先读取。

MCP 工具参数约定（两种模式都需要）请参见 assets/helpers/tool-reference.md——仅在 ToolSearch 输出不足时读取。

---

快速开始

SYNC 模式

用于将工作区中的文档保存到 Obsidian 库：

将此报告同步到 obsidian。

现在要读取的资产： assets/modes/SYNC.md（按需引用 frontmatter-generator、cross-ref-validator、batch-sync-pattern）

READ 模式

用于读取、搜索和分析库中的笔记：

读取我的库中关于架构的笔记。

现在要读取的资产： assets/modes/READ.md（按需引用 priority-ranking、obsidian-linter）

---

模式工作流

SYNC 模式 - 写入 Obsidian 库

将 Markdown 文档从工作区同步到 Obsidian 库，并正确处理 frontmatter 和交叉引用验证。

现在要读取的资产： assets/modes/SYNC.md（按需引用 frontmatter-generator、cross-ref-validator、batch-sync-pattern）

快速摘要：

1. 识别源文件（使用 Glob 搜索工作区文档）
2. 检测访问模式（MCP 或文件系统回退）
3. 浏览库并询问用户目标位置
4. 读取源文件
5. 生成 frontmatter（→ SYNC.md 引用 frontmatter-generator）
6. 使用 mcp__obsidian__write_note 写入库
7. 验证交叉引用（→ SYNC.md 引用 cross-ref-validator）
8. 报告结果

READ 模式 - 从 Obsidian 知识库读取

读取、搜索并分析知识库笔记，为决策提供上下文知识。

现在要读取的资料： assets/modes/READ.md（引用优先级排序、按需使用 obsidian-linter）

快速摘要：

1. 加载 MCP 工具（如果 MCP 不可用，则回退到文件系统）
2. 解析用户意图（读取笔记、搜索、获取项目上下文、回答问题）
3. 执行操作（搜索／读取／分析）
4. 按优先级排序结果（→ READ.md 引用 priority-ranking）
5. 提供包含来源引用的结构化输出

---

配置解析

{vault_destination} 在运行时解析——SYNC 模式会浏览知识库，并询问用户要将内容保存到何处。无需预先配置或持久化设置。请参阅 SYNC.md 步骤 3。

支持暂存目录：当用户说“将我的输出同步到知识库”时，SYNC 模式会检测来自生产技能（universal-planner、code-analyzer）的 .agents/ 目录，列出可用输出，让用户选择，然后将其同步到指定的知识库位置。

---

共享辅助工具

• frontmatter-generator - 按照通用架构生成 Obsidian frontmatter
• cross-ref-validator - 验证双向引用
• batch-sync-pattern - 优化的批量文件同步工作流
• priority-ranking - 按相关性对搜索结果排序

---

Obsidian 输出标准

所有操作均遵循内部 Obsidian Markdown 标准：

1. Frontmatter：通用架构包含 title、date、project、type、status、version、tags、changelog、related
2. 类型分类：14 种文档类型（analysis、plan、sprint-plan、technical-report 等）
3. Wiki 链接：使用 [[note-name]] 格式，绝不使用 Markdown 链接
4. 双向引用：如果 A→B，则 B→A
5. 状态转换：draft → active → completed → archived

如需合规性验证，请参阅 assets/validators/obsidian-linter.md。

---

与其他技能集成

生产技能	obsidian 的集成方式
universal-planner	SYNC：将规划文档保存到知识库。READ：提供历史计划作为上下文
code-analyzer	SYNC：保存技术报告。READ：呈现架构笔记
universal-planner（EXECUTE 模式）	READ：检索冲刺计划和进度

组合模式：

Producer skill generates docs → obsidian SYNC mode writes to vault
Agent needs context → obsidian READ mode retrieves from vault

跨技能调用

当其他技能或 Agent 需要调用 obsidian 时，请按以下优先级顺序操作：

优先级 1：Skill 工具（推荐）

如果在加载了技能的 Claude Code 中运行：

Skill("obsidian")

然后描述要执行的操作（例如，“将 .agents/staging/code-analyzer/ 中的文件同步到知识库”）。

优先级 2：自然语言触发

说出与 auto_invoke 匹配的短语：

• “将输出同步到 obsidian”
• “将这些报告保存到知识库”
• “Guardar en obsidian”

优先级 3：直接读取 SKILL.md（没有技能上下文的子 Agent）

如果 Skill 工具不可用（例如，通过 Task 工具运行的团队子 Agent），请直接读取 SKILL.md：

Read: cognitives/skills/integrations/obsidian/SKILL.md

然后按照 SYNC 或 READ 模式的工作流操作。未先读取此技能时，绝不要调用 mcp__obsidian__* 工具。

---

最佳实践

SYNC 模式：

• 同步前确认源文件存在
• 始终询问用户要保存到何处（绝不假定目标位置）
• 批量同步后验证交叉引用
• 报告文件保存到的确切知识库路径

READ 模式：

• 优先尝试 MCP；如果不可用，则回退到文件系统
• 将搜索范围限定在相关文件夹（不要无必要地搜索整个知识库）
• 始终引用来源的确切笔记路径
• 区分引述内容与解读

---

限制

• 仅支持 Markdown：处理 .md 文件，不处理二进制资源/图片
• 单个知识库：一次只操作一个知识库
• 不支持双向同步：写入知识库（SYNC）或从知识库读取（READ），不支持双向同步
• READ 模式下只读：在 READ 模式下无法修改笔记（写入请使用 SYNC）
• 搜索使用正则表达式/字面匹配：使用 Grep，不支持模糊搜索。如果结果较少，请扩大匹配范围。

---

故障排除

问题	模式	解决方案
"Tool not found: mcp__obsidian__*"	两者	先运行 ToolSearch query: "+obsidian write"
"MCP server not connected"	两者	技能会自动回退到文件系统模式。出现提示时，请提供知识库路径。
"Note already exists"	SYNC	覆盖前请先向用户确认
"No results found"	READ	扩大搜索范围，检查其他文件夹，并确认知识库路径
"Empty content"	SYNC	使用 Glob 验证源文件路径
"Confirmation path mismatch"	SYNC	delete_note 要求 confirmPath 与 path 完全一致
"Multiple matches found"	SYNC	有多处匹配时，patch_note 使用 replaceAll: false 会失败；请设置 replaceAll: true 或细化字符串
"Frontmatter merge conflict"	SYNC	update_frontmatter 使用 merge: true 会保留现有内容；使用 merge: false 可完全替换
元数据查询缓慢	READ	使用 get_frontmatter 或 get_notes_info，而不是读取完整笔记