Obsidian Second Brain
Claude operates your Obsidian vault as a self-rewriting knowledge base. An evolution of Karpathy's LLM Wiki pattern: sources rewrite existing pages instead of just appending, contradictions reconcile automatically, and scheduled agents maintain the vault while you sleep.
Everything worth remembering gets saved. Every update propagates everywhere it belongs.
Quick Start
0. Choose vault access method (in order of preference)
Try these methods in order. Use the first one available:
Method 0 - SessionStart hook (if configured):
If hooks/load_vault_context.py is wired as a SessionStart hook in ~/.claude/settings.json, _CLAUDE.md is injected into context automatically at session start. Skip step 1 below.
To wire it: bash scripts/setup.sh "/path/to/vault" or run /obsidian-setup.
Method A - Direct filesystem (default, always works):
Use standard file tools (Read, Write, Edit, Glob) against the vault path. The vault is plain markdown, so every operation in this skill works this way with no setup. This is the normal path in Claude Code - the commands below use these tools directly.
Method B - MCP server (optional, mainly for non-Claude-Code clients):
This repo ships its own MCP server at integrations/obsidian-mcp-server/ that exposes the vault as tools (obsidian_search, obsidian_read_note, obsidian_save_note, obsidian_capture, plus curator tools). It exists so other MCP clients - Hermes Agent, Claude Desktop, Cursor - can use the vault as a knowledge layer; in Claude Code itself, Method A is simpler and preferred. If those obsidian_* tools happen to be available in your client, you may use them instead of raw file tools. Setup lives in integrations/obsidian-mcp-server/README.md (it is uv run --no-project --with 'mcp<2' python .../server.py with OBSIDIAN_VAULT_PATH set, not an npx package). Since the bookkeeping change, every write through the server also validates the note, adds the index entry, appends the operation-log line, and runs OBSIDIAN_POST_WRITE_CMD when set - see integrations/obsidian-mcp-server/README.md, "Bookkeeping after writes".
1. First time in a vault → read _CLAUDE.md
Before doing anything in a vault, check if _CLAUDE.md exists at the vault root and read it:
Read <vault>/_CLAUDE.md
If it exists: follow its rules exactly - they override the defaults in this skill. Where _CLAUDE.md is silent, fall back to the defaults below.
If it doesn't exist: use the defaults in this skill, then offer to create one.
If the SessionStart hook is active, _CLAUDE.md is already in context - skip this step.
2. First time with a new user → run discovery
Glob <vault>/**/*.md
Scan the structure to understand: folder names, template locations, naming conventions, frontmatter patterns. Then read 2-3 existing notes to calibrate writing style before creating anything new.
3. Bootstrap a new vault
If the user has no vault yet, run:
# One-line install + bootstrap (asks 3 questions: vault path, your name, preset)
curl -sL https://raw.githubusercontent.com/eugeniughelbur/obsidian-second-brain/main/scripts/quick-install.sh | bash
# Or manual:
python scripts/bootstrap_vault.py --path ~/path/to/vault --name "Your Name"
# With a preset:
python scripts/bootstrap_vault.py --path ~/my-vault --name "Your Name" --preset executive
python scripts/bootstrap_vault.py --path ~/my-vault --name "Your Name" --preset builder
python scripts/bootstrap_vault.py --path ~/my-vault --name "Your Name" --preset creator
python scripts/bootstrap_vault.py --path ~/my-vault --name "Your Name" --preset researcher
# With assistant mode (maintaining vault for someone else):
python scripts/bootstrap_vault.py --path ~/my-vault --name "Your Name" --mode assistant --subject "Boss Name"
Then just point the skill at the new vault path (Method A above). If you use the optional bundled MCP server, set OBSIDIAN_VAULT_PATH to the new path and restart the client.
Presets customize the vault for different use cases:
executive - Decisions, people, meetings, strategic planning. Kanban: OKRs, Quarterly, Weekly.
builder - Projects, dev logs, architecture decisions, debugging. Kanban: Backlog, Sprint, Done.
creator - Content calendar, ideas pipeline, audience notes, publishing. Kanban: Ideas, Drafts, Published.
researcher - Sources, literature notes, hypotheses, methodology. Kanban: Reading, Processing, Synthesized.
Default (no preset) gives a general-purpose vault. All presets use wiki-style by default.
Assistant mode creates a _CLAUDE.md configured for operating a vault on behalf of someone else. See references/claude-md-assistant-template.md.
See references/vault-schema.md for full structural details.
Core Operating Principles
AI-first vault rule (applies to every note)
The vault is designed for future agent to read and reason over, not for human review. Every note Claude writes - across all 46 commands - must follow references/ai-first-rules.md:
- Self-contained context - each note explains itself; don't rely on backlinks alone
- "For future agent" preamble - 2-3 sentence summary so any compatible agent can decide relevance in 10 seconds
- Rich, consistent frontmatter -
type, date, tags, ai-first: true, plus type-specific fields (see ai-first-rules.md for schemas per note type)
- Recency markers per claim - "Mem0 raised $24M (as of 2026-04, mem0.ai)" so future agent knows what to verify
- Sources preserved verbatim - every external claim has its source URL inline
- Cross-links mandatory - every person/project/idea/decision uses
[[wikilinks]]
- Confidence levels -
stated | high | medium | speculation where applicable
This rule lives in _CLAUDE.md Section 0 of every vault using this skill, and in references/ai-first-rules.md (the canonical specification with frontmatter schemas + preamble templates per note type). That path is relative to the install root, which is load-bearing: if it does not resolve from your working directory, search upward for it, and if you still cannot read it, say so before writing rather than producing a note that silently skips the rule. The seven requirements above are the floor and apply whether or not the spec is reachable.
Never create in isolation
Every write operation must ask: where else does this belong?
| You create/update... |
Also update... |
| A new project note |
Kanban board (add to Backlog), today's daily note (link it) |
| A task completed |
Kanban board (move to Done), project note (log it), daily note |
| A person note |
Daily note (mention interaction), People index if it exists |
| A dev log |
Daily note (link it), project note (Recent Activity) |
| A deal update |
Side Biz / Deals kanban, Dashboard totals |
| A decision made |
Project note (Key Decisions), daily note |
| A mention/shoutout |
Mentions Log, person's note, daily note |
| A hook, contrarian angle, or content idea |
social-media/ideas.md (if folder exists) |
| A specific reusable number or stat |
social-media/data-points.md (if folder exists) |
| An external post that performed well + why |
social-media/swipe-file.md (if folder exists) |
| Research findings worth keeping |
social-media/research/YYYY-MM-DD - topic.md (if folder exists) |
| Any vault write |
operation log (Logs/YYYY-MM-DD.md if Logs/ exists, else log.md), index.md (update if new note created) |
Always propagate. Never create a single orphaned note.
Bi-temporal facts - never overwrite, always append
When a fact changes (role, company, status, location, tool), NEVER delete the old value. Add a new entry to the timeline: frontmatter array with both event time AND transaction time:
timeline:
- fact: "CTO at Currentscale Labs"
from: 2024-01-01 # event time: when it was true
until: 2026-04-07
learned: 2026-02-23 # transaction time: when the vault learned it
source: "[[2026-02-23]]" # where from
- fact: "Architect at Currentscale Labs"
from: 2026-04-07
until: present
learned: 2026-04-07
source: "[[2026-04-07]]"
Top-level fields (role:, status:, company:) always reflect the CURRENT state. The timeline: preserves the full history with provenance.
This enables:
- Historical queries ("who was my manager in February?")
- Reflective thinking ("you believed X on Tuesday, then ingested Y on Wednesday and shifted to Z")
- Smart reconciliation (different facts at different times = not a contradiction)
- Full audit trail (when did the vault learn each fact, from what source?)
CRITICAL_FACTS.md - always loaded
A tiny file (~120 tokens) loaded alongside SOUL.md at L0 in every session. Contains facts needed in every conversation:
- Timezone
- Current manager
- Current location
- Current company and role
- Any other fact that's true RIGHT NOW and relevant to every interaction
Update this file whenever a critical fact changes. Keep it under 150 tokens.
Raw is immutable
In wiki-style vaults, the raw/ folder contains original sources (articles, transcripts, PDFs). Claude reads these but NEVER modifies them. They are the source of truth. If a wiki page gets corrupted, re-derive it from the raw source. When ingesting, always save the original to raw/ and the derived pages to wiki/.
Maintain index.md and log.md
Two structural files that keep the vault navigable and auditable:
index.md - A catalog of all vault pages organized by category. Claude reads this FIRST when navigating the vault instead of searching - faster and cheaper on tokens. Update it whenever a new note is created or deleted. Format: - [[Note Name]] - brief description grouped under folder headings.
log.md - An append-only chronological log of every vault operation. Every save, ingest, health check, and structural change gets a timestamped entry. Never delete or rewrite entries - only append. Format: ## [YYYY-MM-DD] action | Description
Per-day operation logs (modernized vaults)
Vaults initialized with /obsidian-init (v0.9+) use a split log structure instead of a monolithic log.md:
Logs/YYYY-MM-DD.md - one file per day, append-only. Format: **HH:MM** - action | description
log.md at vault root - pointer file only. Never write entries here; it explains the per-day structure and ships the entry template.
To migrate an existing monolithic log.md: run python scripts/migrate_log.py --vault <path>.
To refresh the stats block in index.md after bulk writes: run python scripts/vault_stats.py --vault <path>.
When writing operation log entries, check whether the vault uses the old (log.md) or new (Logs/YYYY-MM-DD.md) structure and write to the correct location.
The vault is a living system
The vault is not a filing cabinet. It is a living knowledge base that rewrites itself with every input. When new information enters:
- Existing pages get REWRITTEN with new context, not just appended to
- Contradictions between old and new claims get resolved or explicitly documented
- New patterns across multiple sources trigger automatic synthesis pages
- Stale claims get replaced with current information, with history preserved
The vault after an ingest should be DIFFERENT - not just bigger. If pages that existed before aren't smarter, more connected, and more current, the ingest wasn't deep enough.
Two-Output Rule
Every interaction that produces insight must generate two outputs:
- The answer - what the user sees in the conversation
- A vault update - the insight filed back into the relevant note(s)
This applies to all thinking tools and any query where Claude synthesizes information from the vault.
Synthesis Hook
When Claude notices a pattern during any operation (ingest, query, challenge, emerge), it should automatically create a synthesis page in wiki/concepts/. Patterns include:
- The same concept appearing in 3+ unrelated sources
- A claim being reinforced by multiple independent sources
- A trend emerging across time-sequenced notes
- Two entities sharing unexpected connections
Synthesis pages are the vault thinking for itself - connecting dots the user hasn't connected yet.
Reconciliation
The vault should never contain two pages that disagree without knowing they disagree. When contradictions are found (during ingest, health checks, or queries), either:
- Resolve them: rewrite the outdated page, preserve history
- Document them: create an explicit conflict page marked as an open question
Use /obsidian-reconcile for vault-wide truth maintenance.
Proactive save reminders
Unsaved conversations are lost knowledge. Claude should proactively remind the user to save:
- After 10+ exchanges: suggest "Want me to run /obsidian-save before we continue?"
- When the user signals wrap-up (e.g., "ok", "thanks", "done", "bye", "that's it"): suggest "Before you go - want me to /obsidian-save this conversation?"
- When a logical work block completes (feature shipped, decision made, problem solved): suggest saving
- Never skip the reminder. This is especially critical on Claude Desktop where there's no background agent.
Search before creating
Before creating any new note, search for an existing one:
search(query="keyword from title")
Duplicate notes are vault rot. Merge or update instead of creating new.
Never claim absence from memory, never fabricate
Two failure modes corrupt the vault silently:
- False absence (most common): never say "no note exists" or create a note on the assumption none exists without searching exhaustively first - by every plausible name, alias, and folder, listing and grepping, not from memory. When in doubt, over-include and label the uncertainty.
- Fabrication: never invent facts, entities, rates, dates, or relationships that were not actually stated. Mark unknowns as
TBD; an empty section is correct when nothing was said. External claims carry a source URL + recency marker; inferences carry a confidence level.
See the anti-fabrication and search-completeness hard rules in references/ai-first-rules.md.
Match the vault's voice
Read existing notes in the same folder before writing new ones.
Match: frontmatter schema, heading style, list formatting, tone, emoji usage (or lack of it).
Never introduce new conventions - extend what's already there.
Frontmatter is mandatory
Every note gets frontmatter. At minimum:
---
date: 2026-03-24
tags:
- <note-type>
---
See references/vault-schema.md for full frontmatter specs by note type.
Write Rules
See references/write-rules.md for the complete guide. Summary:
- Links: Use
[[Note Name]] for internal links. Always link to people, projects, and jobs mentioned in a note.
- Dates: ISO format (
YYYY-MM-DD) in frontmatter. Human format (March 24) in body text.
- Naming:
YYYY-MM-DD - Title.md for dated notes. Title.md for evergreen notes. No special characters except the ASCII hyphen -. Never an em dash (U+2014) or en dash (U+2013) in a filename: link matching compares stems literally, so 2026-07-26 - Title.md will not resolve a [[2026-07-26 - Title]] link, producing an orphan and a dangling link in the same write. The write-time validator checks file CONTENT, not filenames, so nothing catches this for you.
- Status values:
active / planning / completed / archived / on-hold for projects. in-progress / done / waiting for tasks.
- Kanban: Items follow the format
- [ ] 🔴 **Title** · @{YYYY-MM-DD}\n\tDescription [[Link]]
The _CLAUDE.md File
This is the most important concept in this skill.
_CLAUDE.md lives at the vault root and persists Claude's operating rules across every session and every surface (Claude Desktop, Claude Code, VS Code, terminal). Without it, Claude has to re-learn your vault conventions every conversation.
Precedence rule: _CLAUDE.md wins on all vault-specific rules (folder names, naming conventions, frontmatter fields, auto-save behavior, private folders). The defaults in this skill file apply only where _CLAUDE.md is silent. Never let skill defaults override an explicit _CLAUDE.md rule.
What it contains:
- Your vault's folder map and what each folder is for
- Frontmatter schemas for your specific note types
- Naming conventions you use
- What to auto-save vs. what to ask first
- People and projects that need special handling
- Links to key files (boards, dashboard, templates)
To generate a _CLAUDE.md for an existing vault, run vault discovery then use the template in references/claude-md-template.md.
To install it: write the file to the vault root. Every Claude session that starts in that vault should read it first.
Common Operations
Save info from conversation
When a conversation produces something vault-worthy:
- Identify the note type (decision → project note, person met → People/, task → board + Tasks/, etc.)
- Check if a relevant note already exists
- Write or update - always frontmatter-first
- Propagate to boards, daily note, linked notes
Create today's daily note
date = today in YYYY-MM-DD format
path = Daily/{date}.md
Read Templates/Daily Note.md, fill in the date fields, create the file.
Then scan recent conversation for anything worth logging in today's sections.
Log a dev session
Read Templates/Dev Log.md. Fill: date, project name, what was worked on, problems solved, decisions made, next steps.
Save to Dev Logs/YYYY-MM-DD - Project Name.md.
Link from project note's Recent Activity section and today's daily note.
Update a kanban board
Boards use the kanban-plugin: board frontmatter.
Columns are ## Column Name headers.
Items are - [ ] **Title** · @{due-date}\n\tDescription [[Links]]
Completed items move to the ## ✅ Done column with a strikethrough: - [x] ~~**Title**~~ ✅ Date
Run vault health check
uv run --directory "SKILL_ROOT" scripts/vault_health.py --path ~/path/to/vault
Reports: duplicate notes, orphaned files (no incoming links), stale tasks (overdue), empty folders, broken links, notes missing frontmatter.
Proactively suggest running this when the user says the vault feels messy, notes are hard to find, they mention duplicates, or they haven't mentioned a health check in a long time. Offer: "Want me to run a vault health check?"
Commands
These slash commands can be used in any Claude surface. Each one is smart - it reads context, searches before writing, and propagates everywhere changes belong.
Name matching: If a name argument has a typo or is approximate, search the vault for the closest match, show what was found, and confirm with the user before proceeding. Never silently create a note with a misspelled name.
Command selection: the longest matching trigger wins. Several triggers are prefixes of longer, more specific ones, so a shorter match is not evidence that the shorter command is the right one. Always check whether a longer trigger also matches before choosing.
The five collisions that exist today, with the correct routing:
| The user says |
Route to |
Not to |
Why it matters |
| "remind me every month...", "track a recurring..." |
/obsidian-recurring |
/obsidian-task |
A one-shot card never recurs, which is the whole point of the request |
| "save this idea", "capture this" |
/obsidian-capture |
/obsidian-save |
One small idea note, not a multi-subagent sweep across people, projects, tasks, decisions and boards |
| "save this person", "remember this person" |
/obsidian-person |
/obsidian-save |
A person note, not a full conversation sweep |
| "synthesize what I know about X" |
/vault-deep-synthesis |
/obsidian-synthesize |
One topic cross-referenced, not a whole-vault pattern scan |
| "find unnamed patterns" |
/obsidian-emerge |
/obsidian-synthesize |
Surfaces patterns for the user, does not write synthesis pages unasked |
When two commands still look equally plausible after applying the rule, ask which one rather than guessing - the blast radii differ enormously, and /obsidian-save in particular writes across many files.
/obsidian-save
The master save command. Reads the entire conversation and extracts everything worth preserving.
Steps:
- Scan the conversation and identify all vault-worthy items: decisions, tasks, people mentioned, projects started, ideas, learnings, deals, mentions/shoutouts
- Group items by type: people, projects, tasks, decisions, ideas, deals
- Spawn parallel subagents - one per group - so all note types are handled simultaneously:
- People agent: search for each person, create or update notes, log interactions
- Projects agent: search for each project, create or update notes
- Tasks agent: parse tasks, add to the right kanban columns
- Decisions agent: find relevant project notes, append to Key Decisions sections
- Ideas agent: search Ideas/ for related notes, create or append
- After all agents complete: update today's daily note with links to everything saved
- Report back: a clean list of what was saved and where
Do not ask for guidance on where to save things - infer it. Only ask if something is genuinely ambiguous (e.g. a person mentioned with no context on who they are).
/obsidian-daily
Creates or updates today's daily note. Full steps in commands/obsidian-daily.md (the source of truth).
In short: resolves the daily folder per references/folder-map.md, creates today's note from the daily-note template if missing, then fills it from three inputs - the current conversation (tasks, people, decisions), the calendar (today's events when available), and the boards (due/overdue kanban items) - plus a short overnight-changes line when scheduled agents ran. Existing notes are injected into, never overwritten. Returns the note path.
/obsidian-calendar <mode>
One calendar command with four modes. Claude Code only (needs the Google Calendar MCP). The first word selects the mode; a bare range word defaults to agenda; no argument at all defaults to agenda today.
agenda [range] - reads the calendar and writes a re-derivable AI-first snapshot to wiki/agenda/ (type: agenda-snapshot). Range: today, tomorrow, week, next-week, a date, or a range. Cross-links attendees to [[Person]] notes; flags conflicts, 3+ back-to-back stretches, working-hours focus blocks, and externally-organized events. Read-only on the calendar; Google Calendar stays the source of truth.
reconcile [window] - flags commitments the vault implies (project next_actions, due tasks, dated commitments in daily notes, fixed dates in CRITICAL_FACTS.md) that are NOT on the calendar, plus events with no vault context. Flag only - never adds or changes events.
meeting [selector] - turns an event (last, next, today, event-id:<id>, or fuzzy title) into a type: meeting note in wiki/meetings/ with metadata pre-filled and empty Notes / Decisions / Action items sections (never fabricate meeting content). Cross-links attendees, backlinks any task whose calendar-event-id matches.
schedule <args> - the only mode that writes to the calendar. Standalone ("<title>" <when> <duration>), from a task (task:<path>), or suggest-a-time (task:<...> suggest:<window>). Resolves attendee emails from person notes (never guesses), conflict-checks before writing, requests a Meet link when participants span domains, and writes calendar-event-id back into the task so a re-run reschedules rather than duplicating.
(Consolidated from the former /obsidian-agenda, /obsidian-reconcile-style calendar check, /obsidian-meeting, and /obsidian-schedule - same behaviors, one entry point. The natural-language triggers for all four still route here.)
/obsidian-recurring
Tracks a recurring obligation (payment, filing, ops) with a cadence and a computed next-due date.
State the obligation and cadence (e.g. "pay social benefits, monthly day 20"). Searches for an existing note first, then builds a type: recurring-task note with What / Cadence / Blockers / History sections and frontmatter (cadence, owner, blocker, next-due, optional amount). Adds a board card for the next occurrence; on each completion, appends a History row and advances next-due. Fills the gap that /obsidian-task (one-shot) leaves.
/obsidian-log
Logs a work or dev session to the vault. Full steps in commands/obsidian-log.md (the source of truth).
In short: infers the project from conversation, uses the dev-log template when one exists (inline structure otherwise), and saves YYYY-MM-DD - Project Name.md to the dev-log folder resolved per references/folder-map.md (wiki-style wiki/logs/, Obsidian-style Dev Logs/). Links are injected into the project note's Recent Activity and today's daily note.
/obsidian-task [description]
Adds a task to the vault and the right kanban board.
Steps:
- Parse the task from the argument or from recent conversation context if no argument given
- Infer: priority (🔴/🟡/🟢), due date, linked project, linked person
- Search for the right kanban board - use
_CLAUDE.md board list or search Boards/
- Add the task card to the correct column (
📋 This Week or 📥 Backlog depending on due date)
- Create a task note in
Tasks/ if the task is substantial (more than a one-liner)
- Link the task from the relevant project note and today's daily note
/obsidian-person [name]
Creates or updates a person note.
Steps:
- Search the vault for an existing note matching the name (fuzzy - handle typos and partial names)
- If found: confirm with user, then update with new info from conversation
- If not found: create
People/Full Name.md with full frontmatter schema
- Fill in everything inferable from the conversation: role, company, context, relationship strength, last interaction date
- Log the interaction in today's daily note
- If a People index file exists, add or update the entry there
/obsidian-capture [optional: idea text]
Quick idea capture with zero friction.
Steps:
- Take the argument as the idea, or pull the most recent idea/thought from the conversation
- Search
Ideas/ for a related existing note - if found, append to it
- If new: create
Ideas/Title.md with minimal frontmatter (date, tags: [idea])
- Write the idea with any supporting context from the conversation
- Add a brief mention in today's daily note under an Ideas or Captures section
/obsidian-catchup [today|week|all]
Process what the Telegram journal bot captured on the go. The laptop-side companion to the integrations/telegram-journal/ bot, which captures voice/text/image/PDF/link from your phone and appends each to a catchup.md queue in the vault.
Steps:
- Read
catchup.md in the vault root - each unchecked - [ ] line is an unprocessed capture (date time | kind | summary | -> where).
- Collect the unchecked items, applying the timeframe filter (
today / week / all, default all). If none, say so and stop.
- Show them grouped by age (Today / This week / Older), flagging stale ones.
- Process WITH the user (not autonomously): open each linked note, propose integrate (fold into the right note per the AI-first rule) / keep / discard, confirm, then write.
- Check the item off (
- [x] + processed date); never delete queue history.
Pull, not push: nothing is processed until you run this, so nothing surprises you. The phone is for fast dumb capture; this is where it becomes integrated knowledge.
/obsidian-find [query]
Smart vault search.
Steps:
- Run
search(query="...") with the provided query
- Also try variations if results are sparse (synonyms, related terms)
- Return results with context: note title, folder, a relevant excerpt, and what type of note it is
- If results are ambiguous, group them by type (people, projects, tasks, etc.)
- Offer to open, update, or link any of the found notes
Do not just return filenames - return enough context for the user to act.
/obsidian-recap [today|week|month]
Summarizes a time period from the vault.
Steps:
- Determine the date range from the argument (default:
week if not specified)
- List all daily notes in the range with
list_files_in_dir("Daily/")
- Spawn parallel subagents - one per daily note - to read and extract key points from each simultaneously
- Also spawn parallel agents to read dev logs and completed kanban tasks from the same period
- Synthesize all agent results: what was worked on, decisions made, people interacted with, tasks completed, ideas captured
- Present as a clean narrative summary - not a raw dump of note content
/obsidian-review
Generates a structured weekly or monthly review note. Full steps in commands/obsidian-review.md (the source of truth).
In short: reads the period's daily notes, dev logs, project changes, and completed board items; drafts from the review template when one exists (accomplishments, key decisions, people, learnings, carry-forward, plus the mandated "Suggested next week/month" section); saves YYYY-MM-DD - Weekly Review.md (or Monthly) to the reviews folder resolved per references/folder-map.md; links from the period's last daily note.
/obsidian-board [optional: board name]
Shows or updates a kanban board.
Steps:
- If a board name is given, search
Boards/ for it (fuzzy match)
- If no name given, list available boards and ask which one
- Read and display the current board state: columns, item counts, overdue items (past
@{date})
- Ask if the user wants to make updates - if yes, infer changes from conversation context
- Move completed items to ✅ Done with strikethrough, add new items in the right column
- Flag any items that are overdue or have been in the same column for more than a week
/obsidian-board-hygiene [optional: board name]
Bulk-triages a kanban board whose columns have gone stale. Where /obsidian-board only flags overdue items, this clears them.
Steps:
- Read
_CLAUDE.md for the boards folder and kanban convention (columns, @{date} format)
- Read the target board (fuzzy-match; if none given, list boards and ask), parse every open item, compute age vs today
- Group items into overdue (
@{date} past), stale (older than N days, default 14), and undated; show counts per column so the bloat is visible
- Propose ONE verdict per stale/overdue item with a one-line reason - done / reschedule / archive / keep - as a batch the user approves, edits, or overrides
- Apply approved verdicts in place (additive moves + strikethrough, never silent deletion), then report what moved and log it
/obsidian-project [name]
Creates or updates a project note.
Steps:
- Search the vault for an existing project matching the name (fuzzy - handle typos)
- If found: show what was found, confirm, then update with new info from conversation
- If not found: create
Projects/Project Name.md with full frontmatter schema (date, tags: [project], status: active, job)
- Fill in everything inferable from the conversation: description, goals, key people, current status
- Add a card to the relevant kanban board in the
📥 Backlog or 🔨 In Progress column
- Link from today's daily note
/obsidian-projects [optional: project name]
Live status overview across all tracked projects.
Reads _CLAUDE.md for the projects folder, then scans it for notes with type: project or a repo: field. For each project, spawns a parallel subagent that runs three checks: reads the vault note (status, last activity, next action, blockers), runs git log and git status if a repo: path is set, and looks for NOTES.md / TODO.md in the repo root. Merges the three into one status block (active / stalled / idle / blocked / archived inferred from activity recency), prints the full overview to the conversation ordered active-first, then injects a ## Last overview section into each project note.
If a project name argument is given, shows deep context for that one project only.
/obsidian-health
Runs a vault health check and summarizes findings.
Steps:
- Run:
uv run --directory "SKILL_ROOT" scripts/vault_health.py --path ~/path/to/vault --json
- Parse the JSON output and split findings into categories
- Spawn parallel subagents to handle each category simultaneously:
- Links agent: verify broken links, attempt to resolve them
- Duplicates agent: confirm duplicates are truly the same concept, not just similar names
- Taxonomy agent: only fires when
<vault>/_meta/taxonomy.md exists (format in references/taxonomy-format.md) - opt-in, zero findings without it. tag_synonym (a tag is a known synonym of a canonical tag) offers a per-note rename to the canonical form with confirmation; tag_not_in_taxonomy (a tag matches neither a canonical tag nor a synonym) is informational only, never auto-fixed
- Frontmatter agent: identify notes missing required fields by type
- Staleness agent: check overdue tasks and unfilled template syntax
- Orphans agent: check orphaned notes and empty folders
- Contradictions agent: scan Key Decisions and Knowledge/ for claims that conflict or are superseded
- Concept gaps agent: find terms mentioned 3+ times without a dedicated page
- Stale claims agent: flag Knowledge/ notes older than 6 months on fast-moving topics
- Freshness agent: run
python scripts/freshness_lint.py --path <vault> --json - enforces references/freshness-policy.md (every stored fact must be timeless, dated, or a pointer; fast facts carry an as of stamp or link to their home system)
- Typed-edge lint agent: run
python scripts/link_graph.py --path <vault> --lint - validates the relations: typed-edge graph (Rule 6 § Typed edges in references/ai-first-rules.md): contradiction cycles (critical), unknown types / dangling targets / self-edges (warning), missing inverse edges (info). Returns zero findings on vaults that use no typed edges yet
- Merge agent results and group by severity:
- 🔴 Critical: broken links, unfilled template syntax, contradictions, typed-edge contradiction cycles
- 🟡 Warning: duplicates, stale tasks, missing frontmatter, stale claims, concept gaps, typed-edge problems (unknown type, dangling target, self-edge), tag-synonym findings
- ⚪ Info: orphaned notes, empty folders, missing inverse edges, tags not in the taxonomy
- Present a clean summary with counts per category
- For safe fixes (missing frontmatter, obvious duplicates, creating pages for concept gaps), offer to fix them automatically
- For destructive fixes (archiving, merging, resolving contradictions), list them and ask for explicit confirmation before touching anything
- Append an operation-log entry with severity counts - if
Logs/ exists write the entry to Logs/YYYY-MM-DD.md, otherwise append to log.md (SKILL.md's own rule: the root log.md is a pointer file in v0.9+ vaults, never an entry target)
/obsidian-reindex
Refreshes the semantic search index and makes its coverage visible. Full steps in commands/obsidian-reindex.md (the source of truth).
In short: reads the vault path from _CLAUDE.md, reports the current index_coverage, runs the existing incremental semantic_search.py --build, and reports coverage again with the builder's new, cached, excluded, degraded, and dropped counts. A backend failure stops the flow and is shown to the user; it is never presented as a successful refresh. The command updates only .obsidian-semantic-index.json, not Markdown notes.
/obsidian-retrieval-eval [optional: N to generate | report]
Measures how well vault search actually finds the right note - so improving retrieval is a number, not a hunch.
Hybrid command backed by scripts/eval/retrieval_eval.py, which reuses the REAL search engine (integrations/obsidian-mcp-server/vault_ops.py, the term-frequency, title-weighted ranking behind /obsidian-find and the MCP connector). It bootstraps its own eval set from the vault (an LLM writes a question per sampled note, avoiding the note's title words so it tests retrieval not string-match; the note is the gold answer), then scores recall@1/3/5/10 and MRR and lists the failures - misses and notes buried below #3, naming which note wrongly ranked #1. Claude interprets the numbers, turns failures into ranked retrieval fixes (each a hypothesis to re-measure on the same cases), and optionally writes an AI-first baseline note. Generated cases hold private note paths and are gitignored. The first run on a 1,000+ note vault scored 0% recall@10 on paraphrased questions (long raw/ transcripts and log.md dominate term-frequency ranking) - proving the cheap structural fixes (exclude raw/, weight by type:) should be measured before reaching for a vector index.
/obsidian-merge <canonical> <retired> | --from-health
Merges two near-duplicate notes that /obsidian-health found and stopped at. Dry run by default; the retired note becomes a redirect, never a deletion.
Health is read-only by contract, so the merge was the manual step everyone skipped and the same pairs came back every run. scripts/merge_notes.py does the mechanical half; you compose the merged body, because deciding what actually contradicts between two notes is judgment.
Steps:
- Resolve the pair: two paths from the user (first survives, second retires; confirm if the richer note is the second), or
--from-health to list the 2-file duplicate groups from a live vault_health.check_duplicates() run. A group of 3+ is never auto-paired.
- Read both notes in full. Compose the merged body per
references/ai-first-rules.md: one ## For future agent preamble naming both originals, both provenance trails kept, real contradictions listed with dates rather than resolved, every still-relevant [[wikilink]] from both sides carried over. Write it to a scratch file.
- Dry run:
uv run --directory "SKILL_ROOT" scripts/merge_notes.py --path <vault> --canonical <a> --retire <b> --merged-body-file <scratch>. It prints the frontmatter conflicts (canonical wins, the retired value goes under merged_from:; list fields such as tags and aliases are unioned instead), the alias folded in, and the full text of both proposed notes. Show it verbatim.
- Ask for explicit confirmation, then re-run the identical command with
--apply. Dry run and apply share one compute_merge(), so what was previewed is what gets written.
- Report which note survived, which became
type: redirect (schema in references/ai-first-rules.md, Documented exceptions), the conflicts, and the contradictions the body documents. Log merge | <retired> -> <canonical> per the operation-log convention.
/obsidian-reconcile
Finds and resolves contradictions across the vault.
Steps:
- Read
index.md to understand the full vault landscape
- Spawn parallel subagents to find contradictions:
- Claims agent: scan
wiki/concepts/ and wiki/projects/ for conflicting factual claims
- Entity agent: scan
wiki/entities/ for outdated roles, companies, or descriptions
- Decisions agent: scan
wiki/decisions/ for reversed or superseded decisions never updated
- Source freshness agent: compare
raw/ dates against wiki/ pages for stale references
- For each contradiction, evaluate: which is newer, which i
…(truncated)
1---
2name: obsidian-second-brain
3description: >
4 Operate any Obsidian vault as a living, self-rewriting second brain (an evolution
5 of Karpathy's LLM Wiki pattern: sources rewrite existing pages, contradictions
6 reconcile automatically, scheduled agents maintain the vault while you sleep).
7 Use this skill whenever
8 the user asks Claude to read, write, update, search, or manage their Obsidian
9 vault - including saving notes from conversation, creating daily entries, updating
10 kanban boards, logging dev work, managing people notes, capturing decisions,
11 tracking deals, or maintaining any vault structure. Also triggers when the user
12 wants to bootstrap a new vault from scratch, run a vault health check, or drop
13 a _CLAUDE.md into their vault so all Claude surfaces share the same operating rules.
14 Includes a research toolkit (7 commands: /x-read, /x-pulse, /research, /research-deep,
15 /notebooklm, /youtube, /podcast) for AI-powered research via Grok, Perplexity, NotebookLM,
16 YouTube, and podcast feeds - findings save
17 to the vault automatically following the AI-first vault rule. Use proactively whenever
18 the conversation produces information worth preserving (decisions, people met, projects
19 started, tasks completed, lessons learned, research findings).
20metadata:
21 source: https://skillmd.com/skills/eugeniughelbur/obsidian-second-brain
22---
23
24# Obsidian Second Brain
25
26> Claude operates your Obsidian vault as a self-rewriting knowledge base. An evolution of [Karpathy's LLM Wiki pattern](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f): sources rewrite existing pages instead of just appending, contradictions reconcile automatically, and scheduled agents maintain the vault while you sleep.
27> Everything worth remembering gets saved. Every update propagates everywhere it belongs.
28
29---
30
31## Quick Start
32
33### 0. Choose vault access method (in order of preference)
34
35Try these methods in order. Use the first one available:
36
37**Method 0 - SessionStart hook (if configured):**
38If `hooks/load_vault_context.py` is wired as a SessionStart hook in `~/.claude/settings.json`, `_CLAUDE.md` is injected into context automatically at session start. Skip step 1 below.
39To wire it: `bash scripts/setup.sh "/path/to/vault"` or run `/obsidian-setup`.
40
41**Method A - Direct filesystem (default, always works):**
42Use standard file tools (Read, Write, Edit, Glob) against the vault path. The vault is plain markdown, so every operation in this skill works this way with no setup. This is the normal path in Claude Code - the commands below use these tools directly.
43
44**Method B - MCP server (optional, mainly for non-Claude-Code clients):**
45This repo ships its own MCP server at `integrations/obsidian-mcp-server/` that exposes the vault as tools (`obsidian_search`, `obsidian_read_note`, `obsidian_save_note`, `obsidian_capture`, plus curator tools). It exists so other MCP clients - Hermes Agent, Claude Desktop, Cursor - can use the vault as a knowledge layer; in Claude Code itself, Method A is simpler and preferred. If those `obsidian_*` tools happen to be available in your client, you may use them instead of raw file tools. Setup lives in `integrations/obsidian-mcp-server/README.md` (it is `uv run --no-project --with 'mcp<2' python .../server.py` with `OBSIDIAN_VAULT_PATH` set, not an `npx` package). Since the bookkeeping change, every write through the server also validates the note, adds the index entry, appends the operation-log line, and runs `OBSIDIAN_POST_WRITE_CMD` when set - see `integrations/obsidian-mcp-server/README.md`, "Bookkeeping after writes".
46
47### 1. First time in a vault → read `_CLAUDE.md`
48
49Before doing anything in a vault, check if `_CLAUDE.md` exists at the vault root and read it:
50
51```
52Read <vault>/_CLAUDE.md
53```
54
55If it exists: follow its rules exactly - they override the defaults in this skill. Where `_CLAUDE.md` is silent, fall back to the defaults below.
56If it doesn't exist: use the defaults in this skill, then offer to create one.
57
58If the SessionStart hook is active, `_CLAUDE.md` is already in context - skip this step.
59
60### 2. First time with a new user → run discovery
61
62```
63Glob <vault>/**/*.md
64```
65
66Scan the structure to understand: folder names, template locations, naming conventions, frontmatter patterns. Then read 2-3 existing notes to calibrate writing style before creating anything new.
67
68### 3. Bootstrap a new vault
69
70If the user has no vault yet, run:
71```bash
72# One-line install + bootstrap (asks 3 questions: vault path, your name, preset)
73curl -sL https://raw.githubusercontent.com/eugeniughelbur/obsidian-second-brain/main/scripts/quick-install.sh | bash
74
75# Or manual:
76python scripts/bootstrap_vault.py --path ~/path/to/vault --name "Your Name"
77
78# With a preset:
79python scripts/bootstrap_vault.py --path ~/my-vault --name "Your Name" --preset executive
80python scripts/bootstrap_vault.py --path ~/my-vault --name "Your Name" --preset builder
81python scripts/bootstrap_vault.py --path ~/my-vault --name "Your Name" --preset creator
82python scripts/bootstrap_vault.py --path ~/my-vault --name "Your Name" --preset researcher
83
84# With assistant mode (maintaining vault for someone else):
85python scripts/bootstrap_vault.py --path ~/my-vault --name "Your Name" --mode assistant --subject "Boss Name"
86```
87
88Then just point the skill at the new vault path (Method A above). If you use the optional bundled MCP server, set `OBSIDIAN_VAULT_PATH` to the new path and restart the client.
89
90**Presets** customize the vault for different use cases:
91- **`executive`** - Decisions, people, meetings, strategic planning. Kanban: OKRs, Quarterly, Weekly.
92- **`builder`** - Projects, dev logs, architecture decisions, debugging. Kanban: Backlog, Sprint, Done.
93- **`creator`** - Content calendar, ideas pipeline, audience notes, publishing. Kanban: Ideas, Drafts, Published.
94- **`researcher`** - Sources, literature notes, hypotheses, methodology. Kanban: Reading, Processing, Synthesized.
95
96Default (no preset) gives a general-purpose vault. All presets use wiki-style by default.
97
98**Assistant mode** creates a `_CLAUDE.md` configured for operating a vault on behalf of someone else. See `references/claude-md-assistant-template.md`.
99
100See `references/vault-schema.md` for full structural details.
101
102---
103
104## Core Operating Principles
105
106### AI-first vault rule (applies to every note)
107The vault is designed for **future agent** to read and reason over, not for human review. Every note Claude writes - across all 46 commands - must follow `references/ai-first-rules.md`:
108
1091. **Self-contained context** - each note explains itself; don't rely on backlinks alone
1102. **"For future agent" preamble** - 2-3 sentence summary so any compatible agent can decide relevance in 10 seconds
1113. **Rich, consistent frontmatter** - `type`, `date`, `tags`, `ai-first: true`, plus type-specific fields (see `ai-first-rules.md` for schemas per note type)
1124. **Recency markers per claim** - "Mem0 raised $24M (as of 2026-04, mem0.ai)" so future agent knows what to verify
1135. **Sources preserved verbatim** - every external claim has its source URL inline
1146. **Cross-links mandatory** - every person/project/idea/decision uses `[[wikilinks]]`
1157. **Confidence levels** - `stated | high | medium | speculation` where applicable
116
117This rule lives in `_CLAUDE.md` Section 0 of every vault using this skill, and in `references/ai-first-rules.md` (the canonical specification with frontmatter schemas + preamble templates per note type). That path is relative to the install root, which is load-bearing: if it does not resolve from your working directory, search upward for it, and if you still cannot read it, say so before writing rather than producing a note that silently skips the rule. The seven requirements above are the floor and apply whether or not the spec is reachable.
118
119### Never create in isolation
120Every write operation must ask: *where else does this belong?*
121
122| You create/update... | Also update... |
123|---|---|
124| A new project note | Kanban board (add to Backlog), today's daily note (link it) |
125| A task completed | Kanban board (move to Done), project note (log it), daily note |
126| A person note | Daily note (mention interaction), People index if it exists |
127| A dev log | Daily note (link it), project note (Recent Activity) |
128| A deal update | Side Biz / Deals kanban, Dashboard totals |
129| A decision made | Project note (Key Decisions), daily note |
130| A mention/shoutout | Mentions Log, person's note, daily note |
131| A hook, contrarian angle, or content idea | `social-media/ideas.md` (if folder exists) |
132| A specific reusable number or stat | `social-media/data-points.md` (if folder exists) |
133| An external post that performed well + why | `social-media/swipe-file.md` (if folder exists) |
134| Research findings worth keeping | `social-media/research/YYYY-MM-DD - topic.md` (if folder exists) |
135| Any vault write | operation log (`Logs/YYYY-MM-DD.md` if `Logs/` exists, else `log.md`), `index.md` (update if new note created) |
136
137Always propagate. Never create a single orphaned note.
138
139### Bi-temporal facts - never overwrite, always append
140When a fact changes (role, company, status, location, tool), NEVER delete the old value. Add a new entry to the `timeline:` frontmatter array with both event time AND transaction time:
141
142```yaml
143timeline:
144 - fact: "CTO at Currentscale Labs"
145 from: 2024-01-01 # event time: when it was true
146 until: 2026-04-07
147 learned: 2026-02-23 # transaction time: when the vault learned it
148 source: "[[2026-02-23]]" # where from
149 - fact: "Architect at Currentscale Labs"
150 from: 2026-04-07
151 until: present
152 learned: 2026-04-07
153 source: "[[2026-04-07]]"
154```
155
156Top-level fields (`role:`, `status:`, `company:`) always reflect the CURRENT state. The `timeline:` preserves the full history with provenance.
157
158This enables:
159- Historical queries ("who was my manager in February?")
160- Reflective thinking ("you believed X on Tuesday, then ingested Y on Wednesday and shifted to Z")
161- Smart reconciliation (different facts at different times = not a contradiction)
162- Full audit trail (when did the vault learn each fact, from what source?)
163
164### CRITICAL_FACTS.md - always loaded
165A tiny file (~120 tokens) loaded alongside `SOUL.md` at L0 in every session. Contains facts needed in every conversation:
166- Timezone
167- Current manager
168- Current location
169- Current company and role
170- Any other fact that's true RIGHT NOW and relevant to every interaction
171
172Update this file whenever a critical fact changes. Keep it under 150 tokens.
173
174### Raw is immutable
175In wiki-style vaults, the `raw/` folder contains original sources (articles, transcripts, PDFs). Claude reads these but NEVER modifies them. They are the source of truth. If a wiki page gets corrupted, re-derive it from the raw source. When ingesting, always save the original to `raw/` and the derived pages to `wiki/`.
176
177### Maintain `index.md` and `log.md`
178Two structural files that keep the vault navigable and auditable:
179
180- **`index.md`** - A catalog of all vault pages organized by category. Claude reads this FIRST when navigating the vault instead of searching - faster and cheaper on tokens. Update it whenever a new note is created or deleted. Format: `- [[Note Name]] - brief description` grouped under folder headings.
181
182- **`log.md`** - An append-only chronological log of every vault operation. Every save, ingest, health check, and structural change gets a timestamped entry. Never delete or rewrite entries - only append. Format: `## [YYYY-MM-DD] action | Description`
183
184### Per-day operation logs (modernized vaults)
185Vaults initialized with `/obsidian-init` (v0.9+) use a split log structure instead of a monolithic `log.md`:
186
187- **`Logs/YYYY-MM-DD.md`** - one file per day, append-only. Format: `**HH:MM** - action | description`
188- **`log.md` at vault root** - pointer file only. Never write entries here; it explains the per-day structure and ships the entry template.
189
190To migrate an existing monolithic `log.md`: run `python scripts/migrate_log.py --vault <path>`.
191To refresh the stats block in `index.md` after bulk writes: run `python scripts/vault_stats.py --vault <path>`.
192
193When writing operation log entries, check whether the vault uses the old (`log.md`) or new (`Logs/YYYY-MM-DD.md`) structure and write to the correct location.
194
195### The vault is a living system
196The vault is not a filing cabinet. It is a living knowledge base that rewrites itself with every input. When new information enters:
197- Existing pages get REWRITTEN with new context, not just appended to
198- Contradictions between old and new claims get resolved or explicitly documented
199- New patterns across multiple sources trigger automatic synthesis pages
200- Stale claims get replaced with current information, with history preserved
201
202The vault after an ingest should be DIFFERENT - not just bigger. If pages that existed before aren't smarter, more connected, and more current, the ingest wasn't deep enough.
203
204### Two-Output Rule
205Every interaction that produces insight must generate two outputs:
2061. **The answer** - what the user sees in the conversation
2072. **A vault update** - the insight filed back into the relevant note(s)
208
209This applies to all thinking tools and any query where Claude synthesizes information from the vault.
210
211### Synthesis Hook
212When Claude notices a pattern during any operation (ingest, query, challenge, emerge), it should automatically create a synthesis page in `wiki/concepts/`. Patterns include:
213- The same concept appearing in 3+ unrelated sources
214- A claim being reinforced by multiple independent sources
215- A trend emerging across time-sequenced notes
216- Two entities sharing unexpected connections
217
218Synthesis pages are the vault thinking for itself - connecting dots the user hasn't connected yet.
219
220### Reconciliation
221The vault should never contain two pages that disagree without knowing they disagree. When contradictions are found (during ingest, health checks, or queries), either:
222- Resolve them: rewrite the outdated page, preserve history
223- Document them: create an explicit conflict page marked as an open question
224
225Use `/obsidian-reconcile` for vault-wide truth maintenance.
226
227### Proactive save reminders
228Unsaved conversations are lost knowledge. Claude should proactively remind the user to save:
229- After 10+ exchanges: suggest "Want me to run /obsidian-save before we continue?"
230- When the user signals wrap-up (e.g., "ok", "thanks", "done", "bye", "that's it"): suggest "Before you go - want me to /obsidian-save this conversation?"
231- When a logical work block completes (feature shipped, decision made, problem solved): suggest saving
232- Never skip the reminder. This is especially critical on Claude Desktop where there's no background agent.
233
234### Search before creating
235Before creating any new note, search for an existing one:
236```
237search(query="keyword from title")
238```
239Duplicate notes are vault rot. Merge or update instead of creating new.
240
241### Never claim absence from memory, never fabricate
242Two failure modes corrupt the vault silently:
243- **False absence (most common):** never say "no note exists" or create a note on the assumption none exists without searching exhaustively first - by every plausible name, alias, and folder, listing and grepping, not from memory. When in doubt, over-include and label the uncertainty.
244- **Fabrication:** never invent facts, entities, rates, dates, or relationships that were not actually stated. Mark unknowns as `TBD`; an empty section is correct when nothing was said. External claims carry a source URL + recency marker; inferences carry a confidence level.
245
246See the anti-fabrication and search-completeness hard rules in `references/ai-first-rules.md`.
247
248### Match the vault's voice
249Read existing notes in the same folder before writing new ones.
250Match: frontmatter schema, heading style, list formatting, tone, emoji usage (or lack of it).
251Never introduce new conventions - extend what's already there.
252
253### Frontmatter is mandatory
254Every note gets frontmatter. At minimum:
255```yaml
256---
257date: 2026-03-24
258tags:
259 - <note-type>
260---
261```
262See `references/vault-schema.md` for full frontmatter specs by note type.
263
264---
265
266## Write Rules
267
268See `references/write-rules.md` for the complete guide. Summary:
269
270- **Links**: Use `[[Note Name]]` for internal links. Always link to people, projects, and jobs mentioned in a note.
271- **Dates**: ISO format (`YYYY-MM-DD`) in frontmatter. Human format (`March 24`) in body text.
272- **Naming**: `YYYY-MM-DD - Title.md` for dated notes. `Title.md` for evergreen notes. No special characters except the ASCII hyphen `-`. Never an em dash (U+2014) or en dash (U+2013) in a filename: link matching compares stems literally, so `2026-07-26 - Title.md` will not resolve a `[[2026-07-26 - Title]]` link, producing an orphan and a dangling link in the same write. The write-time validator checks file CONTENT, not filenames, so nothing catches this for you.
273- **Status values**: `active` / `planning` / `completed` / `archived` / `on-hold` for projects. `in-progress` / `done` / `waiting` for tasks.
274- **Kanban**: Items follow the format `- [ ] 🔴 **Title** · @{YYYY-MM-DD}\n\tDescription [[Link]]`
275
276---
277
278## The `_CLAUDE.md` File
279
280This is the most important concept in this skill.
281
282`_CLAUDE.md` lives at the vault root and persists Claude's operating rules across every session and every surface (Claude Desktop, Claude Code, VS Code, terminal). Without it, Claude has to re-learn your vault conventions every conversation.
283
284**Precedence rule:** `_CLAUDE.md` wins on all vault-specific rules (folder names, naming conventions, frontmatter fields, auto-save behavior, private folders). The defaults in this skill file apply only where `_CLAUDE.md` is silent. Never let skill defaults override an explicit `_CLAUDE.md` rule.
285
286**What it contains:**
287- Your vault's folder map and what each folder is for
288- Frontmatter schemas for your specific note types
289- Naming conventions you use
290- What to auto-save vs. what to ask first
291- People and projects that need special handling
292- Links to key files (boards, dashboard, templates)
293
294To generate a `_CLAUDE.md` for an existing vault, run vault discovery then use the template in `references/claude-md-template.md`.
295
296To install it: write the file to the vault root. Every Claude session that starts in that vault should read it first.
297
298---
299
300## Common Operations
301
302### Save info from conversation
303When a conversation produces something vault-worthy:
3041. Identify the note type (decision → project note, person met → People/, task → board + Tasks/, etc.)
3052. Check if a relevant note already exists
3063. Write or update - always frontmatter-first
3074. Propagate to boards, daily note, linked notes
308
309### Create today's daily note
310```
311date = today in YYYY-MM-DD format
312path = Daily/{date}.md
313```
314Read `Templates/Daily Note.md`, fill in the date fields, create the file.
315Then scan recent conversation for anything worth logging in today's sections.
316
317### Log a dev session
318Read `Templates/Dev Log.md`. Fill: date, project name, what was worked on, problems solved, decisions made, next steps.
319Save to `Dev Logs/YYYY-MM-DD - Project Name.md`.
320Link from project note's Recent Activity section and today's daily note.
321
322### Update a kanban board
323Boards use the `kanban-plugin: board` frontmatter.
324Columns are `## Column Name` headers.
325Items are `- [ ] **Title** · @{due-date}\n\tDescription [[Links]]`
326Completed items move to the `## ✅ Done` column with a strikethrough: `- [x] ~~**Title**~~ ✅ Date`
327
328### Run vault health check
329```bash
330uv run --directory "SKILL_ROOT" scripts/vault_health.py --path ~/path/to/vault
331```
332Reports: duplicate notes, orphaned files (no incoming links), stale tasks (overdue), empty folders, broken links, notes missing frontmatter.
333
334Proactively suggest running this when the user says the vault feels messy, notes are hard to find, they mention duplicates, or they haven't mentioned a health check in a long time. Offer: *"Want me to run a vault health check?"*
335
336---
337
338## Commands
339
340These slash commands can be used in any Claude surface. Each one is smart - it reads context, searches before writing, and propagates everywhere changes belong.
341
342**Name matching:** If a name argument has a typo or is approximate, search the vault for the closest match, show what was found, and confirm with the user before proceeding. Never silently create a note with a misspelled name.
343
344**Command selection: the longest matching trigger wins.** Several triggers are prefixes of longer, more specific ones, so a shorter match is not evidence that the shorter command is the right one. Always check whether a longer trigger also matches before choosing.
345
346The five collisions that exist today, with the correct routing:
347
348| The user says | Route to | Not to | Why it matters |
349|---|---|---|---|
350| "remind me every month...", "track a recurring..." | `/obsidian-recurring` | `/obsidian-task` | A one-shot card never recurs, which is the whole point of the request |
351| "save this idea", "capture this" | `/obsidian-capture` | `/obsidian-save` | One small idea note, not a multi-subagent sweep across people, projects, tasks, decisions and boards |
352| "save this person", "remember this person" | `/obsidian-person` | `/obsidian-save` | A person note, not a full conversation sweep |
353| "synthesize what I know about X" | `/vault-deep-synthesis` | `/obsidian-synthesize` | One topic cross-referenced, not a whole-vault pattern scan |
354| "find unnamed patterns" | `/obsidian-emerge` | `/obsidian-synthesize` | Surfaces patterns for the user, does not write synthesis pages unasked |
355
356When two commands still look equally plausible after applying the rule, ask which one rather than guessing - the blast radii differ enormously, and `/obsidian-save` in particular writes across many files.
357
358---
359
360### `/obsidian-save`
361
362**The master save command.** Reads the entire conversation and extracts everything worth preserving.
363
364Steps:
3651. Scan the conversation and identify all vault-worthy items: decisions, tasks, people mentioned, projects started, ideas, learnings, deals, mentions/shoutouts
3662. Group items by type: people, projects, tasks, decisions, ideas, deals
3673. Spawn parallel subagents - one per group - so all note types are handled simultaneously:
368 - **People agent**: search for each person, create or update notes, log interactions
369 - **Projects agent**: search for each project, create or update notes
370 - **Tasks agent**: parse tasks, add to the right kanban columns
371 - **Decisions agent**: find relevant project notes, append to Key Decisions sections
372 - **Ideas agent**: search Ideas/ for related notes, create or append
3734. After all agents complete: update today's daily note with links to everything saved
3745. Report back: a clean list of what was saved and where
375
376Do not ask for guidance on where to save things - infer it. Only ask if something is genuinely ambiguous (e.g. a person mentioned with no context on who they are).
377
378---
379
380### `/obsidian-daily`
381
382**Creates or updates today's daily note.** Full steps in `commands/obsidian-daily.md` (the source of truth).
383
384In short: resolves the daily folder per `references/folder-map.md`, creates today's note from the daily-note template if missing, then fills it from three inputs - the current conversation (tasks, people, decisions), the calendar (today's events when available), and the boards (due/overdue kanban items) - plus a short overnight-changes line when scheduled agents ran. Existing notes are injected into, never overwritten. Returns the note path.
385
386---
387
388### `/obsidian-calendar <mode>`
389
390**One calendar command with four modes.** Claude Code only (needs the Google Calendar MCP). The first word selects the mode; a bare range word defaults to `agenda`; no argument at all defaults to `agenda today`.
391
392- **`agenda [range]`** - reads the calendar and writes a re-derivable AI-first snapshot to `wiki/agenda/` (`type: agenda-snapshot`). Range: `today`, `tomorrow`, `week`, `next-week`, a date, or a range. Cross-links attendees to `[[Person]]` notes; flags conflicts, 3+ back-to-back stretches, working-hours focus blocks, and externally-organized events. Read-only on the calendar; Google Calendar stays the source of truth.
393- **`reconcile [window]`** - flags commitments the vault implies (project `next_action`s, due tasks, dated commitments in daily notes, fixed dates in `CRITICAL_FACTS.md`) that are NOT on the calendar, plus events with no vault context. Flag only - never adds or changes events.
394- **`meeting [selector]`** - turns an event (`last`, `next`, `today`, `event-id:<id>`, or fuzzy title) into a `type: meeting` note in `wiki/meetings/` with metadata pre-filled and **empty** Notes / Decisions / Action items sections (never fabricate meeting content). Cross-links attendees, backlinks any task whose `calendar-event-id` matches.
395- **`schedule <args>`** - the only mode that writes to the calendar. Standalone (`"<title>" <when> <duration>`), from a task (`task:<path>`), or suggest-a-time (`task:<...> suggest:<window>`). Resolves attendee emails from person notes (never guesses), conflict-checks before writing, requests a Meet link when participants span domains, and writes `calendar-event-id` back into the task so a re-run reschedules rather than duplicating.
396
397(Consolidated from the former `/obsidian-agenda`, `/obsidian-reconcile`-style calendar check, `/obsidian-meeting`, and `/obsidian-schedule` - same behaviors, one entry point. The natural-language triggers for all four still route here.)
398
399---
400
401### `/obsidian-recurring`
402
403**Tracks a recurring obligation (payment, filing, ops) with a cadence and a computed next-due date.**
404
405State the obligation and cadence (e.g. "pay social benefits, monthly day 20"). Searches for an existing note first, then builds a `type: recurring-task` note with What / Cadence / Blockers / History sections and frontmatter (`cadence`, `owner`, `blocker`, `next-due`, optional `amount`). Adds a board card for the next occurrence; on each completion, appends a History row and advances `next-due`. Fills the gap that `/obsidian-task` (one-shot) leaves.
406
407---
408
409### `/obsidian-log`
410
411**Logs a work or dev session to the vault.** Full steps in `commands/obsidian-log.md` (the source of truth).
412
413In short: infers the project from conversation, uses the dev-log template when one exists (inline structure otherwise), and saves `YYYY-MM-DD - Project Name.md` to the dev-log folder resolved per `references/folder-map.md` (wiki-style `wiki/logs/`, Obsidian-style `Dev Logs/`). Links are injected into the project note's Recent Activity and today's daily note.
414
415---
416
417### `/obsidian-task [description]`
418
419**Adds a task to the vault and the right kanban board.**
420
421Steps:
4221. Parse the task from the argument or from recent conversation context if no argument given
4232. Infer: priority (🔴/🟡/🟢), due date, linked project, linked person
4243. Search for the right kanban board - use `_CLAUDE.md` board list or search `Boards/`
4254. Add the task card to the correct column (`📋 This Week` or `📥 Backlog` depending on due date)
4265. Create a task note in `Tasks/` if the task is substantial (more than a one-liner)
4276. Link the task from the relevant project note and today's daily note
428
429---
430
431### `/obsidian-person [name]`
432
433**Creates or updates a person note.**
434
435Steps:
4361. Search the vault for an existing note matching the name (fuzzy - handle typos and partial names)
4372. If found: confirm with user, then update with new info from conversation
4383. If not found: create `People/Full Name.md` with full frontmatter schema
4394. Fill in everything inferable from the conversation: role, company, context, relationship strength, last interaction date
4405. Log the interaction in today's daily note
4416. If a People index file exists, add or update the entry there
442
443---
444
445### `/obsidian-capture [optional: idea text]`
446
447**Quick idea capture with zero friction.**
448
449Steps:
4501. Take the argument as the idea, or pull the most recent idea/thought from the conversation
4512. Search `Ideas/` for a related existing note - if found, append to it
4523. If new: create `Ideas/Title.md` with minimal frontmatter (`date`, `tags: [idea]`)
4534. Write the idea with any supporting context from the conversation
4545. Add a brief mention in today's daily note under an Ideas or Captures section
455
456---
457
458### `/obsidian-catchup [today|week|all]`
459
460**Process what the Telegram journal bot captured on the go.** The laptop-side companion to the `integrations/telegram-journal/` bot, which captures voice/text/image/PDF/link from your phone and appends each to a `catchup.md` queue in the vault.
461
462Steps:
4631. Read `catchup.md` in the vault root - each unchecked `- [ ]` line is an unprocessed capture (`date time | kind | summary | -> where`).
4642. Collect the unchecked items, applying the timeframe filter (`today` / `week` / `all`, default `all`). If none, say so and stop.
4653. Show them grouped by age (Today / This week / Older), flagging stale ones.
4664. Process WITH the user (not autonomously): open each linked note, propose **integrate** (fold into the right note per the AI-first rule) / **keep** / **discard**, confirm, then write.
4675. Check the item off (`- [x]` + processed date); never delete queue history.
468
469Pull, not push: nothing is processed until you run this, so nothing surprises you. The phone is for fast dumb capture; this is where it becomes integrated knowledge.
470
471---
472
473### `/obsidian-find [query]`
474
475**Smart vault search.**
476
477Steps:
4781. Run `search(query="...")` with the provided query
4792. Also try variations if results are sparse (synonyms, related terms)
4803. Return results with context: note title, folder, a relevant excerpt, and what type of note it is
4814. If results are ambiguous, group them by type (people, projects, tasks, etc.)
4825. Offer to open, update, or link any of the found notes
483
484Do not just return filenames - return enough context for the user to act.
485
486---
487
488### `/obsidian-recap [today|week|month]`
489
490**Summarizes a time period from the vault.**
491
492Steps:
4931. Determine the date range from the argument (default: `week` if not specified)
4942. List all daily notes in the range with `list_files_in_dir("Daily/")`
4953. Spawn parallel subagents - one per daily note - to read and extract key points from each simultaneously
4964. Also spawn parallel agents to read dev logs and completed kanban tasks from the same period
4975. Synthesize all agent results: what was worked on, decisions made, people interacted with, tasks completed, ideas captured
4986. Present as a clean narrative summary - not a raw dump of note content
499
500---
501
502### `/obsidian-review`
503
504**Generates a structured weekly or monthly review note.** Full steps in `commands/obsidian-review.md` (the source of truth).
505
506In short: reads the period's daily notes, dev logs, project changes, and completed board items; drafts from the review template when one exists (accomplishments, key decisions, people, learnings, carry-forward, plus the mandated "Suggested next week/month" section); saves `YYYY-MM-DD - Weekly Review.md` (or Monthly) to the reviews folder resolved per `references/folder-map.md`; links from the period's last daily note.
507
508---
509
510### `/obsidian-board [optional: board name]`
511
512**Shows or updates a kanban board.**
513
514Steps:
5151. If a board name is given, search `Boards/` for it (fuzzy match)
5162. If no name given, list available boards and ask which one
5173. Read and display the current board state: columns, item counts, overdue items (past `@{date}`)
5184. Ask if the user wants to make updates - if yes, infer changes from conversation context
5195. Move completed items to ✅ Done with strikethrough, add new items in the right column
5206. Flag any items that are overdue or have been in the same column for more than a week
521
522---
523
524### `/obsidian-board-hygiene [optional: board name]`
525
526**Bulk-triages a kanban board whose columns have gone stale.** Where `/obsidian-board` only flags overdue items, this clears them.
527
528Steps:
5291. Read `_CLAUDE.md` for the boards folder and kanban convention (columns, `@{date}` format)
5302. Read the target board (fuzzy-match; if none given, list boards and ask), parse every open item, compute age vs today
5313. Group items into overdue (`@{date}` past), stale (older than N days, default 14), and undated; show counts per column so the bloat is visible
5324. Propose ONE verdict per stale/overdue item with a one-line reason - done / reschedule / archive / keep - as a batch the user approves, edits, or overrides
5335. Apply approved verdicts in place (additive moves + strikethrough, never silent deletion), then report what moved and log it
534
535---
536
537### `/obsidian-project [name]`
538
539**Creates or updates a project note.**
540
541Steps:
5421. Search the vault for an existing project matching the name (fuzzy - handle typos)
5432. If found: show what was found, confirm, then update with new info from conversation
5443. If not found: create `Projects/Project Name.md` with full frontmatter schema (`date`, `tags: [project]`, `status: active`, `job`)
5454. Fill in everything inferable from the conversation: description, goals, key people, current status
5465. Add a card to the relevant kanban board in the `📥 Backlog` or `🔨 In Progress` column
5476. Link from today's daily note
548
549---
550
551### `/obsidian-projects [optional: project name]`
552
553**Live status overview across all tracked projects.**
554
555Reads `_CLAUDE.md` for the projects folder, then scans it for notes with `type: project` or a `repo:` field. For each project, spawns a parallel subagent that runs three checks: reads the vault note (status, last activity, next action, blockers), runs `git log` and `git status` if a `repo:` path is set, and looks for `NOTES.md` / `TODO.md` in the repo root. Merges the three into one status block (active / stalled / idle / blocked / archived inferred from activity recency), prints the full overview to the conversation ordered active-first, then injects a `## Last overview` section into each project note.
556
557If a project name argument is given, shows deep context for that one project only.
558
559---
560
561### `/obsidian-health`
562
563**Runs a vault health check and summarizes findings.**
564
565Steps:
5661. Run: `uv run --directory "SKILL_ROOT" scripts/vault_health.py --path ~/path/to/vault --json`
5672. Parse the JSON output and split findings into categories
5683. Spawn parallel subagents to handle each category simultaneously:
569 - **Links agent**: verify broken links, attempt to resolve them
570 - **Duplicates agent**: confirm duplicates are truly the same concept, not just similar names
571 - **Taxonomy agent**: only fires when `<vault>/_meta/taxonomy.md` exists (format in `references/taxonomy-format.md`) - opt-in, zero findings without it. `tag_synonym` (a tag is a known synonym of a canonical tag) offers a per-note rename to the canonical form with confirmation; `tag_not_in_taxonomy` (a tag matches neither a canonical tag nor a synonym) is informational only, never auto-fixed
572 - **Frontmatter agent**: identify notes missing required fields by type
573 - **Staleness agent**: check overdue tasks and unfilled template syntax
574 - **Orphans agent**: check orphaned notes and empty folders
575 - **Contradictions agent**: scan Key Decisions and Knowledge/ for claims that conflict or are superseded
576 - **Concept gaps agent**: find terms mentioned 3+ times without a dedicated page
577 - **Stale claims agent**: flag Knowledge/ notes older than 6 months on fast-moving topics
578 - **Freshness agent**: run `python scripts/freshness_lint.py --path <vault> --json` - enforces `references/freshness-policy.md` (every stored fact must be timeless, dated, or a pointer; fast facts carry an `as of` stamp or link to their home system)
579 - **Typed-edge lint agent**: run `python scripts/link_graph.py --path <vault> --lint` - validates the `relations:` typed-edge graph (Rule 6 § Typed edges in `references/ai-first-rules.md`): contradiction cycles (critical), unknown types / dangling targets / self-edges (warning), missing inverse edges (info). Returns zero findings on vaults that use no typed edges yet
5804. Merge agent results and group by severity:
581 - 🔴 Critical: broken links, unfilled template syntax, contradictions, typed-edge contradiction cycles
582 - 🟡 Warning: duplicates, stale tasks, missing frontmatter, stale claims, concept gaps, typed-edge problems (unknown type, dangling target, self-edge), tag-synonym findings
583 - ⚪ Info: orphaned notes, empty folders, missing inverse edges, tags not in the taxonomy
5845. Present a clean summary with counts per category
5856. For safe fixes (missing frontmatter, obvious duplicates, creating pages for concept gaps), offer to fix them automatically
5867. For destructive fixes (archiving, merging, resolving contradictions), list them and ask for explicit confirmation before touching anything
5878. Append an operation-log entry with severity counts - if `Logs/` exists write the entry to `Logs/YYYY-MM-DD.md`, otherwise append to `log.md` (SKILL.md's own rule: the root `log.md` is a pointer file in v0.9+ vaults, never an entry target)
588
589---
590
591### `/obsidian-reindex`
592
593**Refreshes the semantic search index and makes its coverage visible.** Full steps in `commands/obsidian-reindex.md` (the source of truth).
594
595In short: reads the vault path from `_CLAUDE.md`, reports the current `index_coverage`, runs the existing incremental `semantic_search.py --build`, and reports coverage again with the builder's new, cached, excluded, degraded, and dropped counts. A backend failure stops the flow and is shown to the user; it is never presented as a successful refresh. The command updates only `.obsidian-semantic-index.json`, not Markdown notes.
596
597---
598
599### `/obsidian-retrieval-eval [optional: N to generate | report]`
600
601**Measures how well vault search actually finds the right note - so improving retrieval is a number, not a hunch.**
602
603Hybrid command backed by `scripts/eval/retrieval_eval.py`, which reuses the REAL search engine (`integrations/obsidian-mcp-server/vault_ops.py`, the term-frequency, title-weighted ranking behind `/obsidian-find` and the MCP connector). It bootstraps its own eval set from the vault (an LLM writes a question per sampled note, avoiding the note's title words so it tests retrieval not string-match; the note is the gold answer), then scores recall@1/3/5/10 and MRR and lists the failures - misses and notes buried below #3, naming which note wrongly ranked #1. Claude interprets the numbers, turns failures into ranked retrieval fixes (each a hypothesis to re-measure on the same cases), and optionally writes an AI-first baseline note. Generated cases hold private note paths and are gitignored. The first run on a 1,000+ note vault scored **0% recall@10** on paraphrased questions (long `raw/` transcripts and `log.md` dominate term-frequency ranking) - proving the cheap structural fixes (exclude `raw/`, weight by `type:`) should be measured before reaching for a vector index.
604
605---
606
607### `/obsidian-merge <canonical> <retired> | --from-health`
608
609**Merges two near-duplicate notes that `/obsidian-health` found and stopped at. Dry run by default; the retired note becomes a redirect, never a deletion.**
610
611Health is read-only by contract, so the merge was the manual step everyone skipped and the same pairs came back every run. `scripts/merge_notes.py` does the mechanical half; you compose the merged body, because deciding what actually contradicts between two notes is judgment.
612
613Steps:
6141. Resolve the pair: two paths from the user (first survives, second retires; confirm if the richer note is the second), or `--from-health` to list the 2-file duplicate groups from a live `vault_health.check_duplicates()` run. A group of 3+ is never auto-paired.
6152. Read both notes in full. Compose the merged body per `references/ai-first-rules.md`: one `## For future agent` preamble naming both originals, both provenance trails kept, real contradictions listed with dates rather than resolved, every still-relevant `[[wikilink]]` from both sides carried over. Write it to a scratch file.
6163. Dry run: `uv run --directory "SKILL_ROOT" scripts/merge_notes.py --path <vault> --canonical <a> --retire <b> --merged-body-file <scratch>`. It prints the frontmatter conflicts (canonical wins, the retired value goes under `merged_from:`; list fields such as `tags` and `aliases` are unioned instead), the alias folded in, and the full text of both proposed notes. Show it verbatim.
6174. Ask for explicit confirmation, then re-run the identical command with `--apply`. Dry run and apply share one `compute_merge()`, so what was previewed is what gets written.
6185. Report which note survived, which became `type: redirect` (schema in `references/ai-first-rules.md`, Documented exceptions), the conflicts, and the contradictions the body documents. Log `merge | <retired> -> <canonical>` per the operation-log convention.
619
620---
621
622### `/obsidian-reconcile`
623
624**Finds and resolves contradictions across the vault.**
625
626Steps:
6271. Read `index.md` to understand the full vault landscape
6282. Spawn parallel subagents to find contradictions:
629 - **Claims agent**: scan `wiki/concepts/` and `wiki/projects/` for conflicting factual claims
630 - **Entity agent**: scan `wiki/entities/` for outdated roles, companies, or descriptions
631 - **Decisions agent**: scan `wiki/decisions/` for reversed or superseded decisions never updated
632 - **Source freshness agent**: compare `raw/` dates against `wiki/` pages for stale references
6333. For each contradiction, evaluate: which is newer, which is more authoritative, is it a genuine conflict or an evolution
6344. Resolve:
635 - **Clear winner**: rewrite the outdated page, add a History section noting what changed
636 - **Ambiguous**: create `wiki/decisions/Conflict - Topic.md` with both sides, mark `status: open`
637 - **Evolution**: update the page to current state with historical context
6385. Rebuild affected `index.md` sections, append an operation-log entry (if `Logs/` exists write the entry to `Logs/YYYY-MM-DD.md`, otherwise append to `log.md` (SKILL.md's own rule: the root `log.md` is a pointer file in v0.9+ vaults, never an entry target)), update daily note
639
640---
641
642### `/obsidian-synthesize`
643
644**Automatic synthesis - the vault thinks for itself.**
645
646Can run manually or as a scheduled agent. Scans the vault for patterns nobody asked about.
647
648Steps:
6491. Read `index.md` and `log.md` (last 20 entries) for recent activity
6502. Spawn parallel subagents:
651 - **Cross-source agent**: find concepts appearing in 2+ unrelated sources from the last 7 days
652 - **Entity convergence agent**: find people who appear together in multiple contexts but have no connection page
653 - **Concept evolution agent**: find concepts updated 3+ times and document how thinking changed
654 - **Orphan rescue agent**: find unlinked notes that should be connected to existing pages
6553. For each pattern: create `wiki/concepts/Synthesis - Title.md` with evidence, interpretation, and suggested action
6564. Link synthesis pages FROM all source notes they reference
6575. Update `index.md`, `log.md`, and today's daily note
658
659---
660
661### `/obsidian-export`
662
663**Export a clean snapshot any agent or tool can consume.** Full steps in `commands/obsidian-export.md` (the source of truth).
664
665In short: three formats - flat JSON (default, `_export/vault-snapshot.json`), a markdown index, or an OKF bundle (Open Knowledge Format, via `uv run scripts/export_okf.py`) that makes the vault readable by any OKF-speaking agent. Scans every note folder present (enumerated per `references/folder-map.md`, both vault styles), extracting path, title, type, date, status, summary, links, tags. Appends to the operation log.
666
667---
668
669### `/obsidian-init`
670
671**Bootstraps the vault's operating surfaces: `_CLAUDE.md`, `index.md`, the log setup, and Bases.** Full steps in `commands/obsidian-init.md` (the source of truth).
672
673In short: maps the vault (parallel subagents over the dashboard, templates, boards, and sample notes), generates `_CLAUDE.md` from `references/claude-md-template.md` with real values, writes `index.md` (the catalog) and the operation-log setup (per-day `Logs/` with a `log.md` pointer, or monolithic `log.md`), and stamps the `Bases/` live views from `references/bases/*.template` with the vault's folder names. Files are written with your file tools (or `obsidian_save_note` on MCP clients). Tell the user to restart the session afterwards.
674
675If `_CLAUDE.md` already exists: show a diff of what would change and ask before overwriting.
676
677---
678
679### `/obsidian-architect`
680
681**Scans a codebase and writes a maintained set of architecture notes into the vault - overview, per-module notes, key decisions. Re-runnable.**
682
683Hybrid command: `scripts/architect_scan.py` does a deterministic scan (stack, modules, dependencies, entry points, git commit) and emits JSON; Claude synthesizes the prose, rationale, a Mermaid diagram, and likely personas, then writes AI-first notes under `Projects/<name>/Architecture/` (`type: architecture-overview` + `type: architecture-module`). Pulls decision candidates from `scripts/mine_commit_decisions.py`. Refresh is the same command re-run: it uses sentinel markers (`<!-- @generated -->` / `<!-- @user -->`, see `references/write-rules.md`) so re-running updates only the generated blocks and never clobbers your hand-edits. For builders who want their code projects documented in the same brain as their ideas and decisions.
684
685---
686
687### `/obsidian-visualize [scope]`
688
689**Generates a JSON Canvas map of the vault's knowledge graph, openable in Obsidian's native canvas viewer.**
690
691Backed by `scripts/link_graph.py` (deterministic link extraction - no whole-vault read). Optional scope: a project, entity, topic, or `full` (default). Builds nodes and edges from `[[wikilinks]]`, clusters by type (entities, projects, concepts, daily, sources) with color and size keyed to centrality, flags orphans with a red border, and writes `atlas.canvas` (or `atlas-<topic>.canvas`) to the vault root. Also emits a text summary: hub nodes by degree centrality, bridge nodes, stale orphans, clusters, and any centrality skew (a single navigation point of failure). Reads the `typed_edges` overlay (from `relations:` frontmatter) to label canvas edges with their relation type and surface the longest `supersedes`/`depends_on`/`caused` reasoning chains. Appends a one-line entry to the operation log.
692
693**Typed edges (graph engineering).** Beyond untyped `[[wikilinks]]`, notes can record *typed* relationships in a `relations:` frontmatter block - `supersedes`, `depends_on`, `caused`, `decided_by`, `relates_to`, `contradicts` (each with an inverse). This makes the graph traversable by meaning, not just adjacency. `scripts/link_graph.py` extracts them as a semantic overlay and `--lint` validates them (unknown types, dangling targets, contradiction cycles, missing inverses); `/obsidian-health` runs that lint. The full spec is Rule 6 § Typed edges in `references/ai-first-rules.md`. The overlay is always reconstructed from frontmatter on demand - plain markdown, no separate graph store.
694
695---
696
697### `/create-command [seed]`
698
699**Scaffolds a new obsidian-second-brain command through a short interview - no markdown or frontmatter editing.**
700
701A guided conversation (intent, name, category, trigger phrases, behavior steps, AI-first compliance, external APIs) writes a fully-formed `commands/<name>.md` that the build pipeline picks up on the next `bash scripts/build.sh`, flowing into all eight platform builds. The optional seed pre-fills suggestions. Every command created this way lands AI-first-compliant by construction. (This is the command that creates commands; it does not run on itself.)
702
703---
704
705### `/obsidian-ingest`
706
707**Ingests a source into the vault - one source touches many pages.**
708
709Steps:
7101. Accept a URL, file path, or pasted text as the source
7112. Classify the source type before full read: article, PDF, transcript, video, or raw text
7123. Read or fetch the full source content
7134. Extract: entities (people, companies, tools), concepts, claims, action items, notable quotes
7145. Save the raw source to `Knowledge/YYYY-MM-DD - Source Title.md` with full summary and source link
7156. Spawn parallel subagents to distribute knowledge across the vault:
716 - **People agent**: create or update People/ notes for each person mentioned
717 - **Projects agent**: update existing project notes with new findings
718 - **Ideas agent**: create or append to Ideas/ for new concepts
719 - **Knowledge agent**: create or update Knowledge/ notes for factual claims and frameworks
7207. Update `index.md` with all newly created notes
7218. Append an operation-log entry: if `Logs/` exists write `**HH:MM** - ingest | Source Title (type) - X created, Y updated` to `Logs/YYYY-MM-DD.md`; otherwise append `## [YYYY-MM-DD] ingest | Source Title (type) - X created, Y updated` to `log.md`
7229. Update today's daily note with an ingest summary
723
724A single ingest should touch 5-15 files. Compile knowledge once, distribute everywhere.
725
726---
727
728### `/obsidian-decide [topic] [--formal]`
729
730**Records decisions at two depths.** Default mode captures the decisions made in a conversation as dated one-liners appended to the relevant project notes' `## Key Decisions` sections (and the daily note) - for the steady stream of choices made while working. `--formal` (or leading with `adr`) instead writes one full Architecture Decision Record - Decision / Context / Options Considered / Rationale / Consequences / Related - to the decisions folder (resolved per `references/folder-map.md`: wiki-style `wiki/decisions/`, Obsidian-style `Knowledge/`), links it from the project's Key Decisions and `index.md`, and logs it. Use the formal mode for a structural or directional decision worth a real writeup; `python scripts/mine_commit_decisions.py` surfaces decision-shaped commits as ADR candidates.
731
732The vault knows why it's structured the way it is - when a future session asks "why?", the formal record answers. `/obsidian-graduate`, `/obsidian-health` structural fixes, and folder reorganizations may offer to write a formal record; they offer, they don't force.
733
734(Consolidated: the former standalone `/obsidian-adr` is now `/obsidian-decide --formal`; its triggers still route here.)
735
736---
737
738### `/obsidian-learn [recent|all|topic]`
739
740**Reviews the lessons scattered across the vault and turns them into a living rulebook.**
741
742Scans daily notes, dev logs, ADRs, and auto-generated pattern reports for lessons, mistakes, and wins, then classifies each as active, stale, superseded, or a promotion candidate (appeared 3+ times - worth becoming a permanent rule in `_CLAUDE.md`). Default scope is the last 30 days (`all` for the whole vault, or a named topic). Writes a Learnings Review to `wiki/concepts/YYYY-MM-DD - Learnings Review.md` and offers to promote candidates or archive stale lessons with confirmation. Lessons that are not reviewed do not compound.
743
744---
745
746## Thinking Tools
747
748These commands use the vault as a thinking partner - not just storage. They surface insights, challenge assumptions, and generate connections that the user cannot see on their own.
749
750---
751
752### `/obsidian-brainstorm`
753
754**Multi-turn Socratic brainstorm - the only stateful thinking tool.**
755
756Every other thinking tool is a single-shot analytical pass; this one interviews the user one question per turn (multiple-choice preferred) across six categories - problem framing, constraints, trade-off forcing, scope bounding, prior-decision linking, anti-goals - until an internal 6-item convergence checklist reaches at least 5, then presents 2-3 named approaches with exactly one (Recommended), and writes a `type: brainstorm` note (conclusions and reasoning, never the transcript). Grounds its questions in the vault first: related decisions, contradictions, and open questions become interview material. Offers `/obsidian-graduate` or `/obsidian-decide` when the outcome is project- or ADR-shaped. Full flow in `commands/obsidian-brainstorm.md`.
757
758---
759
760### `/obsidian-challenge`
761
762**Red-teams your current idea against your own vault history.**
763
764Steps:
7651. Identify the user's current claim, plan, or assumption - from the argument or conversation context
7662. Extract the key premises behind that position
7673. Spawn parallel subagents to search for counter-evidence:
768 - **Decisions agent**: search Key Decisions sections for past decisions that contradicted similar thinking
769 - **Failures agent**: search dev logs, daily notes, and archives for past failures or lessons related to this topic
770 - **Contradictions agent**: search for notes where the user held the opposite position or flagged risks
7714. Synthesize a structured "Red Team" analysis:
772 - **Your position**: restate the claim
773 - **Counter-evidence from your vault**: cite specific notes, dates, and quotes
774 - **Blind spots**: what the user might be ignoring based on their own history
775 - **Verdict**: consistent with past experience, or does the vault suggest caution?
7765. Log the challenge in today's daily note under a Thinking section
777
778Do not be agreeable. The entire point is to pressure-test. Cite specific vault files.
779
780---
781
782### `/obsidian-emerge`
783
784**Surfaces unnamed patterns from recent notes - recurring themes and conclusions you haven't explicitly stated.**
785
786Steps:
7871. Determine the date range from the argument (default: last 30 days)
7882. Spawn parallel subagents to scan vault content:
789 - **Daily notes agent**: extract recurring topics, complaints, observations, energy patterns
790 - **Dev logs agent**: extract repeated blockers, tools, architectural patterns
791 - **Decisions agent**: look for directional trends across project notes
792 - **Ideas agent**: look for thematic clusters in Ideas/ notes
7933. Identify:
794 - **Recurring themes**: topics that appeared 3+ times without being named as a priority
795 - **Emotional patterns**: what energizes vs. drains (based on language)
796 - **Unnamed conclusions**: things the notes imply but never state outright
797 - **Emerging directions**: where the vault suggests the user is heading
7984. Present a "Pattern Report" - each pattern with evidence (cited notes), interpretation, and suggested action
7995. Offer to save the report to `Ideas/` or a relevant project note
8006. Log a summary in today's daily note
801
802The goal is insight the user cannot see themselves. Surface what they haven't named yet.
803
804---
805
806### `/obsidian-connect [topic A] [topic B]`
807
808**Bridges two unrelated domains using the vault's link graph to spark new ideas.**
809
810Steps:
8111. Parse two domains from arguments (e.g., `/obsidian-connect "distributed systems" "cooking"`)
8122. For each domain, search the vault: find all related notes, map backlinks and outgoing links to build a local cluster
8133. Find the bridge:
814 - Shared links, tags, or people between the two clusters
815 - If a direct path exists in the link graph, trace it and explain each hop
816 - If no direct path, find the closest semantic overlap
8174. Generate creative connections:
818 - **Structural analogy**: how a pattern in A maps to B
819 - **Transfer opportunities**: what works in A that could apply to B
820 - **Collision ideas**: new concepts that only exist at the intersection
8215. Present 3-5 specific, actionable connections - not vague analogies but concrete ideas
8226. Offer to save the best connections to `Ideas/` with links to both source domains
8237. Log the connection exercise in today's daily note
824
825The value is in unexpected links. If the connection is obvious, dig deeper.
826
827---
828
829### `/obsidian-graduate`
830
831**Promotes an idea fragment into a full project spec with tasks, board entries, and structure.**
832
833Steps:
8341. If argument given: search `Ideas/`, daily notes, and captures for a matching idea (fuzzy)
8352. If no argument: list recent ideas (last 14 days) and ask the user to pick one
8363. Read the full idea note and any linked notes for context
8374. Research the vault for related content: overlapping projects, related people, past decisions, similar ideas explored before
8385. Generate a full project spec:
839 - **Project note** in `Projects/` with complete frontmatter (status: planning, linked idea)
840 - **Goals**: 3-5 concrete outcomes
841 - **Key tasks**: broken into phases with priorities
842 - **Open questions**: what still needs answering
843 - **Related notes**: links to everything relevant
8446. Add cards to the relevant kanban board
8457. Update the original idea note: add `status: graduated` and link to the new project
8468. Link the new project from today's daily note
847
848The idea doesn't die - it evolves. The original note stays as the origin story.
849
850---
851
852### `/obsidian-panel`
853
854**Convenes a panel of distinct perspectives on a decision - one independent verdict per lens, then a synthesis.**
855
856A multi-persona complement to `/obsidian-challenge` (which red-teams from one stance). Uses the vault's `Advisors/` persona notes as panelists if they exist, otherwise four generic lenses (skeptic, user, operator, long-game). Each panelist argues independently before the synthesis; the disagreement is the point and is never hidden. Saves a `type: synthesis` note to `wiki/concepts/`.
857
858---
859
860### `/vault-deep-synthesis [topic]`
861
862**Cross-references everything the vault knows about one topic: agreements, contradictions, stale claims, coverage gaps.**
863
864Topic-driven (unlike `/obsidian-synthesize`, which scans the whole vault unprompted). Pure vault, no network. Greps and reads every note touching the topic, then consolidates into what the vault agrees on, where notes contradict (surfaced, not resolved - that is `/obsidian-reconcile`), what looks stale, and what is missing. Saves a `type: synthesis` note; never modifies the sources.
865
866---
867
868### `/obsidian-distill [note or source]`
869
870**Condenses one source into key claims, each tagged with provenance back to the exact block it came from.** A distillation, not a summary: condensed enough to read fast, anchored enough to audit.
871
872Segments the source into numbered, citable blocks (`B1`, `B2`, ...), extracts the key claims, and tags each claim with the block(s) it came from (`(src: B3)`). A claim with no traceable source does not make the cut - and gets reported as dropped, never silently cut. Inferences the source implies but never states go in a separate labelled section so distilled fact and reasoning never blur. Saves a `type: distillation` note (with the verbatim `source` and the numbered source blocks at the bottom), links it from the original. This is the trust primitive for a vault more than one person reads - the differentiator behind the team-vault direction. Pairs with `/obsidian-ingest` (brings the source in) and `/vault-deep-synthesis` (cross-references many notes).
873
874---
875
876### `/idea-discovery`
877
878**Ranks 3-5 next-direction candidates from ungraduated ideas, open project questions, and orphan research.**
879
880Answers "what is worth doing next" from vault material. Distinct from `/obsidian-emerge` (names unstated patterns) and `/obsidian-graduate` (promotes one chosen idea). Ranks candidates by a stated heuristic (recency, pull, momentum) and gives the smallest next step for each. Does not auto-graduate.
881
882---
883
884## Context Engine
885
886### `/obsidian-world`
887
888**Loads your identity, values, priorities, and current state in one shot - with progressive context levels.**
889
890Uses token budgets to avoid loading the entire vault. Start light, go deeper only as needed.
891
892Steps:
8931. **L0 - Identity (~200 tokens)**: read `SOUL.md`/`About Me.md` and `CORE_VALUES.md`/`Values.md`
8942. **L1 - Navigation (~1-2K tokens)**: read `index.md` (vault catalog) and `log.md` (last 10 entries)
8953. **L2 - Current State (~2-5K tokens)**: read `Home.md`/`Dashboard.md`, today's daily note, last 3 daily notes, active kanban boards, previous session digests
8964. **L3 - Deep Context (on demand, ~5-20K tokens)**: only load if needed - active project notes, full Knowledge/ articles, recently mentioned people
897
898Present a brief status after L0-L2 (do NOT load L3 unless needed):
899- **Who I am to you**: persona and communication style
900- **Your current priorities**: top 3-5 active threads (from index.md + boards)
901- **Open threads from last session**: anything unfinished (from log.md + daily notes)
902- **Overdue / needs attention**: stale tasks or projects
903- **Today so far**: what's already logged
904
905Keep output concise - this is a boot-up sequence, not a report.
906
907If identity files don't exist, offer to create them by asking 5-7 quick questions about the user's role, values, and preferences.
908If `index.md` doesn't exist, offer to run `/obsidian-init` to generate it.
909
910---
911
912## Research Commands
913
914Seven commands that pull external knowledge into the vault - X posts, X discourse, web research with citations, vault-grounded synthesis, YouTube videos, and podcast episodes (plus `/obsidian-ingest` above for arbitrary URLs, PDFs, audio, and screenshots). All output AI-first notes per the vault's Section 0 rule (preamble, rich frontmatter, recency markers, mandatory wikilinks, sources verbatim).
915
916**Setup:** API keys live at `~/.config/obsidian-second-brain/.env`. Run `install.sh` and answer "y" to the research toolkit prompt, or copy `.env.example` manually. The xAI Grok key is required for `/x-read` and `/x-pulse`. Perplexity is optional: with no `PERPLEXITY_API_KEY` set, `/research` and `/research-deep` fall back to free key-less sources automatically, and `--free` forces that path even when a key exists (`--academic` restricts it to scholarly sources). YouTube key is optional; transcripts work without it. Never tell a user a research command is unavailable because they lack a Perplexity key.
917
918**Stack:** Python 3.10+ with `uv`. Install deps via `uv sync` from the repo root.
919
920---
921
922### `/x-read [url]`
923
924**Deep-read an X post** via Grok + Live Search. Verbatim post + thread + TL;DR + key claims + reply sentiment + voices to watch.
925
926Steps:
9271. Validate the URL contains `x.com/` or `twitter.com/`
9282. Run `uv run -m scripts.research.x_read "<url>"` from the repo root
9293. Show the structured analysis verbatim to the user
9304. **Default save: chat only.** If the user asks "save this", write an AI-first note to `Research/X-reads/`
931
932Plain English triggers: "read this tweet", "analyze this X post", "what's in this tweet".
933
934---
935
936### `/x-pulse [topic]`
937
938**Scan X for what's trending** in a topic. Themes (with rep posts + voices), gaps, hooks working, voice/tone, post ideas.
939
940Steps:
9411. Resolve the topic (multi-word fine)
9422. Run `uv run -m scripts.research.x_pulse "<topic>"`
9433. Show the pulse output verbatim
9444. **Default save: auto-saves** to `Research/X-pulse/YYYY-MM-DD - <slug>.md` (AI-first format)
9455. Append a one-line operation-log entry - if `Logs/` exists write the entry to `Logs/YYYY-MM-DD.md`, otherwise append to `log.md` (SKILL.md's own rule: the root `log.md` is a pointer file in v0.9+ vaults, never an entry target)
946
947Plain English: "what's hot on X about AI", "X pulse on vibe coding", "what should I post today on AI automation".
948
949---
950
951### `/research [topic]`
952
953**Web research with citations** via Perplexity Sonar Pro. Deep dossier: summary, key facts (with recency markers), timeline, key players, contrarian views, further reading, open questions.
954
955Steps:
9561. Resolve the topic
9572. Run `uv run -m scripts.research.research "<topic>"`
9583. Show the dossier verbatim, including citations
9594. **Default save: auto-saves** to `Research/Web/YYYY-MM-DD - <slug>.md`
9605. All citations stored in frontmatter for later Dataview queries
961
962Plain English: "research X", "look up X", "find me info on X". Note: "do deep research" routes to `/research-deep` instead.
963
964---
965
966### `/research-deep [topic]`
967
968**Vault-first deep research with cross-vault propagation.** The chain-everything command.
969
970Steps (4 phases):
9711. **Vault scan** - find existing notes mentioning the topic (the baseline)
9722. **Gap analysis** - Perplexity sonar-pro identifies what's missing/stale, emits 3-5 targeted queries
9733. **Gap-fill** - runs each query via Perplexity (web) or Grok+Live Search (X)
9744. **Synthesis** - Perplexity sonar-deep-research produces a delta report (what's new, what's confirmed, contradictions, recommended vault updates, open questions)
975
976Then:
977- Writes synthesis to `Research/Deep/YYYY-MM-DD - <slug>.md`
978- Emits a JSON propagation payload between `<<<RESEARCH_DEEP_PROPAGATION_PAYLOAD>>>` markers
979- Calling Claude reads that payload and runs `/obsidian-save`-style propagation: spawns parallel subagents to update People/Projects/Ideas/Decisions per the synthesis's "Recommended Vault Updates" bullets
980- Links new research note from today's daily note
981
982Cost: typically $0.20-$0.80 per run depending on topic depth.
983
984Plain English: "do deep research on X", "research properly", "vault-aware research on X", "research and update the vault".
985
986Graceful degradation: if any phase fails partially (e.g. Grok unavailable), continues with available sources and flags the gap.
987
988---
989
990### `/notebooklm [topic]`
991
992**Vault-first source-grounded research via Gemini File Search - one command, no browser.** The grounded parallel to `/research-deep` (open-web). Full steps in `commands/notebooklm.md` (the source of truth).
993
994In short: `uv run -m scripts.research.notebooklm --topic "<topic>"` scans the vault for the top 12 relevant notes, uploads them to a fresh Gemini File Search store, asks Gemini (default `gemini-2.5-flash`, `NOTEBOOKLM_MODEL` overrides) for a synthesis grounded against those sources with citations, saves the AI-first note to `Research/NotebookLM/`, deletes the store so nothing is left behind, and emits a propagation payload that runs the standard `/obsidian-save` flow. Needs `GEMINI_API_KEY`.
995
996When to use it over `/research-deep`: grounded in YOUR sources vs open web - run both on high-value topics; the contradictions between the two views are where the insight is.
997
998Plain English: "notebooklm this", "ask my notebook about X", "ground a research on X using my vault".
999
1000---
1001
1002### `/youtube [url] [--visual]`
1003
1004**Extract and summarize a YouTube video.** Transcript (free, no API key) + metadata + top comments (Data API v3, optional) → summarized via Gemini (free tier), Grok fallback. Add `--visual` to also *watch* the video: scene-change frame extraction Claude reads with its own vision.
1005
1006Steps:
10071. Parse video ID from URL or 11-char ID
10082. Run `uv run -m scripts.research.youtube_extract "<url>"` (add `--visual` for the frame layer, `--max-frames N` to cap frames read, default 24)
10093. Fetches transcript via `youtube-transcript-api`
10104. If `YOUTUBE_API_KEY` set: also fetches title, channel, view counts, top comments
10115. Sends transcript + comments to Gemini (Grok fallback) for AI-first summary: TL;DR, Key Points, Notable Quotes, Themes, Comment Sentiment, Worth Following Up On
10126. **Default save: auto-saves** to `Research/YouTube/YYYY-MM-DD - <video-title-slug>.md`
1013
1014**`--visual` layer:** downloads the video (yt-dlp, <=720p) and extracts one frame per scene change (ffmpeg scene detection, not a fixed timer), so on-screen text, code, diagrams, slides, UI, and b-roll are captured. Hero frames are copied into `Research/YouTube/attachments/<slug>/` and embedded in the note; the full keyframe set is left on disk. The script prints a `FRAMES-FOR-CLAUDE` block - Claude then reads those frames (its own vision, no extra API call) and fills the note's `## Visual notes` section keyed by timestamp. Requires `yt-dlp` + `ffmpeg` on PATH; if missing or download fails, the visual layer is skipped and the transcript summary still saves. The pipeline is ported from claude-watch/claude-video (MIT).
1015
1016Plain English: "summarize this YouTube video", "extract this video", "watch this video", "what's on screen", or just paste a YouTube URL with a question. Use `--visual` when the ask is about what is *shown*, not just said.
1017
1018If the video has no captions and no API key set, the transcript path fails with a clear message; `--visual` can still read the video.
1019
1020---
1021
1022### `/podcast [url]`
1023
1024**Extract and summarize a podcast episode.** Apple Podcasts URL or RSS feed → transcript (RSS `<podcast:transcript>` tag, Whisper API if `OPENAI_API_KEY` set, or show-notes fallback) → summarized via Grok.
1025
1026Steps:
10271. Parse Apple Podcasts URL (resolved to RSS via free iTunes Lookup API) or RSS feed URL
10282. Run `uv run -m scripts.research.podcast_extract "<url>"`
10293. Fetch episode metadata + audio URL + show notes from RSS
10304. Try transcript sources in order: `<podcast:transcript>` tag → Whisper API (if `OPENAI_API_KEY`) → show-notes-only
10315. Send transcript-or-shownotes to Grok for AI-first summary: TL;DR, Key Points, Notable Quotes, Themes, Guests & People Mentioned, Worth Following Up On
10326. **Default save: auto-saves** to `Research/Podcasts/YYYY-MM-DD - <episode-title-slug>.md`
1033
1034Plain English: "summarize this podcast", "what's in this episode", or just paste an Apple Podcasts URL.
1035
1036Spotify URLs are not supported (DRM blocks audio + transcript access). If no transcript path works and show notes are empty, the script fails with a clear message.
1037
1038---
1039
1040### Cost tracking
1041
1042`/x-read`, `/x-pulse`, `/youtube` (Gemini-first summarize), `/podcast` (Grok summarize), and the Perplexity calls in `/research`/`/research-deep` log usage to `~/.research-toolkit/usage.log`. View monthly totals via:
1043```bash
1044uv run python -c "from scripts.research.lib.usage import month_total; t,c = month_total(); print(f'\${t:.2f} across {c} calls')"
1045```
1046
1047
1048No hard caps. No blocking. No per-call confirmation prompts. Trust the user to monitor.
1049
1050---
1051
1052## Scheduled Agents
1053
1054Four autonomous agents designed to run on a schedule with no user intervention. Each runs a focused vault operation at a set time, then stops. They are conservative by default - they never delete or archive anything autonomously, and they never ask the user questions mid-run.
1055
1056Set these up once using the `/schedule` skill in Claude Code.
1057
1058---
1059
1060### `obsidian-morning` - Daily at 8:00 AM
1061
1062**Creates today's daily note and surfaces what needs attention.**
1063
1064Prompt to schedule:
1065```
1066Read _CLAUDE.md. Create today's daily note in Daily/ using the Daily Note template.
1067Pull in any tasks from kanban boards that are due today or overdue.
1068List any projects with status active that have no recent activity in the last 7 days.
1069Do not ask questions - infer everything from the vault. Save and stop.
1070```
1071
1072Setup:
1073```
1074/schedule obsidian-morning - daily 8:00 AM
1075```
1076
1077---
1078
1079### `obsidian-nightly` - Daily at 10:00 PM
1080
1081**Sleeptime consolidation - the vault gets smarter overnight.**
1082
1083This agent does more than close the day. It actively consolidates and improves the vault while you sleep.
1084
1085Prompt to schedule:
1086```
1087Read _CLAUDE.md. This is a sleeptime consolidation pass - the vault should be smarter when the user wakes up.
1088
1089Phase 1 - Close the day:
1090- Read today's daily note. Append a ## End of Day section with a 3-5 bullet summary.
1091- Move any completed kanban tasks to Done.
1092
1093Phase 2 - Reconcile:
1094- First resolve the entities, concepts, and decisions folders per references/folder-map.md: the vault's _CLAUDE.md Folder Map wins,
1095 else wiki-style wiki/entities/ + wiki/concepts/ + wiki/decisions/, else Obsidian-style People/ + Knowledge/ (and Ideas/) + Knowledge/.
1096 A resolved folder that does not exist is a skip, not an error. Never scan a hardcoded wiki/ path on a vault with no wiki/ folder -
1097 unattended, that is three tool failures a night with nothing to show for them.
1098- Scan the entities folder for outdated roles, companies, or descriptions that conflict with newer daily notes.
1099- Scan the concepts folder for claims contradicted by recently ingested sources.
1100- Flag EVERY contradiction as a `type: conflict` note with `status: open` in the decisions folder. Do NOT rewrite any existing page.
1101 (Resolving a contradiction means rewriting the outdated note, which is destructive and irreversible while the user sleeps. It also
1102 contradicts the constraint below. Leave the resolve step to an interactive /obsidian-reconcile run, matching the health agent's
1103 report-only posture.)
1104
1105Phase 3 - Synthesize:
1106- Scan sources ingested today and yesterday. Find concepts that appear in 2+ unrelated sources.
1107- If patterns found: create `Synthesis - Title.md` in the concepts folder resolved in Phase 2, with evidence and interpretation.
1108
1109Phase 4 - Heal:
1110- Find notes created today with no incoming links. Add links from relevant existing pages.
1111- Check if any entity pages reference old timeline entries without an "until" date that should be closed.
1112- Rebuild index.md to reflect today's changes.
1113
1114Phase 5 - Log:
1115- Append an operation-log entry: if `Logs/` exists write `**HH:MM** - nightly | End of day + X flagged, Y synthesized, Z orphans linked` to `Logs/YYYY-MM-DD.md`; otherwise append `## [YYYY-MM-DD] nightly | ...` to `log.md`
1116
1117Do not ask questions. Do not fix anything destructive - only add, update, link. Save and stop.
1118```
1119
1120Setup:
1121```
1122/schedule obsidian-nightly - daily 10:00 PM
1123```
1124
1125---
1126
1127### `obsidian-weekly` - Every Friday at 6:00 PM
1128
1129**Generates a weekly review note from the vault.**
1130
1131Prompt to schedule:
1132```
1133Read _CLAUDE.md. Run /obsidian-recap week to gather this week's activity.
1134Generate a weekly review note using the Review template (or standard structure if none exists).
1135Save to Reviews/YYYY-MM-DD - Weekly Review.md.
1136Link it from this week's last daily note.
1137Do not ask questions. Save and stop.
1138```
1139
1140Setup:
1141```
1142/schedule obsidian-weekly - every Friday 6:00 PM
1143```
1144
1145---
1146
1147### `obsidian-health-check` - Every Sunday at 9:00 PM
1148
1149**Runs the vault health check and logs a report.**
1150
1151Prompt to schedule:
1152```
1153Read _CLAUDE.md. Run: uv run --directory "SKILL_ROOT" scripts/vault_health.py --path ~/path/to/vault --json
1154Parse the output. Write a health report to Knowledge/Vault Health YYYY-MM-DD.md
1155summarizing findings by severity (critical, warning, info).
1156Do not fix anything autonomously - only report.
1157Do not ask questions. Save and stop.
1158```
1159
1160Setup:
1161```
1162/schedule obsidian-health-check - every Sunday 9:00 PM
1163```
1164
1165---
1166
1167### Setting up scheduled agents
1168
1169All four can be configured at once:
1170
1171```
1172/schedule
1173```
1174
1175Then tell Claude which agents you want and at what times. Claude Code's scheduling system will handle the rest - agents run autonomously in the background on the defined cron schedule.
1176
1177To list or remove scheduled agents:
1178```
1179/schedule list
1180/schedule remove obsidian-morning
1181```
1182
1183### Running commands headless (`claude -p`) - important gotcha
1184
1185Custom slash commands do NOT expand in non-interactive mode. A cron job or launchd
1186job that runs `claude -p "/obsidian-daily"` will send the literal text `/obsidian-daily`
1187as a prompt - Claude never loads the command file, so nothing happens.
1188
1189The reliable pattern for any headless run (cron, launchd, a wrapper script) is to point
1190Claude at the command file and tell it to carry out the instructions:
1191
1192```bash
1193# Wrong - the slash command is not expanded in -p mode:
1194claude -p "/obsidian-daily"
1195
1196# Right - read the command file and execute its steps:
1197cd "$VAULT" && claude --dangerously-skip-permissions \
1198 -p "Read ~/.claude/commands/obsidian-daily.md and carry out its instructions exactly."
1199```
1200
1201Because `~/.claude/commands/obsidian-daily.md` is symlinked from this repo (see Testing
1202locally in the README), a scheduled run always uses the current command logic. Export an
1203explicit `PATH` in launchd jobs - launchd strips the environment, so `claude` and `python3`
1204may not be found otherwise.
1205
1206---
1207
1208## Background Agent (PostCompact Hook)
1209
1210A background agent that fires automatically whenever Claude compacts the conversation context. It reads the session summary and propagates everything worth preserving to the vault - no user action required.
1211
1212**What it does:** After each compaction, a headless `claude -p` subprocess wakes up, reads `_CLAUDE.md`, scans the summary for vault-worthy items (people, projects, decisions, tasks, dev work, ideas), and writes updates everywhere they belong - people notes, project notes, dev logs, kanban boards, and today's daily note.
1213
1214**How it works:**
12151. `PostCompact` hook fires in Claude Code after context compaction
12162. Hook script reads the JSON summary from stdin
12173. Spawns a headless `claude --dangerously-skip-permissions -p` subprocess in the vault directory
12184. Agent runs silently, propagates updates, and exits - user sees nothing
1219
1220**Setup:**
1221
12221. Make the hook script executable (one-time):
1223 ```bash
1224 chmod +x ~/.claude/skills/obsidian-second-brain/hooks/obsidian-bg-agent.sh
1225 ```
1226
12272. Set `OBSIDIAN_VAULT_PATH` in `~/.claude/settings.json`:
1228 ```json
1229 {
1230 "env": {
1231 "OBSIDIAN_VAULT_PATH": "/path/to/your/vault"
1232 }
1233 }
1234 ```
1235
12363. Add the `PostCompact` hook to `~/.claude/settings.json`:
1237 ```json
1238 {
1239 "hooks": {
1240 "PostCompact": [
1241 {
1242 "matcher": "",
1243 "hooks": [
1244 {
1245 "type": "command",
1246 "command": "/Users/you/.claude/skills/obsidian-second-brain/hooks/obsidian-bg-agent.sh",
1247 "timeout": 10,
1248 "async": true
1249 }
1250 ]
1251 }
1252 ]
1253 }
1254 }
1255 ```
1256
1257**Debugging:** The agent logs to `/tmp/obsidian-bg-agent.log`. Check there if updates aren't appearing.
1258
1259**Safety:** The agent never deletes, archives, or merges anything. It only adds or updates. If the summary has nothing vault-worthy, it exits without touching the vault.
1260
1261---
1262
1263## Write-Time AI-First Validator (PostToolUse Hook)
1264
1265A non-blocking validator that fires after every `Write` or `Edit` on a markdown file inside the configured vault. It warns when the file fails the AI-first rule (missing required frontmatter, missing `## For future agent` preamble, broken YAML) and surfaces the warning back to the active agent on stderr so it can repair the note in the same turn.
1266
1267**What it checks:**
12681. The file has frontmatter delimiters (`--- ... ---`)
12692. No tabs in frontmatter (YAML requires spaces)
12703. Required AI-first fields present: `date:`, `type:`, `tags:`, `ai-first: true`
12714. The body contains a `## For future agent` preamble, or its Obsidian callout form `> [!info]- For future agent` (rule #2 of [`references/ai-first-rules.md`](references/ai-first-rules.md))
1272
1273**What it skips:**
1274- Files outside `OBSIDIAN_VAULT_PATH`
1275- Files under `raw/`, `templates/`, `_export/`, `.obsidian/`, `.git/`, `.trash/`, `.claude/` (slash-command copies and settings are not notes - #249)
1276- Payloads with no `tool_name` (nothing fired)
1277
1278**What it refuses to skip silently:** a payload that names a tool but carries no path key the hook knows (`file_path`, `filePath`, `notebook_path`). The matcher fired, so a write happened and went unchecked; the hook prints one stderr line naming the tool and the payload keys and exits 1 (non-blocking, the write stands) instead of exiting 0 and looking like "not a vault file".
1279
1280**Setup:**
1281
12821. Make the script executable (one-time):
1283 ```bash
1284 chmod +x ~/.claude/skills/obsidian-second-brain/hooks/validate-ai-first.sh
1285 ```
1286
12872. `OBSIDIAN_VAULT_PATH` must already be set in `~/.claude/settings.json` (the background agent setup above covers this).
1288
12893. Add the `PostToolUse` hook to `~/.claude/settings.json`:
1290 ```json
1291 {
1292 "hooks": {
1293 "PostToolUse": [
1294 {
1295 "matcher": "Write|Edit",
1296 "hooks": [
1297 {
1298 "type": "command",
1299 "command": "bash ~/.claude/skills/obsidian-second-brain/hooks/validate-ai-first.sh"
1300 }
1301 ]
1302 }
1303 ]
1304 }
1305 }
1306 ```
1307
1308**Behavior:** Non-blocking. If a write fails the AI-first rule, the hook emits JSON with `systemMessage` (shown to the user) and `decision`/`reason` plus `additionalContext` (fed to the model), one line per missing requirement, with the warning mirrored to stderr for logs. The agent can re-write the file in the same conversation turn to fix it. The original write is NOT reverted.
1309
1310**Other platforms (Codex CLI / Gemini CLI / OpenCode):** The hook ships only in the `claude-code` build (`dist/claude-code/hooks/`); the other platform builds do not include a `hooks/` directory. If your platform has a post-write hook system, wire it yourself from the source repo: [`hooks/validate-ai-first.hook.yaml`](hooks/validate-ai-first.hook.yaml) is the platform-neutral spec and `hooks/validate-ai-first.sh` the implementation. Without host wiring, the AI-first rule is enforced by the command instructions alone.
1311
1312---
1313
1314## Per-Project Vaults (multi-repo workflows)
1315
1316The default install path (`scripts/setup.sh`) writes `OBSIDIAN_VAULT_PATH` into `~/.claude/settings.json` (global). That assumes one machine = one vault. If you work across multiple repos and want each to have its own dedicated vault - or want to keep work and personal vaults separate without manually swapping config - use Claude Code's per-project settings to override the global setting on a per-directory basis.
1317
1318**How it works:** every hook in this skill (`hooks/load_vault_context.py`, `hooks/validate-ai-first.sh`, `hooks/obsidian-bg-agent.sh`) reads `OBSIDIAN_VAULT_PATH` from process env at fire-time. Claude Code merges `.claude/settings.json` from the current project directory on top of `~/.claude/settings.json`, so a project-scoped env block overrides the global one for any session launched from that directory.
1319
1320**Setup per repo:**
1321
13221. Bootstrap each vault once: `bash scripts/setup.sh` for the first vault (writes the global default), then `python scripts/bootstrap_vault.py --path ~/vaults/repo-b --name "Your Name"` for any additional vaults (skips the global config step).
1323
13242. In each repo where you want a non-default vault, create `.claude/settings.json`:
1325
1326 ```json
1327 {
1328 "env": {
1329 "OBSIDIAN_VAULT_PATH": "/Users/you/vaults/repo-a-vault"
1330 }
1331 }
1332 ```
1333
13343. Restart Claude Code (or open a new session in that directory). All slash commands, hooks, and scripts will now operate on the project-specific vault.
1335
1336**What this does NOT give you:** isolation within a single vault. The skill has no `--scope` concept - `/obsidian-find`, `/obsidian-recap`, and `/obsidian-emerge` scan the entire configured vault. If you want multiple projects sharing one vault, you can organize them by top-level folders for visual grouping, but commands will still see across folders. A real `--scope` refactor is tracked in discussion threads - open a discussion if this is your use case.
1337
1338**Slash commands and hooks are still globally installed.** Only the `OBSIDIAN_VAULT_PATH` env var is per-project. You do not need to re-symlink commands or re-register hooks per repo.
1339
1340---
1341
1342## Reference Files
1343
1344- `references/vault-schema.md` - Complete folder structure + frontmatter specs for all note types
1345- `references/write-rules.md` - Detailed writing, linking, and formatting rules
1346- `references/claude-md-template.md` - Template for generating a vault's `_CLAUDE.md`
1347
1348## Scripts
1349
1350- `scripts/setup.sh` - One-command installer (wires hook + env var + MCP)
1351- `scripts/bootstrap_vault.py` - Bootstrap a complete vault from scratch
1352- `scripts/vault_health.py` - Audit a vault for structural issues