# Obsidian

> obsidian

- Skill: `yakeworld/obsidian` (Agent Skill, multi-file: 16 files)
- Install (CLI): `npx skillmds@latest add yakeworld/obsidian`
- Raw SKILL.md: https://api.skillmd.com/api/skills/yakeworld/obsidian/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: yakeworld (https://skillmd.com/u/yakeworld)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/yakeworld/obsidian

---



## Operational Steps
1. 确认输入参数完整
2. 执行核心操作（参考本目录下的 scripts/ 或 references/）
3. 验证输出符合契约
4. 保存结果并报告

## Pitfalls
- 
- 

## Verification
- 
- 
- 
- 
1. 
2. 
3. 
## IO_CONTRACT

- **input**: `request: str, context: dict` — 用户请求描述、上下文信息
- **output**: `result: dict — 技能执行结果（结构因技能而异）`

> 对应原则：P2（机械原子暴露输入输出规范）

# Obsidian Vault

Use this skill for filesystem-first Obsidian vault work: reading notes, listing notes, searching note files, creating notes, appending content, adding wikilinks, and initializing project knowledge bases.

Covers two tiers of work:
- **Tier 1: Note ops** — read, search, create, edit individual notes within an existing vault.
- **Tier 2: Vault init** — initialize a directory as an Obsidian knowledge base with MOC structure, frontmatter, symlinks to source files, and sync scripts.

## Vault path

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 `~/.hermes/.env`. If it is unset, use `~/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.

## Read a note

Use `read_file` with the resolved absolute path to the note. Prefer this over `cat` because it provides line numbers and pagination.

## List notes

Use `search_files` with `target: "files"` and the resolved vault path. Prefer this over `find` or `ls`.

- To list all markdown notes, use `pattern: "*.md"` under the vault path.
- To list a subfolder, search under that subfolder's absolute path.

## Search

Use `search_files` for both filename and content searches. Prefer this over `grep`, `find`, or `ls`.

- For filenames, use `search_files` with `target: "files"` and a filename `pattern`.
- For note contents, use `search_files` with `target: "content"`, the content regex as `pattern`, and `file_glob: "*.md"` when you want to restrict matches to markdown notes.

## Create a note

Use `write_file` with the resolved absolute path and the full markdown content. Prefer this over shell heredocs or `echo` because it avoids shell quoting issues and returns structured results.

## Append to a note

Prefer a native file-tool workflow when it is not awkward:

- Read the target note with `read_file`.
- Use `patch` for an anchored append when there is stable context, such as adding a section after an existing heading or appending before a known trailing block.
- Use `write_file` when rewriting the whole note is clearer than constructing a fragile patch.

For an anchored append with `patch`, replace the anchor with the anchor plus the new content.

For a simple append with no stable context, `terminal` is acceptable if it is the clearest safe option.

## Targeted edits

Use `patch` for focused note changes when the current content gives you stable context. Prefer this over shell text rewriting.

## Vault setup — convert a code/research repo into an Obsidian knowledge base

For converting an existing project directory into an Obsidian knowledge base, see:
- `references/vault-setup-workflow.md` — class-level workflow

## Related files

- `references/vault-setup-workflow.md` — full vault setup workflow

---

## Tier 2: Vault Initialization — 项目知识库搭建

当需要把现有项目目录变成可导航的 Obsidian 知识库时，按以下步骤。

### 何时使用

- 项目已有大量 `.md`、`.tex`、`.pdf` 文件需要组织
- 需要跨文档导航（图谱、反链、标签）
- 需要区分笔记层（分析/注释）和源文件层（原文）

### 步骤

**Step 1: 添加 `.obsidian/` 配置**
```json
// core-plugins.json — 启用图谱、反链、标签、文件搜索
{
  "core:backlink": true,
  "core:graph": true,
  "core:tag-pane": true,
  "core:search": true,
  "core:file-explorer": true,
  "core:command-palette": true
}
```
同时把 `.obsidian/` 加入 `.gitignore`。

**Step 2: 创建 MOC 索引链**

在每个子目录建 `_INDEX.md`（Map of Content），形成可导航的入口：

```
项目根/
├── _INDEX.md              ← 总入口（快速链接到各区域）
├── docs/_INDEX.md          ← 文档区
├── skills/_INDEX.md        ← 技能/知识点区
├── papers/_INDEX.md        ← 论文笔记区
└── outputs/papers/_INDEX.md ← 原文源文件区
```

**Step 3: 添加 YAML frontmatter**

```yaml
---
tags: [paper, iris, segmentation]
aliases: [中文名, English Alt Name]
---
```

**Step 4: 添加参照链接**

每个笔记末尾添加：
```markdown
## 参照
- [[papers/_INDEX|📝 论文目录]]
- [[_INDEX|← 返回根 MOC]]
```

**Step 5: 链接外部源文件**

用符号链接将已有文件（TeX、PDF、数据）映射到 vault 内：
```bash
ln -s /path/to/source/dir outputs/papers/paper-name/
```

**Step 6: 建立与 fact_store 的同步**

在 `scripts/` 下放同步脚本。核心逻辑：
- 扫描修改过的 `.md` 文件
- 提取 `**key**: value`、表格行、frontmatter tags
- 写入 `fact_store` SQLite 数据库
- 重建 FTS 索引

### 已知陷阱

- **不要直接复制源文件**：使用符号链接保持源目录干净，且 Git 不跟踪 vault 元文件
- **MOC 命名**：`_INDEX.md` 的 `_` 前缀让它在 Obsidian 文件浏览器中置顶
- **Wikilink 中的空格**：Obsidian wikilink 支持空格，但路径中有 `'`（单引号）时需用 `\` 转义
- **frontmatter tag 格式**：`tags: [a, b, c]` 比 `tags: a, b, c` 更兼容

