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

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:

---
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:

## 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

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