# Obsidian Vault Crud

> Safe Create/Read/Update/Delete operations for Obsidian Vault notes. Implements atomic writes, advisory locking, concurrent edit detection, and lossless YAML frontmatter handling. Use when reading, writing, updating, or appending to any vault note.

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

---


## Dependencies

This skill requires **Python 3.8+** and standard library only. No external packages needed.

**To install this skill's dependencies:**
```bash
pip-compile ./requirements.in
pip install -r ./requirements.txt
```

See `./requirements.txt` for the dependency lockfile (currently empty — standard library only).

---
# Obsidian Vault CRUD

**Status:** Active
**Author:** Richard Fremmerlid
**Domain:** Obsidian Integration
**Depends On:** `obsidian-markdown-mastery` (WP05)

## Core Mandate

This skill provides the **disk I/O layer** for all agent interactions with the Obsidian Vault. It does NOT handle syntax parsing (that belongs to `obsidian-markdown-mastery`). Instead, it ensures that every file write is:

1. **Atomic** — via POSIX `os.rename()` from a `.tmp` staging file
2. **Locked** — via an advisory `.agent-lock` file at the vault root
3. **Conflict-aware** — via `mtime` comparison before/after read
4. **Lossless** — via `ruamel.yaml` for frontmatter (never PyYAML)

## Available Commands

### Read a Note
```bash
python ./vault_ops.py read --file <path>
```

### Create a Note
```bash
python ./vault_ops.py create --file <path> --content <text> [--frontmatter key=value ...]
```

### Update a Note
```bash
python ./vault_ops.py update --file <path> --content <text>
```

### Append to a Note
```bash
python ./vault_ops.py append --file <path> --content <text>
```

## Safety Guarantees

### Atomic Write Protocol
1. Write content to `<target>.agent-tmp`
2. Verify the `.agent-tmp` file was written completely
3. `os.rename('<target>.agent-tmp', '<target>')` — atomic on POSIX
4. If any step fails, the `.agent-tmp` is cleaned up

### Advisory Lock Protocol
- Before any write batch: create `<vault_root>/.agent-lock`
- After write batch completes: remove `.agent-lock`
- Other agents check for `.agent-lock` before writing
- This is advisory (does not block Obsidian UI)

### Concurrent Edit Detection
- Capture `os.stat(file).st_mtime` before reading
- Before writing, check `st_mtime` again
- If mtime changed → another process edited the file → **ABORT**

### Frontmatter Handling
- Uses `ruamel.yaml` (NOT `PyYAML`) to preserve comments, indentation, and array styles
- Ensures Dataview and Obsidian Properties remain intact