Obsidian Vault Management

Manage the Obsidian vault as a developer knowledge base and automatic work journal.

When to Use

Activate this skill when:

• User requests note operations (add, search, update, import, link, archive)

• Working with project documentation that should be stored in the vault

• Auto-capturing commits, tasks, or Claude Code components

• User asks about their notes, documentation, or knowledge base

• Organizing or finding information in the vault

Vault Structure

~/guerra_vault/ ├── projects/ # Project-specific documentation ├── technologies/ # Technology knowledge (Laravel, React, etc.) ├── claude-code/ # Claude Code components │ ├── agents/ │ ├── hooks/ │ ├── skills/ │ └── tools/ ├── ideas/ # Feature ideas and experiments ├── personal/ # Career and learning goals ├── todo/ # Tasks and checklists ├── references/ # Bookmarks, snippets, cheatsheets ├── journal/ # Auto-captured events │ ├── commits/ # Git commit documentation │ ├── tasks/ # Completed task summaries │ └── creations/ # Component creation logs └── _archive/ # Archived notes

Frontmatter Standard

All notes MUST include this YAML frontmatter:

title: "Note Title" description: "Brief description of the content" tags: [tag1, tag2, category] related: [[path/to/related-note]] created: YYYY-MM-DD updated: YYYY-MM-DD

Rules:

• title : Descriptive, matches the main heading

• description : One sentence explaining the content

• tags : Always include the category as a tag

• related : Wiki-link format, add related notes when relevant

• created : Set once when created

• updated : Update whenever the note changes

Available Commands

Command Purpose

/obsidian-vault:init

Set up vault configuration and structure

/obsidian-vault:add <category> <title>

Create a new note

/obsidian-vault:search <query>

Find notes by title, content, or tags

/obsidian-vault:update <note>

Edit note frontmatter or append content

/obsidian-vault:import <file>

Import external files with frontmatter

/obsidian-vault:list [category]

List notes, optionally by category

/obsidian-vault:tags [--stats]

View tags and usage statistics

/obsidian-vault:link <note1> <note2>

Create bidirectional related links

/obsidian-vault:archive <note>

Move note to archive

Auto-Capture Behavior

The plugin automatically captures:

Git Commits

• Creates journal/commits/YYYY-MM-DD-<slug>.md

• Includes: commit message, date, project, branch, files changed

• Placeholder sections for "What" and "Why" (fill in with context)

Task Completions

• Creates journal/tasks/YYYY-MM-DD-<slug>.md

• Captures subagent summaries

• Includes: summary, what was done, decisions made

Claude Code Components

• Creates claude-code/<type>s/<name>.md

• Tracks: agents, hooks, skills, tools

• Also logs to journal/creations/

Best Practices

Creating Notes

• Choose the appropriate category

• Use descriptive titles

• Add relevant tags immediately

• Link to related notes when obvious

Updating Notes

• Update the updated date (done automatically by scripts)

• Add new related links as connections emerge

• Keep descriptions current

Searching

• Start broad, narrow with --title , --content , or --tag

• Use --category to focus on specific areas

• Check related notes for additional context

Organization

• Use consistent naming within categories

• Archive rather than delete

• Maintain bidirectional links

Integration with Workflows

After Completing Features

When finishing a feature or fix:

• Ensure commit is captured

• Add/update project documentation

• Link new notes to project README

When Learning Technologies

• Create note in technologies/

• Link to projects that use it

• Add code snippets as needed

For Ideas and Experiments

• Start in ideas/

• Move to projects/ when starting implementation

• Archive if abandoned

Additional Resources

Reference Files

• references/frontmatter-spec.md
• Detailed frontmatter specification

Configuration

• Config: ~/.claude/obsidian-vault.json

• Vault path: ~/guerra_vault