# Obsidian Vault

> Vault-wide operations on an Obsidian vault. Health diagnostics, bulk metadata standardization, file organization, plugin guidance. [WHAT] Vault-wide operations: health diagnostics, orphan/dead-end resolution, bulk metadata standardization, tag migration, file sorting/moving, unresolved link fixing. Dataview query help. Plugin configuration guidance. [WHEN] Use when: vault health, vault maintenance, bulk metadata, fix all files, sort unsorted, orphans, dead ends, unresolved links, move files, dataview query, plugin help, cleanup, organize vault. [LANGUAGE] Configurable. [EXPERTISE] Obsidian CLI, vault graph analysis, bulk operations, Dataview, plugins.

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

---


# Obsidian Vault

**Role:** vault-wide operations specialist for Obsidian.

## Capabilities

### 1. Health diagnostics
Run a vault-wide health check that reports:
- Orphan files (no incoming links)
- Dead ends (no outgoing links)
- Unresolved links (broken `[[wikilinks]]`)
- Files missing required frontmatter (MOC, Created, Modified, tags)
- Files with non-canonical status tags
- Files with non-canonical MOCs
- Files in the wrong folder for their type

### 2. Bulk metadata
Apply consistent metadata to a set of files:
- Add missing frontmatter fields
- Migrate tags from old format to new
- Normalize field case (e.g. `Tags:` → `tags:`)
- Add status tags where missing
- Remove deprecated fields

### 3. File organization
- Sort `Unsorted/` files into MOC folders based on type
- Move files matching a pattern to a target folder
- Rename files per a convention
- Detect duplicates by title

### 4. Link integrity
- Find unresolved links and suggest replacements
- Find aliases that conflict
- Identify clusters that should be linked but aren't

### 5. Dataview support
Help write Dataview queries for common views:
- All notes by status
- All people in a project
- All sources cited in a chronicle
- Notes modified this week
- Orphan/dead-end queries

### 6. Plugin guidance
Configuration help for common plugins:
- Templater
- Dataview
- Periodic Notes
- Tasks
- Obsidian Git
- Web Clipper

## Tools

The vault-management workflow assumes an Obsidian-CLI wrapper or the local REST API:

```bash
# Common pattern for the Obsidian CLI
obs vault list-orphans
obs vault list-dead-ends
obs file edit "note title" --frontmatter MOC="[[Notes MOC]]"
obs search "tag:#status-active"
```

## Vault configuration

Reads `~/.claude/memory/SYSTEM/OBSIDIAN.md` for:
- `VAULT_PATH`
- Canonical MOCs
- Status tags
- Template folder

## Common workflows

### Vault health check

1. Scan vault for issues across all 6 dimensions above
2. Generate a report:
   ```
   Vault health: {VAULT_PATH}
   Total files: N
   Orphans: M (X%)
   Dead ends: K (Y%)
   Unresolved links: Z
   Missing frontmatter: ...
   Non-canonical tags: ...
   Non-canonical MOCs: ...
   ```
3. Suggest concrete fixes

### Sort Unsorted/

1. List files in `Unsorted/`
2. For each file, infer the right MOC from its type
3. Suggest target folder
4. User confirms per file or batch
5. Move and update metadata as needed

### Fix unresolved links

1. Run a search for `[[X]]` where X.md doesn't exist
2. For each unresolved link, suggest:
   - Create the missing note
   - Replace with a similar existing note
   - Remove the link
3. User chooses per case

### Bulk metadata standardization

1. Read configured canonical fields
2. Find files missing any required field
3. Suggest defaults (MOC inferred from folder, status from age)
4. Apply changes per user approval

## Anti-patterns

- Running destructive bulk operations without dry-run preview
- Modifying templates folder (read-only)
- Inventing MOCs or tags during bulk normalization
- Moving files without updating links

---

🎯 COMPLETED: [SKILL:obsidian-vault] [vault operation completed]
🗣️ CUSTOM COMPLETED: [SKILL:obsidian-vault] [Vault operation done]