Obsidian Vault Management Skill

Obsidian Vault Management

Purpose

This skill provides expert guidance for working with Obsidian vaults, enabling effective knowledge management through proper syntax usage, organizational best practices, and workflow automation. It covers Obsidian Flavored Markdown (OFM), modern organization methodologies, task management workflows, and integration with Claude Code.

When to Use This Skill

Use this skill when:

Working with Obsidian notes and needing to understand OFM syntax
Organizing or restructuring an Obsidian vault
Setting up daily/weekly task management workflows
Creating templates for notes, projects, or reviews
Performing vault maintenance (finding broken links, orphaned notes, etc.)
Helping users implement knowledge management best practices
Integrating Obsidian with automation tools or Claude Code

Obsidian Flavored Markdown (OFM)

Key Syntax Differences

Obsidian extends standard Markdown with wiki-inspired features:

Wikilinks (Internal Linking):

[[Note Name]] - Link to another note
[[Note Name|Display Text]] - Custom display text
[[Note#Heading]] - Link to specific heading
[[Note^block-id]] - Link to specific block
Add ^block-id at end of any line to create referenceable blocks

Embeds (Transclusion):

![[Note]] - Embed entire note
![[Note#Heading]] - Embed from heading onwards
![[Note^block-id]] - Embed specific block
![[Image.jpg]] - Embed media files

Callouts:

> [!note] Optional Title
> Content here

Types: note, tip, info, todo, warning, danger, error, bug, example, abstract, success, question, failure, important, quote

Collapsible: [!tip]+ (expanded) or [!tip]- (collapsed)

Tags:

#tag - Basic tag
#parent/child/grandchild - Nested hierarchy

Comments:

%% Hidden comment %% - Obsidian-only, not portable

Highlights:

==highlighted text== - Obsidian-specific

Properties/Frontmatter:

---
title: Note Title
date: 2025-11-12
tags: [tag1, tag2]
status: active
---

Math (LaTeX):

Inline: $E = mc^2$
Display: $$equation$$

Diagrams (Mermaid):

```mermaid
graph LR
    A --> B --> C
```

Dataview Queries (if plugin installed):

```dataview
TABLE rating, date
FROM #books
SORT rating DESC
```

For complete syntax details, refer to references/ofm-syntax.md.

Organization Best Practices

Recommended Folder Structures

ACE Framework (Recommended):

Atlas/          # Knowledge maps, ideas, reference materials
Calendar/       # Daily notes, periodic notes, time-based entries
Efforts/        # Projects, goals, active work

FINVA System (Workflow-based):

Fleeting/       # Quick rough notes (weekly review)
In Progress/    # Projects needing work
Notes/          # Permanent completed notes
Views/          # MOCs and organizational notes
Archives/       # Old projects

Zettelkasten (Research-focused):

Fleeting/       # Temporary captures
Permanent/      # Atomic evergreen notes

Core Principles

Use minimal folders (3-7 top-level max)
Organize by note TYPE, not TOPIC - let links connect topics
Create MOCs (Maps of Content) as navigation hubs
Design for worst-day usability - system must work when tired
Let structure emerge organically rather than pre-planning everything

Maps of Content (MOCs)

MOCs are index notes that link to related notes:

# Topic Name

## Overview
Brief description

## Subtopic 1
- [[Note 1]]
- [[Note 2]]

## Subtopic 2
- [[Note 3]]
- [[Note 4]]

Create MOCs when:

Experiencing "mental squeeze point" (juggling too many related notes)
Topic has 5+ related notes
Need navigation hub for an area

For detailed organization strategies, refer to references/organization-guide.md.

Daily/Weekly Task Workflows

Essential Plugins

Daily Notes (Core) - Creates daily notes
Templater (Community) - Advanced templates
Tasks (Community) - Task management
Dataview (Community) - Query and display data
Day Planner (Community) - Time blocking

Templates

Daily note template available at assets/templates/daily-note.md Weekly review template available at assets/templates/weekly-review.md Project template available at assets/templates/project.md

Task Syntax (Tasks Plugin)

- [ ] Basic task
- [ ] Task with due date =Å 2025-11-15
- [ ] High priority task ë
- [ ] Recurring task = every week

Time Blocking

Use Day Planner plugin with 24-hour format:

## Today's Schedule

- [ ] 07:00 Morning Routine
- [ ] 08:00 Deep Work - Project X
- [ ] 10:00 Team Meeting

For complete workflow details, refer to references/task-workflows.md.

Vault Maintenance Workflows

Health Check Workflow

When performing vault health checks:

Find broken links:
- Read all notes and extract [[wikilinks]]
- Check if target files exist
- Report broken links with source locations
Find orphaned notes:
- Analyze all notes for incoming/outgoing links
- Report notes with no connections
Check frontmatter completeness:
- Verify all notes have required metadata
- Report missing fields
Find duplicate titles:
- Compare note filenames and titles
- Flag potential duplicates
Identify stubs:
- Find notes with less than 100 words
- Suggest expansion or archival

Use scripts/vault_health.py for automated health checks.

Note Organization Workflow

When organizing notes:

Analyze content:
- Read note content and existing metadata
- Identify main topics and themes
Suggest improvements:
- Appropriate tags based on content
- Related notes that should be linked
- Folder location if misplaced
- Missing frontmatter fields
Get approval:
- Show proposed changes
- Ask for confirmation
- Apply changes systematically

Batch Operations Safety

When performing batch operations:

Always preview changes first:
- Show before/after
- List affected files
- Get explicit approval
Process in batches:
- Handle 50 files at a time for large vaults
- Provide progress updates
Preserve Obsidian syntax:
- Don't break wikilinks when renaming
- Keep embeds functional
- Maintain block references
Backup reminder:
- Remind user to backup before major changes
- Suggest git commit if using version control

Quality Standards

When Creating/Editing Notes

Always ensure:

Frontmatter is present and complete:

---
title: Note Title
created: YYYY-MM-DD
tags: [relevant, tags]
---

First heading matches title:
```
# Note Title
```
Wikilinks are properly formatted:
- Use [[Note Name]] not [Note Name](note-name.md)
- Check that linked notes exist
- Suggest creating missing notes

Appropriate callouts for key info:

> [!important]
> Critical information here

Related notes are linked:
- Add "Related" or "See Also" section
- Link to parent MOC
- Link to related projects
Tags follow convention:
- Use nested tags: #category/subcategory
- Be consistent with existing tags
- Don't create redundant tags

Claude Code Integration

MCP (Model Context Protocol) Setup

For AI-assisted vault management:

Install "Local REST API" community plugin in Obsidian
Generate API key in Obsidian settings
Install MCP server: npx -y @smithery/cli install mcp-obsidian --client claude
Restart Claude Desktop

Vault Context File

Recommend users create CLAUDE.md in vault root with:

Vault structure description
Naming conventions
Common workflows
Quality standards

Example vault context file available at assets/templates/CLAUDE.md

Available MCP Operations

obsidian_read_note - Read content and metadata
obsidian_global_search - Search entire vault
obsidian_update_note - Append, prepend, or overwrite
obsidian_manage_frontmatter - Get/set YAML metadata
obsidian_manage_tags - Add/remove tags

Recommended Tools

Export & Publishing

obsidian-export (Rust CLI) - Convert vault to standard markdown
Quartz v4 - Static site generator for Obsidian
Obsidian Digital Garden - Netlify publishing plugin

Terminal Access

obsidian-cli (Yakitrak/Go) - CLI for vault operations

Automation

obsidian-metadata (Python) - Bulk metadata operations
Templater - Advanced templates with JavaScript
Linter - Automated formatting

Sync & Backup

Obsidian Git - Version control (desktop)
Remotely Save - Multi-cloud sync (mobile-friendly)

For complete tooling reference, see references/tools-and-automation.md.

Best Practices Summary

Start simple - 3-7 top-level folders, evolve organically
Use links liberally - Connect related ideas naturally
Create MOCs - Navigation hubs for major topics
Maintain daily notes - Capture everything daily
Weekly reviews - Regular reflection and cleanup
Atomic notes - One main idea per note
Use templates - Consistency and efficiency
Automate repetitive tasks - Plugins and scripts
Backup regularly - Git or cloud sync
Design for retrieval - Optimize for finding, not filing

Performance Optimization

For Large Vaults

Use specific paths - Don't search entire vault unnecessarily
Batch processing - Process 50 files at a time
Efficient queries - Use Dataview for complex queries
Cache results - Don't re-read unchanged files

Troubleshooting

Broken Links

Cause: Note renamed/moved without updating links
Solution: Find all occurrences, update to new path/name

Orphaned Notes

Cause: No incoming or outgoing links
Solution: Review content, link to relevant MOC, archive if obsolete

Inconsistent Metadata

Cause: Different templates or manual editing
Solution: Use obsidian-metadata CLI for bulk updates, enforce template usage

Additional Resources

For comprehensive details on specific topics, refer to:

references/ofm-syntax.md - Complete OFM syntax guide
references/organization-guide.md - Detailed organization strategies
references/task-workflows.md - Complete workflow implementations
references/tools-and-automation.md - CLI tools and automation guide

Templates and assets available in assets/templates/.

Agent Skills: Obsidian Vault Management

Skill Files