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

---
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//YYYY-MM-DD-.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

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