obsidian

Obsidian 集成

为将 Claude 工作流与 Obsidian 库集成提供专业指导，包括使用 Obsidian 基于 Markdown 的系统创建笔记、管理任务和组织知识。

何时使用此技能

• 在与 Claude 的开发会话期间创建笔记
• 在 Obsidian 中跟踪任务和待办事项
• 记录与 Claude 一起发现的决策和解决方案
• 构建项目见解知识库
• 整理 Claude 会话中的研究发现
• 创建会议笔记或会话摘要

支持文件

此技能分为多个文件。需要时加载相关文件：

• best-practices.md - MOC、属性、组织理念、dump 标签要求
• templates.md - 笔记模板：会话、技术、任务、分析规划、主题参考、待办事项、HOME.md
• organization-patterns.md - 主页 MOC、项目 MOC、待办事项整合、归档策略、跨项目链接
• vault-management.md - 库重组、会话整合、链接管理、项目目录设置、脑暴内容处理
• reference.md - Obsidian Markdown 语法、bash 辅助工具、插件、Claude 集成模式、故障排除
• cli-reference.md - Obsidian CLI（1.12+）命令参考，可替代许多 bash 用法
• changelog.md - 版本历史

核心原则

1. 优先使用 CLI - 尽可能使用 obsidian CLI 命令（1.12+），而不是 bash/cat 用法。参见 cli-reference.md
2. 库的位置 - 使用 $OBSIDIAN_VAULT 环境变量直接访问文件；CLI 使用 vault=<name> 选项
3. 始终询问用户将笔记放在哪里 - 未先询问用户，绝不自行决定笔记的保存位置。展示库结构，提供选项，并让用户选择。
4. 原子化笔记 - 每篇笔记聚焦于一个概念或主题
5. 链接 - 使用维基链接 [[note-name]] 连接相关想法
6. 标签 - 使用 #project/feature 之类的分层标签进行整理
7. 任务 - 使用复选框语法记录可执行事项
8. 时间戳 - 添加日期以提供时间背景

基本规则

规则 1：绝不擅自决定笔记位置

重要：在 Obsidian 中创建任何笔记时，始终询问用户希望将笔记保存在哪里。即使位置看起来显而易见，也绝不自行决定。

原因：用户了解自己的库是如何组织的。擅自决定位置意味着用户之后还得重新整理。

创建任何笔记的工作流：

1. 展示当前库结构，帮助用户做决定
2. 提供选项（根目录、特定文件夹、自定义路径）——不要自行决定
3. 在写入任何内容之前获取用户的选择
4. 在用户选择的位置创建笔记

唯一例外：如果 .claude/project-config 已根据用户先前的选择指定了位置，则可创建项目会话笔记。

黄金法则：如果你准备将文件写入 Obsidian 库，先停下来询问用户希望将文件放在哪里。

规则 2：会话笔记始终添加 Dump 标签

会话／每日笔记中始终包含 dump 标签。这对于以下事项至关重要：

• 跨项目筛选所有会话笔记：tag:#dump
• 使用 /consolidate-notes 归档工作流
• 将工作笔记与永久文档分开

新建会话文件的 Python 模板：

f.write("---\n")
f.write("type: session\n")
f.write(f"project: {PROJECT_NAME}\n")
f.write(f"date: {date_str}\n")
f.write("tags:\n")
f.write("  - session\n")
f.write("  - dump\n")  # REQUIRED
f.write("status: completed\n")
f.write("---\n\n")

规则 3：始终添加属性（Frontmatter）

每篇笔记都必须包含 YAML Frontmatter，至少包含：

---
type: session | planning | reference | todo | moc | development | analysis
project: project-name
status: active | in-progress | completed | archived
tags:
  - relevant-tags
created: YYYY-MM-DD
---

完整的属性架构请参阅 best-practices.md。

规则 4：使用 MOC，而不是深层文件夹

• 保持文件夹结构扁平（最多 2-3 层）
• 使用内容地图（MOC）笔记作为导航中心
• 每个 MOC 最多包含 25 个条目
• 当某个部分变得过大时，创建子 MOC
• 使用属性和标签对主题进行分类，而不是使用文件夹

有关 MOC 的详细指导，请参阅 best-practices.md。

Vault 配置

环境设置

# Check vault location
echo $OBSIDIAN_VAULT
# Should return something like: /Users/username/Documents/Notes

# If not set, add to ~/.zshrc or ~/.bashrc
export OBSIDIAN_VAULT="/path/to/your/vault"

Obsidian CLI（1.12+）

Obsidian 现在自带原生 CLI（obsidian）。创建、读取、追加和搜索笔记时，优先使用 CLI 命令，而不是 bash 模式。

# Verify CLI is available
obsidian version

# List vaults
obsidian vaults verbose

# Target a specific vault
obsidian files vault="My Vault"

完整的 CLI 命令参考请参阅 cli-reference.md。

关键工作流

创建笔记

1. 检查 vault 是否可访问（obsidian vault 或 echo $OBSIDIAN_VAULT）
2. 向用户展示 vault 结构（obsidian folders 或 obsidian files）
3. 询问笔记的保存位置
4. 使用恰当的 frontmatter 创建笔记（type、project、tags、created date）
5. 如果是会话笔记，请添加 dump 标签
6. 添加指向相关笔记的 wikilinks

使用 CLI：

obsidian create name="my-note" path="projects/my-note.md" template="session" open
# Or with inline content:
obsidian create name="my-note" content="---\ntype: session\ntags:\n  - dump\n---\n\n# Content"

使用 bash（适用于复杂的多行内容）：

cat > "$OBSIDIAN_VAULT/projects/my-note.md" <<'EOF'
---
type: session
tags:
  - dump
---
# Content
EOF

笔记模板请参阅 templates.md。

创建会话摘要

由 /safe-exit 和 /safe-clear 命令使用：

1. 从 .claude/project-config 读取项目配置，获取 vault 路径
2. 在项目的 session-saves/ 目录中创建笔记
3. 添加包含 type: session 和 dump 标签的 frontmatter
4. 记录：上下文、摘要、决策、待办事项和代码引用
5. 链接到相关笔记

整理会话笔记

当会话文件夹中有 5 篇或更多笔记，或到达项目里程碑时：

1. 检查所有会话笔记，找出主题
2. 创建主题参考笔记（按主题而非日期）
3. 将 TODO 提取到项目的 TO-DOS.md
4. 将已处理的会话归档到 archived/daily/
5. 更新项目 HOME.md 和 MOC

完整的整理工作流请参阅 vault-management.md。

Vault 重组

重组 vault 时：

1. 记录目标结构
2. 先创建新文件夹
3. 移动文件和文件夹
4. 系统地更新所有链接
5. 检测失效链接
6. 使用 tree 命令验证

详细的重组步骤请参阅 vault-management.md。

标准项目结构

project-name/
├── TO-DOS.md
├── session-saves/
├── archived/
│   ├── daily/
│   └── monthly/
└── [project-specific folders]

Obsidian 语法速查

[[Note Name]]              # Wikilink
[[Note Name|Display Text]] # Wikilink with alias
[[Note#Heading]]           # Link to heading
#tag  #project/feature     # Tags
- [ ] Task to do           # Task
- [x] Completed task       # Done task
> [!note]                  # Callout
> Content here

完整的语法参考请参阅 reference.md。

与其他技能集成

• folder-organization - Vault 结构规范
• managing-environments - 开发工作流
• claude-collaboration - 团队知识共享

---

请记住：目标是构建一个可搜索、相互链接的知识库，并随着每次 Claude 会话不断扩展。从简单开始，按需添加结构。