### 相关文件

- `references/synthos-vault-init-2026-05-27.md` — Synthos 知识库搭建实例

## 验证清单 · VERIFICATION

- [ ] Vault 路径已解析为具体绝对路径（不含 `$OBSIDIAN_VAULT_PATH` 未展开变量），含空格的路径也正确传递
- [ ] 文件操作用原生工具完成：`read_file` / `write_file` / `patch` / `search_files` 替代 `cat` / `find` / `grep` / `ls`
- [ ] 新建/编辑笔记的 YAML frontmatter 用数组格式 `tags: [a, b, c]`，wikilink 中的单引号已用 `\` 转义
- [ ] 局部修改用 `patch` 锚定追加（有稳定上下文时），仅在整体重写更清晰时才用 `write_file`
- [ ] Vault 初始化后：各子目录存在 `_INDEX.md`（`_` 前缀置顶），`.obsidian/` 已加入 `.gitignore`
- [ ] 外部源文件（PDF/TeX）以符号链接映射进 vault 而非复制，链接目标可访问

## 约束规则 · RULES

1. **输入约束**: 参数类型、范围、格式必须校验
2. **输出约束**: 返回值结构、编码、命名必须一致
3. **异常约束**: 错误信息必须包含上下文和恢复建议
4. **安全约束**: 不执行未验证的任意代码，不暴露内部状态

## Golden 集合 · GOLDEN SET

- **Golden Input**: 标准输入样本（覆盖正常路径）
- **Golden Output**: 预期输出（精确匹配或格式校验）
- **Golden Error**: 预期错误信息（覆盖失败路径）

> Golden 集合是测试的单一真理来源。所有改进必须通过 golden 测试。

> 违反规则的操作视为不安全，必须拒绝或隔离。

> 每项验证必须可执行、可记录、可复现。验证失败时记录原因和修复。

# Obsidian

## Genes (策略基因)

> 紧凑策略表示。条件→策略。需要深度时参考完整文档。

- **[OBSI-001]** 当需要访问 Obsidian 笔记文件时 → 优先使用 `read_file`、`write_file` 等原生文件工具而非 Shell 命令，以避免路径空格和引号转义问题
- **[OBSI-002]** 当 Vault 路径包含环境变量（如 `$OBSIDIAN_VAULT_PATH`）时 → 必须先通过 `terminal` 解析为具体的绝对路径，再传递给文件工具，因为文件工具不支持变量展开
- **[OBSI-003]** 当需要搜索笔记文件名或内容时 → 统一使用 `search_files` 工具（分别指定 `target: "files"` 或 `target: "content"`），替代 `grep`、`find` 或 `ls`
- **[OBSI-004]** 当需要对笔记进行局部修改且存在稳定上下文锚点时 → 使用 `patch` 工具进行锚定追加或替换，仅在重写整个笔记更清晰时才使用 `write_file`
- **[OBSI-005]** 当初始化项目知识库（Vault Init）时 → 在每个子目录创建以 `_` 开头的 `_INDEX.md` 作为 MOC（内容地图），利用前缀使其在文件浏览器中置顶以实现快速导航
- **[OBSI-006]** 当需要将外部源文件（如 PDF、TeX）纳入 Vault 时 → 使用符号链接（symlink）映射源文件而非直接复制，以保持源目录整洁并避免 Git 跟踪冗余数据
- **[OBSI-007]** 当编写笔记的 YAML frontmatter 标签时 → 使用数组格式 `tags: [a, b, c]` 而非逗号分隔字符串，以确保更好的兼容性