---
name: vault
description: 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
---

# 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/<name>/ 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/<name>/YYYY-MM-DD-<type>.md` |
| Save inbox | "save to inbox" | `projects/_inbox/YYYY-MM-DD-<desc>.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 `<vault-path>/projects/<project-name>/`
4. Infer doc type from conversation (brainstorming → brainstorm, planning → plan)
5. Generate filename: `YYYY-MM-DD-<type>.md`
6. Write frontmatter with `status: planning`
7. Add `## Related Documents` section
8. Confirm: "Created projects/<name>/YYYY-MM-DD-<type>.md"

### Save to Inbox

**Trigger:** "save to inbox" / "quick idea"

1. Determine vault path from conversation context
2. Create in `<vault-path>/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/<project-name>/`
6. Move selected files → rename if needed (e.g., -idea.md → -initial-brainstorm.md)
7. Update frontmatter:
   - `project: inbox` → `project: <project-name>`
   - 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 `<vault-path>/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:**
```
<vault-path>/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`