Vault Health Skill

Workflow Position

code

[Point Claude at vault]
        |
    personal:obs-vault-health     <- YOU ARE HERE
        |
    [Mode: Quick | Standard | Deep]
        |
    [Analysis Phase] -> Tag scan -> Orphan scan -> Frontmatter scan
        |
    [Report: Issues Found]
        |
    [User confirms fixes]
        |
    [Apply fixes OR generate cleanup script]
        |
    Output: Health Report + Style Guide for vault

Overview

Comprehensive Obsidian vault maintenance skill combining three essential health checks:

•Tag Cleanup & Standardisation - Identify duplicates, inconsistent naming, enforce PARA prefix conventions
•Orphan Note Detection - Find unlinked notes, broken wiki-links, unused tags
•Frontmatter Standardisation - Ensure consistent YAML metadata across note types

Key Features:

•3 modes (Quick/Standard/Deep) for different maintenance needs
•
PARA methodology alignment with your folder structure:
- •0-Inbox → Capture point (new notes land here)
- •1-Projects → Active efforts with goals and deadlines
- •2-Areas → Ongoing responsibilities
- •3-Resources → Topic-based reference material
- •4-Archives → Completed/inactive items
- •5-Daily → Daily notes
•
Prefix tag system for Auto Note Mover:
- •#p/ → Projects (e.g., #p/leanix, #p/bcbs239)
- •#a/ → Areas (e.g., #a/capabilities, #a/school)
- •#r/ → Resources (e.g., #r/prompting)
- •domain/ → Business domain (e.g., domain/compliance)
- •client/ → Client (e.g., client/ey, client/jpmc)
- •tech/ → Technology (e.g., tech/ai, tech/python)
•Style guide generation for vault consistency
•Focus on consistency - primary goal is catching missing tags and links
•Non-destructive analysis with user confirmation before changes

When to Use

•Regular vault maintenance (weekly/monthly)
•Before major vault reorganisation
•After importing notes from another system
•When vault feels "messy" or hard to navigate
•Preparing vault for sharing or publishing

When to Skip

•Brand new vault (< 50 notes) - not enough data for patterns
•Just reorganised - wait a week to see how new structure works
•Time-critical work - save for dedicated maintenance time
•Shared vault - coordinate with collaborators first

The Process

Step 0: Determine Vault Location

Ask the user:

Where is your Obsidian vault located?

Please provide the full path to your vault directory.

Wait for answer before proceeding.

Step 1: Determine Mode

Ask the user:

What level of vault health check do you need?

Quick (5-10 minutes)

•Tag analysis only

•Top 10 issues

•Output: Quick report

Standard (15-30 minutes)

•Tags + Orphan detection + Basic frontmatter

•Full issue list with priorities

•Output: Health Report + Style Guide

Deep (30-60 minutes)

•All three scans + cross-reference validation

•Comprehensive audit with recommendations

•Output: Full Audit Report + Style Guide + Action Plan

Auto-escalate to Deep if ANY of these apply:

•Vault has 500+ notes
•Multiple authors/contributors
•Migrated from another system
•Never had a full audit

Wait for answer before proceeding.

Quick Mode

For regular maintenance. Tag analysis only.

Quick Pass: Tag Analysis

Scan vault for tags and identify:

PARA Prefix Compliance:

• Notes missing PARA prefix tags (p/, a/, r/, ar/)
• Notes with wrong prefix for their location
• Auto Note Mover trigger tags present and correct

Duplicate Detection:

• Case variations (Meeting, meeting, MEETING)
• Plural variations (project, projects)
• Hyphen/underscore variations (work-log, work_log)
• Typos (recieved, received)

Low-Value Tags:

