Vault Management

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

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

1. Choose the appropriate category 2. Use descriptive titles 3. Add relevant tags immediately 4. Link to related notes when obvious

Updating Notes

1. Update the updated date (done automatically by scripts) 2. Add new related links as connections emerge 3. Keep descriptions current

Searching

1. Start broad, narrow with --title, --content, or --tag 2. Use --category to focus on specific areas 3. Check related notes for additional context

Organization

1. Use consistent naming within categories 2. Archive rather than delete 3. Maintain bidirectional links

Integration with Workflows

After Completing Features

When finishing a feature or fix: 1. Ensure commit is captured 2. Add/update project documentation 3. Link new notes to project README

When Learning Technologies

1. Create note in technologies/ 2. Link to projects that use it 3. Add code snippets as needed

For Ideas and Experiments

1. Start in ideas/ 2. Move to projects/ when starting implementation 3. Archive if abandoned

Additional Resources

Reference Files

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

Configuration

• Config: ~/.claude/obsidian-vault.json
• Vault path: ~/guerra_vault

Frontmatter Specification

This document defines the YAML frontmatter standard for all notes in the Obsidian vault.

Required Fields

title

• Type: String (quoted)
• Purpose: The display title of the note
• Rules:
• Must match or closely relate to the # Heading in the note body
• Use title case for readability
• Keep under 80 characters

Examples:

title: "Laravel Queue Configuration with Redis"
title: "API Rate Limiting Implementation"
title: "Code Reviewer Agent"

description

• Type: String (quoted)
• Purpose: Brief explanation of the note's content
• Rules:
• One to two sentences
• Provides context without reading the full note
• Useful for search results and previews

Examples:

description: "Step-by-step guide for configuring Laravel queues with Redis backend"
description: "Git commit implementing rate limiting for all public API endpoints"
description: "Specialized agent for reviewing code changes against project standards"

tags

• Type: Array of strings
• Purpose: Categorization and searchability
• Rules:
• Always include the category as a tag
• Use lowercase, hyphenated format
• Include relevant technologies, projects, and concepts
• Aim for 3-7 tags

Examples:

tags: [technologies, laravel, redis, queues, performance]
tags: [commit, my-saas-app, api, security, rate-limiting]
tags: [claude-code, agent, code-review, quality]

related

• Type: Array of wiki-links
• Purpose: Connect related notes for navigation
• Rules:
• Use Obsidian wiki-link format: [[path/to/note]]
• Omit the .md extension
• Prefer bidirectional links (both notes link to each other)
• Add links as connections become apparent

Examples:

related: []
related: [[technologies/redis]]
related: [[projects/my-saas-app/README], [technologies/laravel-queues]]

created

• Type: Date (YYYY-MM-DD)
• Purpose: Track when the note was first created
• Rules:
• Set once, never change
• Use ISO 8601 date format

Example:

created: 2026-01-27

updated

• Type: Date (YYYY-MM-DD)
• Purpose: Track when the note was last modified
• Rules:
• Update whenever content changes
• Scripts update this automatically
• Use ISO 8601 date format

Example:

updated: 2026-01-27

Optional Fields

archived_from

• Type: String (path)
• Purpose: Track original location when archived
• Rules:
• Added automatically by archive command
• Removed when restored

Example:

archived_from: technologies

source

• Type: String
• Purpose: Track where the note came from
• Values: claude-code, manual, imported

Example:

source: claude-code

status

• Type: String
• Purpose: Track note completion state
• Values: draft, active, archived, outdated

Example:

status: active

Complete Example

---
title: "Implementing API Rate Limiting with Redis"
description: "Complete guide to setting up rate limiting for Laravel APIs using Redis as the backend store"
tags: [technologies, laravel, redis, api, rate-limiting, security]
related: [[projects/my-saas-app/README], [technologies/redis-caching]]
created: 2026-01-27
updated: 2026-01-27
---

Validation Rules

1. All required fields must be present 2. Dates must be valid YYYY-MM-DD format 3. Tags must be an array (even if empty: `[]`) 4. Related must be an array (even if empty: `[]`) 5. Strings with special characters must be quoted

Scripts

The plugin's scripts automatically:

• Add frontmatter to new notes
• Update the updated field on changes
• Validate frontmatter structure
• Add/modify archived_from on archive/restore