Initial commit

2025-11-29 18:27:22 +08:00
commit 440d018303
5 changed files with 843 additions and 0 deletions
--- a/skills/vault/SKILL.md
+++ b/skills/vault/SKILL.md
@@ -0,0 +1,270 @@
+---
+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`