• Tags used only once
• Tags used fewer than 3 times
• Overly generic tags (#important, #todo, #misc)

Structure Issues:

• Tags not using PARA prefix convention
• Inconsistent sub-tag naming under prefixes

Present findings:

markdown

## Quick Tag Analysis

**Vault:** [path]
**Total Tags:** X
**Issues Found:** Y

### PARA Prefix Compliance
| Issue | Count | Examples |
|-------|-------|----------|
| Missing PARA prefix | 15 | note1.md, note2.md |
| Wrong prefix for location | 3 | (in Projects/ but has a/ tag) |

### Auto Note Mover Alignment
- Notes that will move on next sync: X
- Notes missing trigger tags: Y

### Duplicates Found (merge recommended)
| Keep | Merge Into | Count |
|------|------------|-------|
| #p/project-alpha | #project-alpha, #p/alpha | 5 |

### Low-Value Tags (review for removal)
| Tag | Usage Count | Recommendation |
|-----|-------------|----------------|
| #misc | 2 | Remove or rename |

### Suggested Actions
1. Add PARA prefix tags to X notes
2. Merge Y duplicate tags
3. Review Z low-value tags

Ask: "Would you like me to apply these tag fixes? I'll show you each change before making it."

End of Quick Mode - Skip to Output section.

Standard Mode

For monthly reviews. Tags + Orphans + Frontmatter.

Pass 1: Tag Analysis (Same as Quick)

See Quick Mode. Report findings before continuing.

Pass 2: Orphan Detection

Scan vault for connectivity issues:

Unlinked Notes:

• Notes with no incoming links (nothing points to them)
• Notes with no outgoing links (they point to nothing)
• Notes with neither (completely isolated)

Broken Links:

• [[wiki-links]] pointing to non-existent notes
• [[wiki-links|aliases]] with broken targets
• Image/attachment links that don't resolve

Tag Orphans:

• Tags defined in frontmatter but never used elsewhere
• Tags used in body but note has no frontmatter tags field

Present findings:

markdown

## Orphan Analysis

### Isolated Notes (no links in or out)
| Note | Created | Last Modified | Recommendation |
|------|---------|---------------|----------------|
| random-thought.md | 2024-01 | 2024-01 | Archive or link |

### Notes with No Incoming Links (may be undiscoverable)
- project-ideas.md (consider linking from Projects MOC)
- meeting-2024-01-15.md (consider daily note link)

### Broken Wiki-Links
| Source Note | Broken Link | Suggestion |
|-------------|-------------|------------|
| index.md | [[Old Project]] | Delete or create note |

Report findings: "Orphan pass complete. Found X connectivity issues."

Pass 3: Frontmatter Standardisation

Check YAML frontmatter consistency:

Universal Fields (all notes should have):

• type (project, area, resource, meeting, index)
• tags (array with appropriate PARA prefix)
• date created (auto-generated: YYYY-MM-DD HH:MM:SS)
• date modified (auto-updated: YYYY-MM-DD HH:MM:SS)

Type-Specific Fields:

Project Notes (type: project):

• status (active, paused, completed, archived)
• priority (low, medium, high)
• startDate (YYYY-MM-DD)
• dueDate (YYYY-MM-DD)
• Tags include #p/project-name

Area Notes (type: area):

• status (ongoing, maintenance)
• Tags include #a/area-name

Resource Notes (type: resource):

• Tags include #r/topic-name
• Optional: domain/, tech/ tags

Meeting Notes (type: meeting):

• date (YYYY-MM-DD)
• participants (array)
• Tags include project (#p/) and optionally client/

Daily Notes:

• Filename is YYYY-MM-DD.md
• Located in 5-Daily/

Present findings:

markdown

## Frontmatter Analysis

### Missing Universal Fields
| Field | Notes Missing It | % of Vault |
|-------|------------------|------------|
| created | 45 | 23% |
| tags | 12 | 6% |

### Inconsistent Field Names
| Variations Found | Recommended Standard |
|------------------|---------------------|
| created, date created, dateCreated | created |
| modified, updated, date modified | modified |

### Type-Specific Gaps
- 15 meeting notes missing `attendees` field
- 8 project notes missing `status` field

Report findings: "Frontmatter pass complete. Generating style guide."

End of Standard Mode - Proceed to Output section.

Deep Mode

For comprehensive audit. All scans plus cross-reference validation.

Pass 1: Tag Analysis (Same as Quick)

See Quick Mode. Additional Deep checks:

• Tag taxonomy depth analysis (how nested?)
• Tag co-occurrence patterns (tags often used together)
• Suggested tag hierarchy restructure

Pass 2: Orphan Detection (Same as Standard)

See Standard Mode. Additional Deep checks:

• Link density analysis (average links per note)
• Hub notes identification (most linked-to notes)
• Suggested MOC (Map of Content) candidates

Pass 3: Frontmatter Standardisation (Same as Standard)

See Standard Mode. Additional Deep checks:

• Field value consistency (status values, date formats)
• Alias usage audit
• CSS class usage audit

Pass 4: Cross-Reference Validation

Internal Consistency:

• Dates in frontmatter match filename dates (for daily notes)
• Project statuses match actual activity (stale "active" projects)
• Tags in frontmatter appear in body (or vice versa)

External References:

• URLs in notes still valid (optional, can be slow)
• File paths for attachments valid
• Dataview queries return results

Naming Conventions:

• File names follow consistent pattern
• Folder structure logical and consistent
• No duplicate file names in different folders

Pass 5: Health Scoring

Generate overall vault health score:

markdown

## Vault Health Score

**Overall: B+ (82/100)**

| Category | Score | Weight | Notes |
|----------|-------|--------|-------|
| Tag Health | 75 | 25% | 15 duplicates, good structure |
| Connectivity | 90 | 25% | Low orphan rate, good linking |
| Frontmatter | 70 | 25% | Missing fields in 23% of notes |
| Consistency | 85 | 25% | Minor naming variations |

### Priority Actions (Impact vs Effort)
1. **High Impact, Low Effort:** Merge 15 duplicate tags
2. **High Impact, Medium Effort:** Add frontmatter to 45 notes
3. **Medium Impact, Low Effort:** Archive 8 isolated notes

End of Deep Mode - Proceed to Output section.

Output Format

Health Report (All Modes)

markdown

# Vault Health Report

**Vault:** [path]
**Date:** [date]
**Mode:** Quick | Standard | Deep
**Notes Scanned:** X

---

## Summary

| Category | Issues | Critical | High | Medium | Low |
|----------|--------|----------|------|--------|-----|
| Tags | X | 0 | 5 | 10 | X |
| Orphans | X | 0 | 2 | 8 | X |
| Frontmatter | X | 0 | 3 | 15 | X |
| **Total** | **X** | **0** | **10** | **33** | **X** |

---

## Critical Issues (Address Immediately)

None found.

---

## High Priority Issues

### 1. Duplicate Tags
[Details...]

### 2. Broken Wiki-Links
[Details...]

---

## Recommended Actions

1. [ ] Merge duplicate tags (15 minutes)
2. [ ] Fix broken links (10 minutes)
3. [ ] Add frontmatter to key notes (30 minutes)
4. [ ] Archive isolated notes (5 minutes)

---

## Next Health Check

Recommended: [date + 1 month] (Standard mode)

Style Guide (Standard/Deep only)

Generate and save to vault root as _vault-style-guide.md:

markdown

# Vault Style Guide

**Generated:** [date]
**Generator:** Claude (personal:obs-vault-health)
**Mode:** Standard | Deep

---

## Tag Conventions

### PARA Prefix System (Auto Note Mover)
| Prefix | Meaning | Example | Target Folder |
|--------|---------|---------|---------------|
| `#p/` | Project | `#p/leanix`, `#p/bcbs239` | `1-Projects/[name]` |
| `#a/` | Area | `#a/capabilities`, `#a/school` | `2-Areas/[name]` |
| `#r/` | Resource | `#r/prompting`, `#r/organization` | `3-Resources/[name]` |

### Additional Tag Categories
| Prefix | Usage | Examples |
|--------|-------|----------|
| `domain/` | Business domain | `domain/compliance`, `domain/banking` |
| `client/` | Client reference | `client/ey`, `client/jpmc`, `client/barclays` |
| `tech/` | Technology stack | `tech/ai`, `tech/python`, `tech/sql` |

### Naming Rules
- Use kebab-case: `#p/project-name` not `#p/projectName`
- Lowercase only
- Short but descriptive

---

## Frontmatter Templates

### Project Note
```yaml
---
type: project
status: active
tags: [p/project-name]
title: Project Title
date created: YYYY-MM-DD HH:MM:SS
date modified: YYYY-MM-DD HH:MM:SS
priority: medium
startDate: YYYY-MM-DD
dueDate: YYYY-MM-DD
---

Area Note

yaml

---
type: area
status: ongoing
tags: [a/area-name]
title: Area Title
date created: YYYY-MM-DD HH:MM:SS
date modified: YYYY-MM-DD HH:MM:SS
---

Resource Note

yaml

---
type: resource
tags: [r/topic-name]
title: Resource Title
date created: YYYY-MM-DD HH:MM:SS
date modified: YYYY-MM-DD HH:MM:SS
---

Meeting Note

yaml

---
type: meeting
tags: [meeting, p/project-name, client/client-name]
title: Meeting Title
date: YYYY-MM-DD
date created: YYYY-MM-DD HH:MM:SS
date modified: YYYY-MM-DD HH:MM:SS
participants: []
---

Naming Conventions

Files

•Daily notes: YYYY-MM-DD.md
•Dated notes: YYYY-MM-DD - Title.md
•Project/Area notes: Title.md (descriptive, spaces OK)
•Meeting notes: YYYY-MM-DD - Meeting Topic.md

Folders (PARA Structure)

code

/
├── 0-Inbox/           # Capture point for new notes
├── 1-Projects/        # Active efforts with goals
│   ├── 0-Dev/         # Development projects
│   └── [ProjectName]/ # Individual projects
├── 2-Areas/           # Ongoing responsibilities
│   ├── Cap Markets/   # Work area
│   └── [AreaName]/    # Individual areas
├── 3-Resources/       # Reference material
│   ├── dev/           # Development resources
│   └── [TopicName]/   # Topic-based
├── 4-Archives/        # Completed/inactive
├── 5-Daily/           # Daily notes
├── Templates/         # Note templates
├── Clippings/         # Web clippings
└── attachments/       # Embedded files

Auto Note Mover Rules

Notes with these tags will auto-move:

Tag	Destination Folder
`#p/leanix`	`1-Projects/LeanIX/`
`#p/bcbs239`	`1-Projects/2-JPMC_BCBS239/`
`#a/capabilities`	`2-Areas/Cap Markets/Capabilities/`
`#a/peopleteam`	`2-Areas/Cap Markets/PeopleTeam/`
`#a/school`	`2-Area/schoolAdmin/`
`#r/prompting`	`3-Resources/prompting/`

Excluded folders: Templates/

Linking Conventions

•Use wiki-links: [[Note Name]]
•Use aliases for readability: [[Note Name|display text]]
•Every project/area should have an index note
•Link meeting notes to their project
•Daily notes should link to relevant projects/tasks

code


---

## After Vault Health

1. **Review the report** with priorities in mind
2. **Apply quick wins first** (tag merges, obvious fixes)
3. **Save the style guide** for future reference
4. **Schedule next check** (Quick: weekly, Standard: monthly, Deep: quarterly)
5. **Share style guide** if collaborating with others

> "Vault health check complete! Mode: [Quick|Standard|Deep]"
>
> **Issues found:** X total (Y high priority)
>
> **Outputs generated:**
> - Health Report
> - Style Guide (Standard/Deep)
>
> **Recommended next check:** [date]

---

## Key Principles

- **Analysis before action** - Never modify without user confirmation
- **Non-destructive by default** - Generate scripts/reports, don't auto-apply
- **Incremental improvement** - Small regular maintenance beats big overhauls
- **Style guide is source of truth** - Document decisions for consistency
- **Quick mode for habits** - Low-friction regular checks catch issues early