jiahao-shao1 Obsidian Brain
A thinking partner skill that integrates Claude Code with your Obsidian vault.
Setup
If the vault doesn't exist yet, initialize it:
scripts/init-vault.sh ~/second-brain
The vault path defaults to ~/second-brain. Set VAULT_ROOT environment variable to override.
Core Principle: Dual-Zone Architecture
The vault has two zones. You MUST respect these boundaries:
Human Zone (read-only for AI, with exceptions)
Directories: notes/, projects/, tasks/, resources/, contexts/, daily/, people/
NEVER directly create or modify files in these directories — unless using scripts/human-write.sh for user-dictated content (tasks, notes). Human-write validates the path is in tasks/ or notes/ AND the content has source: human.
AI Zone (read-write for AI)
Directory: ops/ (and all subdirectories)
All AI-generated writes MUST go through scripts/safe-write.sh which validates paths via realpath. Direct file writes to the vault are forbidden.
Commands
CRUD Commands
/capture
Capture user's words as a draft. Run scripts/capture.sh.
Zone: Writes to ops/drafts/ only (via safe-write.sh).
Create Task
Create a task the user dictates. Run scripts/create-task.sh.
scripts/create-task.sh $VAULT_ROOT "Task title" --due 2026-04-01 --tags "work,urgent"
Zone: Writes to tasks/ only (via human-write.sh, source: human).
Create Note
Create a note the user dictates. Run scripts/create-note.sh.
scripts/create-note.sh $VAULT_ROOT "Note title" "Content text" --tags "ai" --links "concept-a,concept-b"
Zone: Writes to notes/ only (via human-write.sh, source: human).
Query Tasks
Query tasks with filtering. Run scripts/query-tasks.sh.
scripts/query-tasks.sh $VAULT_ROOT --undone --date today
scripts/query-tasks.sh $VAULT_ROOT --tag migration --project obsidian-brain
Zone: Reads only.
Complete Task
Mark a task as done. Run scripts/complete-task.sh.
scripts/complete-task.sh $VAULT_ROOT "task keyword"
Zone: Modifies done: field in tasks/ only.
Planning Commands
/context
Load project context from the vault. Read references/command-guide.md for details.
Zone: Reads both zones. Never writes.
/today
Morning planning. Read tasks, recent daily notes, and calendar.
Zone: Reads both zones. Output to terminal only — never writes.
Reflection Commands (Phase 2)
All reflection commands output to terminal only — they never write files.
/challenge
Stress-test a belief against your past writing.
scripts/analyze.sh $VAULT_ROOT --mode challenge --topic "some belief"
Zone: Reads human zone only.
/drift
Detect gaps between intended goals and actual activity.
scripts/analyze.sh $VAULT_ROOT --mode drift --days 60
Zone: Reads human zone only.
/emerge
Surface hidden ideas — ghost links and recurring themes.
scripts/analyze.sh $VAULT_ROOT --mode emerge --days 30
Zone: Reads human zone only.
/connect
Find hidden connections between two topics.
scripts/analyze.sh $VAULT_ROOT --mode connect --topics "topic-a,topic-b"
Zone: Reads human zone only.
Wikilink Queries
Use scripts/query-links.sh to find connected notes:
# Find what a note links to
scripts/query-links.sh $VAULT_ROOT outgoing "notes/idea-a.md"
# Find what links to a topic
scripts/query-links.sh $VAULT_ROOT backlinks "idea-a"
# Backlinks from human zone only (for reflection commands)
scripts/query-links.sh $VAULT_ROOT backlinks "idea-a" --human-only
Schema Reference
See references/vault-schema.md for frontmatter conventions, zone rules, and wikilink strategy.
See references/command-guide.md for detailed command documentation.