zhongwei/gh-fnichol-claude-code-plugins-plugins-obsidian
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
gh-fnichol-claude-code-plug…/skills/vault/SKILL.md
Zhongwei Li 440d018303 Initial commit
2025-11-29 18:27:22 +08:00

9.0 KiB
Raw Permalink Blame History

name, description
name description
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

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
Reference in New Issue View Git Blame Copy Permalink