obsidian-vault-crud

name	obsidian-vault-crud
description	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.
allowed-tools	Bash, Read, Write

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

python plugins/obsidian-integration/skills/obsidian-vault-crud/scripts/vault_ops.py read --file <path>

Create a Note

python plugins/obsidian-integration/skills/obsidian-vault-crud/scripts/vault_ops.py create --file <path> --content <text> [--frontmatter key=value ...]

Update a Note

python plugins/obsidian-integration/skills/obsidian-vault-crud/scripts/vault_ops.py update --file <path> --content <text>

Append to a Note

python plugins/obsidian-integration/skills/obsidian-vault-crud/scripts/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