# Vault > Use when user says "save this", "create project", "promote from inbox" - manages Obsidian vault documentation with frontmatter (project/status/type/created), file naming (YYYY-MM-DD-name.md), wikilinks, and project structure in projects/ folders - Skill: `tomevault-io/vault-2` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/vault-2` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/vault-2/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Docs & Writing - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/vault-2 --- # Obsidian Vault Operations ## Overview Direct file system management for Obsidian project documentation. Enforces YYYY-MM-DD-name.md naming, generates frontmatter, maintains wikilinks, organizes into projects// and _inbox/. **For project linking features** (CLAUDE.local.md integration, dual locations, automatic startup), see the `project-linking` skill. ## Configuration **Vault path:** Look for "Primary vault:" in conversation context (from CLAUDE.md). - Use the most recent occurrence if multiple are present (user override takes precedence) - Default: `~/Obsidian/vault` if not specified - Expand `~` to user's home directory before using ## When to Use **User triggers:** - "Save this" / "create project" / "save to inbox" - "Create a [design/plan/brainstorm] doc for [project]" - "Promote that note to a project" - "Update [doc] in [project]" - "List projects" / "show me what's in [project]" **Use this skill for:** Project documentation, design docs, brainstorms, plans, retrospectives **Don't use for:** Code documentation (use project CLAUDE.md), one-off notes outside vault **Note:** If session has CLAUDE.local.md with project linking, use `project-linking` skill instead for advanced features. ## Quick Reference | Operation | Command Pattern | Result | |-----------|----------------|--------| | New project | "save as new project" | `projects//YYYY-MM-DD-.md` | | Save inbox | "save to inbox" | `projects/_inbox/YYYY-MM-DD-.md` | | Add to project | "create [type] doc for [project]" | New doc + wikilinks to related | | Update doc | "update [doc] in [project]" | Edit + `updated: YYYY-MM-DD` frontmatter | | Promote inbox | "promote to project" | Move + update frontmatter + rename | | List projects | "list projects" | Show all with status (skip _inbox) | | Show contents | "what's in [project]" | List docs chronologically | | Update status | "mark [project] as active" | Update all doc frontmatter | | Validate | "check frontmatter" | Report missing/invalid fields | **Conventions:** - Filename: `YYYY-MM-DD-descriptive-name.md` (lowercase, hyphens) - Links: Wikilinks `[[filename]]` (no .md, no path if same folder) - Always add `## Related Documents` section to project docs ## Frontmatter **Required fields:** ```yaml --- project: project-name # Matches folder name or "inbox" status: planning # planning|active|paused|completed|archived type: brainstorm # brainstorm|design|plan|notes|retrospective created: YYYY-MM-DD # File creation date --- ``` **Optional fields:** - `updated: YYYY-MM-DD` - Added when document revised (filename stays same) - `promoted: YYYY-MM-DD` - Added when moved from inbox to project **Valid values:** - **status:** planning, active, paused, completed, archived - **type:** brainstorm, design, plan, notes, retrospective ## Core Operations ### Create New Project **Trigger:** "save this as a new project" 1. Determine vault path from conversation context 2. Ask for project name → validate (lowercase, hyphens, no spaces) 3. Create `/projects//` 4. Infer doc type from conversation (brainstorming → brainstorm, planning → plan) 5. Generate filename: `YYYY-MM-DD-.md` 6. Write frontmatter with `status: planning` 7. Add `## Related Documents` section 8. Confirm: "Created projects//YYYY-MM-DD-.md" ### Save to Inbox **Trigger:** "save to inbox" / "quick idea" 1. Determine vault path from conversation context 2. Create in `/projects/_inbox/` 3. Use descriptive filename from content 4. Frontmatter: `project: inbox`, `status: planning`, `type: notes` 5. Confirm creation ### Add Document to Existing Project **Trigger:** "create a [design/plan] doc for [project-name]" 1. Search `projects/` for matching folder 2. If not found → ask to clarify or create new project 3. If multiple matches → present options 4. Create new doc in project folder 5. Search vault for related docs 6. Add inline wikilinks where relevant 7. Add `## Related Documents` section with links: `[[YYYY-MM-DD-filename]]` 8. Confirm creation + report links added ### Update Existing Document **Trigger:** "update the [doc] in [project]" 1. Find document in project folder 2. Read current contents 3. Make requested updates 4. Add/update `updated: YYYY-MM-DD` in frontmatter 5. **Preserve filename** (creation date unchanged) 6. Confirm what changed ### Promote from Inbox **Trigger:** "promote that note to a project" / "make this a proper project" 1. Identify inbox note from conversation context 2. Search `_inbox/` for related notes (similar topics, keywords) 3. Present related notes → ask which to include 4. Ask for project name 5. Create `projects//` 6. Move selected files → rename if needed (e.g., -idea.md → -initial-brainstorm.md) 7. Update frontmatter: - `project: inbox` → `project: ` - Add `promoted: YYYY-MM-DD` - Update `type` if needed (ask user or infer) 8. Confirm with list of moved files ### List Projects **Trigger:** "list projects" / "show me all projects" 1. Determine vault path from conversation context 2. Read `/projects/` (skip `_inbox/`) 3. For each project, read one doc to get status 4. Sort by status: active → planning → paused → completed → archived 5. Show count of documents per project **Output:** ``` Active Projects: - project-name (3 docs) Planning: - another-project (1 doc) ``` ### Show Project Contents **Trigger:** "what's in [project]" / "show me [project]" 1. Find project folder 2. List all documents with types and statuses from frontmatter 3. Present chronologically **Output:** ``` project-name (status: active): - 2025-11-07-initial-brainstorm.md (brainstorm) - 2025-11-10-design-doc.md (design) ``` ### Update Project Status **Trigger:** "mark [project] as active" / "set status to completed" 1. Find project folder 2. Read all documents 3. Update `status` field in all frontmatter 4. Confirm count of documents updated ### Validate Frontmatter **Trigger:** "check [project] frontmatter" / "validate frontmatter" 1. Find project folder → read all documents 2. Check each has: project, status, type, created 3. Verify `project` matches folder name 4. Verify `status` in valid values 5. Verify `type` in valid values 6. Verify dates are YYYY-MM-DD format 7. Report issues found **Auto-validate before creating any file.** ## Structure & Naming **Directory:** ``` /projects/ _inbox/ # Quick captures project-name/ # One folder per project YYYY-MM-DD-desc.md ``` **Naming rules:** - **Files:** `YYYY-MM-DD-descriptive-name.md` (lowercase, hyphens, concise) - **Projects:** `project-name` (lowercase, hyphens, matches folder) - **No spaces or underscores** **Examples:** - `obsidian-integration/2025-11-07-initial-brainstorm.md` - `api-refactoring/2025-11-08-design-doc.md` ## Linking **Internal:** `[[YYYY-MM-DD-filename]]` (no .md, no path if same folder) **External:** `[text](url)` **Always add to project docs:** ```markdown ## Related Documents - [[YYYY-MM-DD-brainstorm]] - Brief description - [[YYYY-MM-DD-design]] - Brief description ``` **Auto-linking:** - Add inline wikilinks where contextually relevant - Search vault when creating new docs - Link to related project docs in Related Documents section ## Pre-flight Checks **Before ANY file operation:** - [ ] Path exists or can be created - [ ] Filename matches `YYYY-MM-DD-name.md` - [ ] Frontmatter has: project, status, type, created - [ ] Dates are `YYYY-MM-DD` format - [ ] Status/type are valid values **Before updates:** - [ ] File exists → read current contents - [ ] Preserve creation date in filename (only update frontmatter) ## Common Mistakes | Problem | Solution | |---------|----------| | Project not found | Search partial matches → offer to create → list available | | Invalid frontmatter | Report issue → fix before proceeding | | File exists | Ask to update in-place or use different filename | | Permission denied | Report error → suggest checking vault path in ~/.claude/CLAUDE.md | | Vault path not found | Check for "Primary vault:" in context → use default ~/Obsidian/vault | | Wrong date in filename | Preserve creation date (filename) when updating → only change `updated` | ## Example **User:** "Save this brainstorm as a new project called obsidian-integration" **You:** Create `projects/obsidian-integration/2025-11-07-initial-brainstorm.md` with frontmatter **User:** "Create a design doc for obsidian-integration" **You:** Create `2025-11-08-architecture-design.md`, link to `[[2025-11-07-initial-brainstorm]]` **User:** "Promote that git-worktrees note from inbox to a project" **You:** 1. Found `_inbox/2025-11-07-git-worktrees-idea.md` 2. Create `projects/git-worktrees/` 3. Move and rename → `2025-11-07-initial-brainstorm.md` 4. Update frontmatter: `project: git-worktrees`, add `promoted: 2025-11-08` --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/fnichol) — claim your Tome and manage your conversions.