Vault (Obsidian Notes)
Location: ~/Documents/Notes/
Principles
- Obsidian vault for documents - Detailed notes, task logs, project context
- Unix tools for fast search - ripgrep (rg), fd, or mdfind for finding content efficiently
- WikiLinks for connections - Build traversable knowledge graph
- ALWAYS: New tasks should be in an
open state
Templates
Templates are in the skill directory, not the notes directory:
.claude/skills/vault/templates/knowledge-note.md - For knowledge notes.claude/skills/vault/templates/task.md - For new tasks
Bash Commands
# List in-progress tasks
rg --type md -l "^status:\s*in-progress" ~/Documents/Notes/Projects/*/Tasks
# Find project directory (handles YYYY[-MM] prefix)
fd -t d -d 1 -i "<project>" ~/Documents/Notes/Projects
# List project task files
fd -e md . ~/Documents/Notes/Projects/*<project>*/Tasks
# Find files by name
fd -e md -i "<name>" ~/Documents/Notes
# Recently modified (last 7 days)
fd -e md --changed-within 7d ~/Documents/Notes
# Find with Spotlight index
mdfind -interpret -onlyin ~/Documents/Notes "<concept>"
Timestamps
Always use real timestamps, never placeholders:
# For task filename: YYYY-MM-DD HHMMSS
date +"%Y-%m-%d %H%M%S"
# For log entry header: YYYY-MM-DD HH:MM
date +"%Y-%m-%d %H:%M"
# For frontmatter (ISO-8601)
date -Iseconds
Task File Path
~/Documents/Notes/Projects/<YYYY[-MM] Project>/Tasks/<YYYY-MM-DD HHMMSS> <Title>.md
Linking Strategy
Link if it improves the note, not just because it matches a term.
What to search for
| Search for |
Example (if writing about "Unison abilities") |
| Direct terms |
"abilities", "Unison abilities" |
| Parent concepts |
"effect handlers", "functional programming" |
| Sibling techniques |
"monads", "algebraic effects" |
| Tools/tech used |
"UCM", "Jit" |
Linking workflow
- Semantic discovery —
mdfind -interpret for related concepts
- Backlinks —
rg "\[\[<concept>" to find what links to your topics
- Tags overlap —
rg "^ - <tag>$" for notes sharing tags
- Add discovered notes as WikiLinks using breadcrumb pattern:
[[Parent]] | [[Related]]
Capture Heuristics
Worth capturing when:
| Marker |
Trigger |
| 📋 |
Principle applies across multiple contexts |
| 🤔 |
Caused debugging time or surprised me |
| ⚙️ |
Method that could save time later |
| 📎 |
Link to documentation or source |
| ☝️ |
Non-obvious choice with reasoning worth preserving |
Where to capture:
| Destination |
When |
| Existing note |
Discovery extends/refines an existing topic (search firs ) |
| New note |
Substantial, standalone, referenceable by other notes |
| Task log only |
One-off detail that won't generalise |
Note Locations
| Folder |
Purpose |
Examples |
Development/ |
Conceptual, non-project, topics, paradigms, architectural patterns |
"Functional Programming", "Test Driven Development", "Unison Web Application Patterns" |
HowTo/ |
Procedural guides, specific techniques, step-by-step instructions, unrelated to projects |
"Unison Testing with Effect Handlers", "TDD with Functional Programming" |
Tools/ |
Software tools and their usage |
"Claude", "Git", "HTMX", "Obsidian" |
Projects/<project>/ |
Project level knowledge in an appropriate note in the project folder |
|
Projects/<project>/Tasks/ |
Task logs only — never knowledge notes |
|
Projects/<project>/Glossary |
Glossary entries |
|
What NOT to include
- DO NOT include changed files
1---2name: vault3description: Read and write notes in the Obsidian vault. Use for task logs, knowledge capture, and building context.4---5
6# Vault (Obsidian Notes)
7
8Location: `~/Documents/Notes/`
9
10## Principles
11
121. **Obsidian vault for documents** - Detailed notes, task logs, project context
132. **Unix tools for fast search** - ripgrep (rg), fd, or mdfind for finding content efficiently
143. **WikiLinks for connections** - Build traversable knowledge graph
154. **ALWAYS**: New tasks should be in an `open` state
16
17## Templates
18
19Templates are in the skill directory, not the notes directory:
20
21- `.claude/skills/vault/templates/knowledge-note.md` - For knowledge notes
22- `.claude/skills/vault/templates/task.md` - For new tasks
23
24## Bash Commands
25
26```bash
27# List in-progress tasks
28rg --type md -l "^status:\s*in-progress" ~/Documents/Notes/Projects/*/Tasks
29
30# Find project directory (handles YYYY[-MM] prefix)
31fd -t d -d 1 -i "<project>" ~/Documents/Notes/Projects
32
33# List project task files
34fd -e md . ~/Documents/Notes/Projects/*<project>*/Tasks
35
36# Find files by name
37fd -e md -i "<name>" ~/Documents/Notes
38
39# Recently modified (last 7 days)
40fd -e md --changed-within 7d ~/Documents/Notes
41
42# Find with Spotlight index
43mdfind -interpret -onlyin ~/Documents/Notes "<concept>"
44```
45
46## Timestamps
47
48Always use real timestamps, never placeholders:
49
50```bash
51# For task filename: YYYY-MM-DD HHMMSS
52date +"%Y-%m-%d %H%M%S"
53
54# For log entry header: YYYY-MM-DD HH:MM
55date +"%Y-%m-%d %H:%M"
56
57# For frontmatter (ISO-8601)
58date -Iseconds
59```
60
61## Task File Path
62
63`~/Documents/Notes/Projects/<YYYY[-MM] Project>/Tasks/<YYYY-MM-DD HHMMSS> <Title>.md`
64
65## Linking Strategy
66
67> Link if it improves the note, not just because it matches a term.
68
69### What to search for
70
71| Search for | Example (if writing about "Unison abilities") |
72|------------|-----------------------------------------------|
73| Direct terms | "abilities", "Unison abilities" |
74| Parent concepts | "effect handlers", "functional programming" |
75| Sibling techniques | "monads", "algebraic effects" |
76| Tools/tech used | "UCM", "Jit" |
77
78### Linking workflow
79
801. **Semantic discovery** — `mdfind -interpret` for related concepts
812. **Backlinks** — `rg "\[\[<concept>"` to find what links to your topics
823. **Tags overlap** — `rg "^ - <tag>$"` for notes sharing tags
834. Add discovered notes as WikiLinks using breadcrumb pattern: `[[Parent]] | [[Related]]`
84
85## Capture Heuristics
86
87**Worth capturing when:**
88
89| Marker | Trigger |
90|--------|---------|
91| 📋 | Principle applies across multiple contexts |
92| 🤔 | Caused debugging time or surprised me |
93| ⚙️ | Method that could save time later |
94| 📎 | Link to documentation or source |
95| ☝️ | Non-obvious choice with reasoning worth preserving |
96
97**Where to capture:**
98
99| Destination | When |
100|-------------|------|
101| **Existing note** | Discovery extends/refines an existing topic (search firs ) |
102| **New note** | Substantial, standalone, referenceable by other notes |
103| **Task log only** | One-off detail that won't generalise |
104
105## Note Locations
106
107| Folder | Purpose | Examples |
108|--------|---------|----------|
109| `Development/` | Conceptual, non-project, topics, paradigms, architectural patterns | "Functional Programming", "Test Driven Development", "Unison Web Application Patterns" |
110| `HowTo/` | Procedural guides, specific techniques, step-by-step instructions, unrelated to projects | "Unison Testing with Effect Handlers", "TDD with Functional Programming" |
111| `Tools/` | Software tools and their usage | "Claude", "Git", "HTMX", "Obsidian" |
112| `Projects/<project>/` | Project level knowledge in an appropriate note in the project folder | |
113| `Projects/<project>/Tasks/` | Task logs only — never knowledge notes | |
114| `Projects/<project>/Glossary` | Glossary entries | |
115
116
117## What NOT to include
118
119- **DO NOT** include changed files
majiayu000