obsidianObsidian vault 专属操作：wikilink/双链、backlink、canvas、daily note、frontmatter 属性等 Obsidian 特有能力。注意：普通的知识库读写（存/搜/读/改笔记）统一走内置 knowledge_* 工具——当用户把知识库后端配成 Obsidian 时，knowledge_* 会自动落到 vault，无需本技能。仅当用户点名 Obsidian、或要用 vault 特有功能（双链/canvas/日记/backlink 维护）时才加载本技能。
Independent GitHub snapshot · Automated classification · Original documentation governs
name: obsidian title: Obsidian Vault Manager description: "Obsidian vault 专属操作：wikilink/双链、backlink、canvas、daily note、frontmatter 属性等 Obsidian 特有能力。注意：普通的知识库读写（存/搜/读/改笔记）统一走内置 knowledge_* 工具——当用户把知识库后端配成 Obsidian 时，knowledge_* 会自动落到 vault，无需本技能。仅当用户点名 Obsidian、或要用 vault 特有功能（双链/canvas/日记/backlink 维护）时才加载本技能。" version: 1.1.0 author: NousResearch license: MIT platforms: [linux, macos, windows] trigger:
Use this skill for filesystem-first Obsidian vault work: reading notes, listing notes, searching note files, creating notes, appending content, adding wikilinks, managing tags, maintaining backlinks, and editing frontmatter.
所有写入 Obsidian 笔记的操作，必须通过 knowledge_add / knowledge_edit 完成。
file_write 直接写 markdown 文件shell 的 mkdir / cat / echo / python3 -c "open(...).write(...)"<vault>/<scene>/<slug>.md）knowledge_add(title, content, tags, scene, frontmatter)knowledge_edit(source, content, mode="append", scene)knowledge_edit(source, content, mode="replace", scene, frontmatter)判断标准：只要写入的内容是笔记/资料/纪要/PRD/设计文档等知识库条目（即使已经用 lark-cli / web_fetch 拉取了原文），写回时也必须走 knowledge_* 工具。
为什么：knowledge_* 工具会自动加 frontmatter（title/type/tags/created/updated，由 yaml.safe_dump 安全生成）、自动建子目录、自动建索引支持全文搜索；file_write 直写会绕过这一切，导致路径平铺根目录、frontmatter 字段缺失、搜索查不到。
凡是笔记内容派生自外部网页/飞书文档/链接（用户提供了 URL，或你用 lark-cli / web_fetch 拉取过原文），调用 knowledge_add / knowledge_edit 时必须传 frontmatter={"source": "{原始 URL}"}。
title / type / tags / created / updated）由后端自动管理，不要在 frontmatter 里重复传type 由 tags[0] 自动推断，无需手动指定author / published 等扩展字段| 内容类型 | scene | 示例 |
|---|---|---|
| 工作向记录 | work | PRD、设计文档、会议纪要、技术方案、工作沉淀 |
| 个人/生活向 | life | 个人学习、生活记录、家庭事项 |
| 不确定 | work | 默认 work，用户明确说生活类时切 life |
scene 决定子目录（<vault>/work/... vs <vault>/life/...），不传 scene 会平铺到 vault 根目录——这是禁止的。
Use a known or resolved vault path before calling file tools.
The documented vault-path convention is the OBSIDIAN_VAULT_PATH environment variable, for example from ${ETHAN_HOME:-~/.ethan}/.env. If it is unset, fall back to ~/Documents/obsidian/work, then ~/Documents/Obsidian Vault.
File tools do not expand shell variables. Do not pass paths containing $OBSIDIAN_VAULT_PATH to read_file, write_file, patch, or search_files; resolve the vault path first and pass a concrete absolute path. Vault paths may contain spaces, which is another reason to prefer file tools over shell commands.
If the vault path is unknown, terminal is acceptable for resolving OBSIDIAN_VAULT_PATH or checking whether the fallback path exists. Once the path is known, switch back to file tools.
Use read_file with the resolved absolute path to the note. Prefer this over cat because it provides line numbers and pagination.
Use search_files with target: "files" and the resolved vault path. Prefer this over find or ls.
pattern: "*.md" under the vault path.Use search_files for both filename and content searches. Prefer this over grep, find, or ls.
search_files with target: "files" and a filename pattern.search_files with target: "content", the content regex as pattern, and file_glob: "*.md" when you want to restrict matches to markdown notes.调用 knowledge_add 工具创建笔记。不要用 write_file / shell / file_write 直写文件——见上方硬规则 R1。
knowledge_add(
title="笔记标题",
content="Markdown 正文（不要带 frontmatter，后端自动生成）",
tags=["coze", "prd"], # 第一个 tag 自动成为 type（不要带 scene 前缀）
scene="work", # 必传，决定子目录
frontmatter={"source": "https://...原始 URL..."} # 来自外部链接时必传 R2
)
后端会自动：
title / created / updated / type / tags），用 yaml.safe_dump 安全序列化<vault>/<scene>/<slug>.md（slug 由标题小写化生成，重名追加 -1/-2）写入 Obsidian 的内容必须遵循以下原则：
scripts/fetch_doc.py 脚本获取完整 Markdown 内容，不要仅凭记忆或摘要转写。<blockquote> / <cite> / <colgroup> 等专有标签需在写入前清理为标准 Markdown（> / [[wikilink]] / 标准 table）。assets/ 目录，然后使用相对路径或 wikilink 引用，不要直接引用外部 URL。
<vault>/assets/<有意义的文件名>.png（按内容命名，避免随机串）![[assets/my-image.png]] 或 <!-- 图片未下载: <url> -->调用 knowledge_edit(source, content, mode="append", scene) 追加内容。source 是笔记的 slug 或绝对路径（之前 knowledge_add 的返回值）。
knowledge_edit(source, content, mode="append", scene)knowledge_edit(source, content, mode="replace", scene, frontmatter)read_file + write_file 拼接整篇内容shell 的 echo >> 追加mode="replace" 会保留原文件的 created 字段，只刷新 updated 为今天。
定向修改用 knowledge_edit(source, content, mode="replace", scene) 整篇替换。当前 knowledge_edit 不支持局部 patch，需要修改局部内容时：先 knowledge_read(source) 读全文 → 在内存里改 → knowledge_edit(source, modified_content, mode="replace", scene)。
Obsidian links notes with [[Note Name]] syntax. When creating notes, use these to link related content.
[[Note Name]] — link to a note[[Note Name|Display Text]] — custom display text[[Note Name#Heading]] — link to a heading inside a note[[Note Name#^block-id]] — link to a block reference![[Note Name]] — embed a full note![[image.png]] — embed an image attachment![[image.png|300]] — embed an image with a width hint正文链接规范：如果文档中提到了已有的其他笔记或项目，使用 [[双链]] 将它们关联起来（例如：关于 AB 灰度配置，可参考 [[AB 实验灰度方案]]）。原始链接（如飞书文档 URL）应写入 frontmatter 的 source 字段。
笔记的 frontmatter 由 knowledge_add / knowledge_edit 后端自动生成，不要在 content 里手写 frontmatter 块。后端用 yaml.safe_dump 安全序列化，避免引号/冒号/反斜杠导致的解析错误。
| 字段 | 来源 | 说明 |
|---|---|---|
title | knowledge_add(title=...) | 笔记标题，引号风格由 yaml.safe_dump 按内容自动决定 |
created | 后端 | 首次创建时设为今天；knowledge_edit(mode=replace) 时从原文件保留 |
updated | 后端 | 每次写入刷新为今天 |
type | tags[0] 自动推断 | 不要手动传，传了也会被忽略 |
tags | knowledge_add(tags=[...]) | 层级标签列表 |
| 字段 | 何时传 | 示例 |
|---|---|---|
source | 内容来自外部 URL 时必传（R2） | frontmatter={"source": "https://..."} |
author | 需要记录作者时 | frontmatter={"author": "张三"} |
published | 需要记录发布时间时 | frontmatter={"published": "2026-07-15"} |
层级格式：使用 分类/子分类 格式，支持多级嵌套，方便在 Obsidian 中折叠和检索。
常用标签体系（不要带 work//life/ 前缀，scene 参数已决定顶层目录）：
<项目名> — 项目归属（如 coze、lark）tech/<技术栈> — 技术研究（如 tech/electron、tech/mcp）prd — PRD / 设计案（type 自动推断为 prd）tech-design — 技术方案（type 自动推断为 tech-design）meeting — 会议纪要（type 自动推断为 meeting）reference — 参考资料（type 自动推断为 reference）todo — 个人待办<分类> — 生活类内容规则：
# 号；正文中的 inline 标签必须以 # 开头tag_manager.py list 查询已有标签，优先复用_、-、/；不以数字开头To update frontmatter on an existing note: 调用 knowledge_edit(source, content, mode="replace", scene, frontmatter={...}) 整篇替换，frontmatter 参数里只传扩展字段（如 source），固定字段（title / type / tags / created / updated）由后端管理。不要用 read_file + patch 改 frontmatter——这会绕过 yaml.safe_dump，可能产出非法 YAML。
Tags use the 一级/二级/三级 hierarchical format. Reuse existing tags whenever possible; do not invent new top-level tags impulsively.
python3 ~/.ethan/skills/obsidian/scripts/tag_manager.py list — scans frontmatter tags: fields and inline #tag occurrences across the vault.python3 ~/.ethan/skills/obsidian/scripts/tag_manager.py add "note_path.md" "project/active" — patches the note's frontmatter (creates one if missing). note_path may be absolute, or relative to the vault root.alpha/beta/gamma, supports unlimited nesting. No leading digits; allowed chars: letters, digits, _, -, /.#tag works anywhere in the body; frontmatter tags: is preferred for structured classification.Before creating a new tag, always run list first and reuse an existing one if a close match exists.
Backlinks are [[Note Name]] references pointing TO a note. Obsidian builds them automatically in-app; on the filesystem you maintain them by editing the source notes.
search_files with target: "content", pattern: "\\[\\[Note Name" and file_glob: "*.md" across the vault. The same prefix matches both [[Note Name]] and [[Note Name|...]].terminal (mv "old.md" "new.md"), or read+write+delete via file tools.[[Old Name]] and [[Old Name|...]] across the vault.[[New Name]] (preserve display text after |).If the user keeps a daily-notes folder (commonly Daily/, 日记/, or journals/), create today's note with write_file at the conventional path. Use YYYY-MM-DD.md naming unless the user has an existing convention. If unsure, list the vault root first to discover the folder.
.canvas files are JSON describing nodes (text/file/link/group) and edges on a 2D plane. See references/canvas.md for the spec. Edit with write_file producing valid JSON; do not hand-edit fragments. Coordinates: x increases right, y increases down; position is the top-left corner.
If obsidian-cli is installed (check with terminal running which obsidian-cli), it can automate some operations more safely than raw filesystem edits:
obsidian-cli print "note" — print note contentobsidian-cli search "keyword" — search note titlesobsidian-cli search-content "keyword" — search note contentobsidian-cli create "path/note.md" --content "..." — create noteobsidian-cli daily — open today's daily noteobsidian-cli frontmatter "note" --set "key:value" — write frontmatter fieldobsidian-cli move "old.md" "new.md" — rename note (auto-updates backlinks)obsidian-cli list — list vault filesPrefer the filesystem-first workflows above when obsidian-cli is unavailable. Use obsidian-cli move for renames when available, since it updates backlinks automatically.
references/markdown.md — Obsidian Flavored Markdown reference (wikilinks, embeds, callouts, frontmatter).references/canvas.md — JSON Canvas spec for .canvas files.