Obsidian Integration

Expert guidance for integrating Claude workflows with Obsidian vault, including note creation, task management, and knowledge organization using Obsidian's markdown-based system.

When to Use This Skill

• Creating notes during development sessions with Claude

• Tracking tasks and TODOs in Obsidian

• Documenting decisions and solutions discovered with Claude

• Building a knowledge base of project insights

• Organizing research findings from Claude sessions

• Creating meeting notes or session summaries

Supporting Files

This skill is split across several files. Load the relevant file when needed:

• best-practices.md - MOCs, properties, organization philosophy, dump tag requirements

• templates.md - Note templates: session, technical, task, analysis planning, thematic reference, TODO, HOME.md

• organization-patterns.md - Home MOC, Project MOC, TODO consolidation, archive strategy, cross-project linking

• vault-management.md - Vault reorganization, session consolidation, link management, project directory setup, brain dump handling

• reference.md - Obsidian markdown syntax, bash helpers, plugins, Claude integration patterns, troubleshooting

• cli-reference.md - Obsidian CLI (1.12+) command reference, replaces many bash patterns

• changelog.md - Version history

Core Principles

• Prefer CLI - Use obsidian CLI commands (1.12+) over bash/cat patterns when possible. See cli-reference.md

• Vault Location - Use $OBSIDIAN_VAULT environment variable for direct file access; CLI uses vault=<name> option

• Always Ask User for Note Placement - Never decide where to save notes without asking the user first. Show vault structure, suggest options, and let the user choose.

• Atomic Notes - Each note focuses on a single concept or topic

• Linking - Use wikilinks [[note-name]] to connect related ideas

• Tags - Organize with hierarchical tags like #project/feature

• Tasks - Use checkbox syntax for actionable items

• Timestamps - Include dates for temporal context

Essential Rules

Rule 1: Never Assume Note Placement

CRITICAL: When creating ANY note in Obsidian, ALWAYS ask the user where they want it saved. Never decide the location yourself, even if it seems obvious.

Why: The user knows how their vault is organized. Assuming a location means they'll need to reorganize later.

Workflow for ANY note creation:

• Show current vault structure to help user decide

• Suggest options (root level, specific folder, custom path) -- do NOT decide

• Get user input before writing anything

• Create in chosen location

Only exception: Project session notes when .claude/project-config already specifies the location from a previous user choice.

Golden Rule: If you're about to write a file to the Obsidian vault, STOP and ask the user where it should go first.

Rule 2: Always Include Dump Tag in Session Notes

ALWAYS include the dump tag in session/daily notes. This is essential for:

• Filtering all session notes across projects: tag:#dump

• Archiving workflows with /consolidate-notes

• Separating working notes from permanent documentation

Python template for new session files:

f.write("---\n") f.write("type: session\n") f.write(f"project: {PROJECT_NAME}\n") f.write(f"date: {date_str}\n") f.write("tags:\n") f.write(" - session\n") f.write(" - dump\n") # REQUIRED f.write("status: completed\n") f.write("---\n\n")

Rule 3: Always Add Properties (Frontmatter)

Every note must have YAML frontmatter with at minimum:

type: session | planning | reference | todo | moc | development | analysis project: project-name status: active | in-progress | completed | archived tags:

• relevant-tags created: YYYY-MM-DD

For the full property schema, see best-practices.md.

Rule 4: Use MOCs Over Deep Folders

• Keep folder structure flat (2-3 levels max)

• Use Maps of Content (MOC) notes as navigation hubs

• Keep MOCs under 25 items

• Create sub-MOCs when sections grow too large

• Use properties and tags for topic categorization, not folders

For detailed MOC guidance, see best-practices.md.

Vault Configuration

Environment Setup

Check vault location

echo $OBSIDIAN_VAULT

Should return something like: /Users/username/Documents/Notes

If not set, add to ~/.zshrc or ~/.bashrc

export OBSIDIAN_VAULT="/path/to/your/vault"

Obsidian CLI (1.12+)

Obsidian now ships with a native CLI (obsidian ). Prefer CLI commands over bash patterns for creating, reading, appending, and searching notes.

Verify CLI is available

obsidian version

List vaults

obsidian vaults verbose

Target a specific vault

obsidian files vault="My Vault"

For the full CLI command reference, see cli-reference.md.

Key Workflows

Creating a Note

• Check vault is accessible (obsidian vault or echo $OBSIDIAN_VAULT )

• Show vault structure to user (obsidian folders or obsidian files )

• Ask where to save the note

• Create with proper frontmatter (type, project, tags, created date)

• Include dump tag if it's a session note

• Add wikilinks to related notes

Using CLI:

obsidian create name="my-note" path="projects/my-note.md" template="session" open

Or with inline content:

obsidian create name="my-note" content="---\ntype: session\ntags:\n - dump\n---\n\n# Content"

Using bash (for complex multi-line content):

cat > "$OBSIDIAN_VAULT/projects/my-note.md" <<'EOF'

type: session tags:

• dump

Content

EOF

For note templates, see templates.md.

Creating a Session Summary

Used by /safe-exit and /safe-clear commands:

• Read project config from .claude/project-config for vault path

• Create note in project's session-saves/ directory

• Include frontmatter with type: session , dump tag

• Document: context, summary, decisions, action items, code references

• Link to related notes

Consolidating Session Notes

When session folder has 5+ notes or at project milestones:

• Review all session notes, identify themes

• Create thematic reference notes (by topic, not date)

• Extract TODOs to project TO-DOS.md

• Archive processed sessions to archived/daily/

• Update project HOME.md and MOCs

For the full consolidation workflow, see vault-management.md.

Vault Reorganization

When restructuring the vault:

• Document target structure

• Create new folders first

• Move files and folders

• Update all links systematically

• Run broken link detection

• Verify with tree command

For detailed reorganization steps, see vault-management.md.

Standard Project Structure

project-name/ ├── TO-DOS.md ├── session-saves/ ├── archived/ │ ├── daily/ │ └── monthly/ └── [project-specific folders]

Obsidian Syntax Quick Reference

[[Note Name]] # Wikilink [[Note Name|Display Text]] # Wikilink with alias [[Note#Heading]] # Link to heading #tag #project/feature # Tags

• Task to do # Task
• Completed task # Done task

[!note] # Callout Content here

For full syntax reference, see reference.md.

Integration with Other Skills

• folder-organization - Vault structure standards

• managing-environments - Development workflow

• claude-collaboration - Team knowledge sharing

Remember: The goal is to build a searchable, linked knowledge base that grows with each Claude session. Start simple, add structure as needed.