Obsidian Notes Skill

Obsidian Notes

这个 skill 用于把对话或项目/主题上下文整理成长期可用的 Obsidian 笔记。笔记应当在数周后仍然可搜索、可阅读、可复用，并且能够和知识库中已有笔记形成清晰关系。

对于工作项目资料，笔记不是“来源指针”或“摘要卡片”。整理后的正文必须足够完整，让读者不需要重新打开原始文件，也能理解主要内容、关键机制、案例样本、数据口径和可复制启示。

核心流程

1. 识别笔记主题：项目、资料、议题、决策、工作流、配置、问题、复盘或可复用方法。
2. 判断笔记类型：
   • agent-workflow：Agent 行为、MCP/CLI/tool 设置、可重复工作流。
   • project-note：项目资料、项目背景、业务内容、阶段性沉淀。
   • technical-note：配置、命令、排障、架构、技术流程。
   • decision-record：已选择方向、被排除选项、依据和影响。
   • reference-note：长期参考知识、案例、方法或复用框架。
3. 当笔记属于业务/项目归档时，使用 references/note-types.md 判断领域模板，尤其是社群和会员运营、营销策划、商业运营、品牌活动、线上产品开发、案例研究和 MOC/索引类笔记。
4. 当输入来自微信文章、URL、PDF、DOCX、EXCEL、PPTX、本地文件、会议记录或已有 Obsidian 笔记时，使用 references/source-types.md 判断来源处理规则。
5. 选择存放目录。Agent 工作流和工具设置默认放入 00-Agent(工作流沉淀）/；业务资料、案例、报告、活动复盘和来源归档类笔记优先放入 06-Archives(重要档案）/，除非用户指定其他位置。
6. 使用 references/note-template.md 起草笔记。
7. 写入前应用 references/style-guide.md 的样式和质量要求。
8. 写入前检索同目录、同主题或同项目已有笔记，补齐 related_notes 和 ## 文件引用。不要写 待关联 这类占位内容。
9. 写入前执行质量检查。
10. 如果可用 Obsidian MCP 或 Local REST API，优先写入并读回验证标题、Properties、Key takeaway、摘要、后续可复用关键信息、Key references 和 文件引用 是否存在。若不可用，则提供 Markdown 供手动写入。

必需笔记结构

每篇笔记必须包含：

• YAML Properties：包含创建信息、更新时间、来源、项目/主题、知识类型、状态、可信度、相关项目、相关笔记和 tags。不要使用 links 属性；URL、本地路径和外部证据统一放入 Key references。
• 一个具体的 H1 标题。
• ## Key takeaway：Obsidian callout，包含一句最值得复用的结论，以及一小段解释为什么重要、何时适用、复用时不能忘记什么。
• ## 摘要：Obsidian callout，固定三条短 bullet，便于快速浏览。
• ## Context：Obsidian callout，简要说明背景、目标、当前状态、适用范围；如果用户提供了微信或其他平台 URL，必须在这里保留原始 URL。
• 主体内容块：
  • 工作项目归档笔记优先使用 ## 原始内容完整整理、## 机制 / 模式、## 案例 / 对比、## 可复制启示。
  • 技术/工具/流程类笔记可使用更适合的结构，例如 Key points、Workflow / Method、配置表或验证清单。
• ## 后续可复用关键信息：
  • 工作项目归档笔记：只放复用口径、模板沉淀、数据口径、机制抽象、适用条件和注意事项。
  • Agent/技术笔记：可放路径、命令、端点、配置键、验证方式和已知坑点。
  • 不要在这里重复原始文件路径、URL 或页码；这些统一放入 Key references。
• ## Key references：唯一外部来源区，放用户提供 URL、原始文件路径、官方文档、API endpoint、页码/章节/发布时间等证据来源。临时抽取文本、HTML 抓取件、工作区副本只作为消化过程材料；笔记完成后默认不保留引用，除非它本身是长期可复核来源。
• ## 文件引用：只放 Obsidian 内部 wiki 链接，表达与已有笔记的主要知识关系。

默认不要在工作项目归档笔记中加入 ## Next actions。只有当笔记本身是行动计划、任务追踪，或用户明确要求后续行动时才加入。

默认不要在 ## 文件引用 中加入 后续可延展。如果整理过程中发现值得拆成新专题的内容，应在最终回复中列为“建议拆分整理项”，等待用户确认后再创建新笔记。

写作规则

• 优先使用具体事实、路径、文件名、指标、机制、角色、决策和结论，避免泛泛总结。
• 保留关键本地路径、端口、工具名、文件名和用户提供链接。
• 表格优先用于数据、机制、对比、角色分工、配置矩阵、复用模板和检查清单。
• Mermaid 只在能明显压缩流程或关系时使用。
• 不写入密钥、API key、cookie、token、auth code 或 bearer 值，除非用户明确要求写入该敏感信息。
• 读写 Markdown 使用 UTF-8；Windows PowerShell 中读取含中文标题的文件时使用 -Encoding UTF8。
• 保持 Key references 和 文件引用 的边界：
  • 外部证据、URL、本地路径、页码、端点属于 Key references。
  • Obsidian 内部笔记关系属于 文件引用。
• 网页 URL 在 Context 和 Key references 中优先写成可点击 Markdown 链接，链接文字优先使用内容标题、页面标题、文档标题、仓库名或平台入口名，例如 [我们一起奔赴热爱](https://...)。只有无法确定标题时才使用 [微信原文](https://...) 或 [来源链接](https://...)。不要用反引号包裹网页 URL；Windows 本地路径、API endpoint、命令和文件名仍使用反引号。
• tags 只放稳定主题分类。不要把 note_type、年份、状态、带特殊符号的品牌写法放入 tags；例如不要写 project-note、2022、樾+、樾⁺、社群+。正文和标题可以保留正式品牌名，标签应转成稳定写法，例如 樾生活方式。
• 对微信文章、URL、PDF、DOCX、EXCEL、PPTX，要在 Key references 中保留来源身份、访问/保存时间、页码/章节/工作表/幻灯片等可追溯信息。
• 对 06-Archives 中的业务/项目归档笔记，不要写轻量指针笔记。必须提取并保留原始资料的主要内容：叙事主线、事实、数据、机制、案例、对比、决策和可复用启示。页码/slide 只是证据，不能替代正文。
• 写入已有笔记时，先读取现有内容，再尽量做定向修改。只有创建新笔记或经用户同意替换生成稿时，才进行整篇替换。
• 删除、移动、大范围替换等破坏性操作需要用户明确确认。

质量检查

写入或更新前，确认：

• YAML 包含 created_at、updated_at、source、project、topic、note_type、knowledge_type、status、confidence、related_projects、related_notes 和 tags。
• tags 不包含纯数字、note_type 值、状态值或特殊符号标签；年份应放标题、topic 或正文，类型应放 note_type。
• 写入业务/项目归档笔记前已检索现有知识库关系；related_notes 中的笔记必须在 文件引用 中解释，且不要保留 待关联 占位。
• Key takeaway 只有一句可复用结论和一段高密度解释，不凑字数。
• 摘要 恰好三条 bullet，且不重复 Key takeaway 段落。
• Context 简洁说明背景、目标、状态和适用范围；用户提供的 URL 在这里可见。
• 用户提供的网页 URL 在 Context 和 Key references 中使用 Markdown 链接格式，确保可点击跳转。
• 工作项目归档笔记正文足够完整，读者无需重新打开原始文件即可理解核心内容。
• 后续可复用关键信息 不重复来源路径或 URL，只保留复用口径、模板沉淀、数据口径、机制抽象、适用条件等内容。
• Key references 只包含外部证据、用户 URL、本地文件路径、repo 路径、API endpoint、页码或章节。
• 文件引用 只包含有意义的 Obsidian 内部 wiki 链接，并说明关系；默认不写 后续可延展。
• 没有写入密钥、API key、cookie、token、auth code 或 bearer 值，除非用户明确要求。

Obsidian 写入建议

如果 MCP 工具可用，优先顺序（这是日常笔记操作的推荐路径；插件开发调试场景在 Obsidian CLI 可用时改用 CLI）：

1. vault_write：创建新笔记。
2. vault_read：读回验证写入结果。
3. vault_get_document_map：修改已有笔记前获取结构。
4. vault_patch：定向修改标题、frontmatter 或指定 heading。
5. vault_append：仅在明确需要追加且不会重复时使用。

手动使用 Obsidian Local REST API with MCP 时：

• Streamable HTTP MCP endpoint 使用 https://127.0.0.1:27124/mcp/。
• JSON 请求使用无 BOM 的 UTF-8。
• Header 包含 Authorization: Bearer 、Content-Type: application/json、Accept: application/json, text/event-stream。
• 初始化后保留 Mcp-Session-Id，后续请求继续使用。

与其它 Skill 的协作

本 skill 是 Obsidian 知识库笔记的结构权威。加载本 skill 时，其它 Obsidian 相关 skill 只能作为语法、文件格式或调试能力补充，不能覆盖本 skill 对笔记结构、Properties、内容完整性和引用边界的要求。

obsidian-markdown：Obsidian 语法手册

使用场景：需要写 embeds、注释 %%、LaTeX 数学、Mermaid 图表、脚注、block links 等 Obsidian 特有 Markdown 语法。

分工边界：

• 本 skill 定义笔记应该包含什么结构、哪些 Properties 字段、哪些 callout 样式、哪些内容质量要求。
• obsidian-markdown 只定义具体 Obsidian Markdown 语法怎么写。
• Properties 字段以本 skill 为准；默认不要因为 obsidian-markdown 的通用示例而新增 title、date 等字段。
• aliases、cssclasses 只有在用户明确要求、已有 vault 规范需要，或 Obsidian 视图确实依赖时才补充。
• Callout 规范以本 skill 为准；obsidian-markdown 的 callout 类型列表仅作语法参考。

obsidian-bases：.base 视图

使用场景：创建或编辑 .base 文件，构建笔记的表格、卡片或列表视图。

分工边界：

• 本 skill 不定义 .base 文件格式；遇到 .base 文件创建或编辑时委托给 obsidian-bases。
• 本 skill 定义的 Properties 字段，例如 note_type、project、topic、status、confidence、tags，可作为 .base 的过滤、分组和排序字段。
• .base 视图不得反向改变本 skill 的 YAML 字段规范。

json-canvas：.canvas 图谱

使用场景：创建或编辑 .canvas 文件，构建知识图谱、思维导图、流程图或项目关系图。

分工边界：

• 本 skill 不定义 .canvas 文件格式；遇到 Canvas 文件创建或编辑时委托给 json-canvas。
• Canvas 的 file node 可以指向本 skill 生成的笔记。
• 本 skill 负责保证被引用笔记的命名、结构和内部关系清晰；json-canvas 负责 Canvas JSON 结构正确。

obsidian-cli：命令行与插件调试

使用场景：仅在 Obsidian CLI 可用，且任务涉及 MCP 不具备的能力时使用，例如插件热重载、截图验证、错误捕获、DOM/console 检查或版本对比。

日常 vault 读写、搜索和补丁仍优先使用 MCP。

参考文件

• 起草笔记前阅读 references/note-template.md。
• 判断样式、内容密度和可读性时阅读 references/style-guide.md。
• 判断业务领域模板时阅读 references/note-types.md。
• 判断来源处理规则时阅读 references/source-types.md。