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 headingdescription: One sentence explaining the contenttags: Always include the category as a tagrelated: Wiki-link format, add related notes when relevantcreated: Set once when createdupdated: 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
1---2name: vault-management3description: This skill should be used when the user asks to "manage notes", "update vault", "add to obsidian", "document in vault", "search my notes", "find related notes", or when working with Obsidian vault files. Also triggers when discussing knowledge management, note organization, or when Claude Code auto-captures commits, tasks, or component creation.4---5
6# Obsidian Vault Management
7
8Manage the Obsidian vault as a developer knowledge base and automatic work journal.
9
10## When to Use
11
12Activate this skill when:
13- User requests note operations (add, search, update, import, link, archive)
14- Working with project documentation that should be stored in the vault
15- Auto-capturing commits, tasks, or Claude Code components
16- User asks about their notes, documentation, or knowledge base
17- Organizing or finding information in the vault
18
19## Vault Structure
20
21```
22~/guerra_vault/
23├── projects/ # Project-specific documentation
24├── technologies/ # Technology knowledge (Laravel, React, etc.)
25├── claude-code/ # Claude Code components
26│ ├── agents/
27│ ├── hooks/
28│ ├── skills/
29│ └── tools/
30├── ideas/ # Feature ideas and experiments
31├── personal/ # Career and learning goals
32├── todo/ # Tasks and checklists
33├── references/ # Bookmarks, snippets, cheatsheets
34├── journal/ # Auto-captured events
35│ ├── commits/ # Git commit documentation
36│ ├── tasks/ # Completed task summaries
37│ └── creations/ # Component creation logs
38└── _archive/ # Archived notes
39```
40
41## Frontmatter Standard
42
43All notes MUST include this YAML frontmatter:
44
45```yaml
46---
47title: "Note Title"
48description: "Brief description of the content"
49tags: [tag1, tag2, category]
50related: [[path/to/related-note]]
51created: YYYY-MM-DD
52updated: YYYY-MM-DD
53---
54```
55
56**Rules:**
57- `title`: Descriptive, matches the main heading
58- `description`: One sentence explaining the content
59- `tags`: Always include the category as a tag
60- `related`: Wiki-link format, add related notes when relevant
61- `created`: Set once when created
62- `updated`: Update whenever the note changes
63
64## Available Commands
65
66| Command | Purpose |
67|---------|---------|
68| `/obsidian-vault:init` | Set up vault configuration and structure |
69| `/obsidian-vault:add <category> <title>` | Create a new note |
70| `/obsidian-vault:search <query>` | Find notes by title, content, or tags |
71| `/obsidian-vault:update <note>` | Edit note frontmatter or append content |
72| `/obsidian-vault:import <file>` | Import external files with frontmatter |
73| `/obsidian-vault:list [category]` | List notes, optionally by category |
74| `/obsidian-vault:tags [--stats]` | View tags and usage statistics |
75| `/obsidian-vault:link <note1> <note2>` | Create bidirectional related links |
76| `/obsidian-vault:archive <note>` | Move note to archive |
77
78## Auto-Capture Behavior
79
80The plugin automatically captures:
81
82### Git Commits
83- Creates `journal/commits/YYYY-MM-DD-<slug>.md`
84- Includes: commit message, date, project, branch, files changed
85- Placeholder sections for "What" and "Why" (fill in with context)
86
87### Task Completions
88- Creates `journal/tasks/YYYY-MM-DD-<slug>.md`
89- Captures subagent summaries
90- Includes: summary, what was done, decisions made
91
92### Claude Code Components
93- Creates `claude-code/<type>s/<name>.md`
94- Tracks: agents, hooks, skills, tools
95- Also logs to `journal/creations/`
96
97## Best Practices
98
99### Creating Notes
1001. Choose the appropriate category
1012. Use descriptive titles
1023. Add relevant tags immediately
1034. Link to related notes when obvious
104
105### Updating Notes
1061. Update the `updated` date (done automatically by scripts)
1072. Add new related links as connections emerge
1083. Keep descriptions current
109
110### Searching
1111. Start broad, narrow with `--title`, `--content`, or `--tag`
1122. Use `--category` to focus on specific areas
1133. Check related notes for additional context
114
115### Organization
1161. Use consistent naming within categories
1172. Archive rather than delete
1183. Maintain bidirectional links
119
120## Integration with Workflows
121
122### After Completing Features
123When finishing a feature or fix:
1241. Ensure commit is captured
1252. Add/update project documentation
1263. Link new notes to project README
127
128### When Learning Technologies
1291. Create note in `technologies/`
1302. Link to projects that use it
1313. Add code snippets as needed
132
133### For Ideas and Experiments
1341. Start in `ideas/`
1352. Move to `projects/` when starting implementation
1363. Archive if abandoned
137
138## Additional Resources
139
140### Reference Files
141- **`references/frontmatter-spec.md`** - Detailed frontmatter specification
142
143### Configuration
144- Config: `~/.claude/obsidian-vault.json`
145- Vault path: `~/guerra_vault`
mwguerra