richfrem/agent-plugins-skills / plugins/agent-memory/.apm/skills/managing-obsidian-vaults
managing-obsidian-vaults
VerifiedInteractive vault, wiki and Super-RAG setup in the main conversation. Use for "set up my wiki", "initialize the full knowledge stack" or combined RLM/vector/wiki setup. Manage Obsidian vaults and LLM wikis: initialize vaults, author Markdown and wikilinks, safely edit notes and Bases, create Canvas diagrams, traverse graphs, build concept wikis, distill summary/bullets/deep layers, query and lint knowledge.
references/architecture-background.md
View on GitHub# Obsidian Integration: Architecture Background
## Why Direct Filesystem (Zero-RPC)?
After evaluating three integration strategies, the direct filesystem read/write approach
was chosen over Obsidian's Local REST API and custom TypeScript plugins because it minimizes
external dependencies and works completely offline.
### Strategies Evaluated
| Strategy | Pros | Cons | Verdict |
|:---------|:-----|:-----|:--------|
| **Local REST API** | Clean HTTP interface | Requires Obsidian running; extra dependency | ❌ Rejected |
| **Custom TypeScript Plugin** | Deep Obsidian integration | Requires TypeScript build chain; brittle | ❌ Rejected |
| **Direct Filesystem** | Zero dependencies; works offline | No real-time sync | ✅ Chosen |
### Rationale
- **Zero Dependencies**: No running Obsidian instance required for agents to operate
- **Offline-First**: Agents can read/write vault files without any server
- **Git-Native**: Files are plain markdown tracked by Git — no proprietary format
- **Portability**: This plugin works on any project with `.md` files
## Key Architectural Principles
### 1. Agnosticism
The Obsidian skills know NOTHING about any specific project's domain logic.
They only know how to parse/write Obsidian-flavored markdown. Project-specific
context (like which folders map to what) is injected by the project's own
configuration (e.g., `VAULT_PATH`).
### 2. Separation of Concerns
```
obsidian-markdown-mastery → Syntax parsing (wikilinks, embeds, callouts)
obsidian-vault-crud → Safe disk I/O (atomic writes, locking, mtime)
obsidian-init → Vault bootstrapping and configuration
```
The parser never touches disk. The CRUD layer never parses syntax. Each skill has exactly one job.
### 3. Safety-First Writes
All file mutations use:
- **Atomic writes** via POSIX `os.rename()` from `.agent-tmp` staging files
- **Advisory locking** via `.agent-lock` at the vault root
- **Concurrent edit detection** via `mtime` comparison before/after operations
- **Lossless YAML** via `ruamel.yaml` (never PyYAML) for frontmatter
## Obsidian Vault Basics
An Obsidian Vault is simply a folder on disk. There is no database, no server,
no proprietary format. Obsidian reads `.md` files and builds its graph view,
backlinks, and search index from the raw text.
### Key Obsidian Syntax
- `[[Note Name]]` — Internal link (wikilink)
- `[[Note#Heading]]` — Link to a specific heading
- `[[Note#^block-id]]` — Link to a specific block
- `[[Note|Display Text]]` — Aliased link
- `![[Note]]` — Transclusion/embed (note the `!` prefix)
- `> [!type] Title` — Callout blocks
### Configuration
- `.obsidian/` — Local config directory (should be `.gitignore`d)
- `.obsidian/app.json` — App settings including `userIgnoreFilters`
- Frontmatter (YAML between `---` delimiters) — Metadata for Dataview and Properties
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |