laurigates/vault-tags

Vault Tag Taxonomy

When to Use This Skill

| Use this skill when... | Use the alternative instead when... | |---|---| | Consolidating drifted/duplicate tags (🔒/security vs 🔍/security) across many notes | Setting one property on one live note via the running CLI — use properties | | Collapsing bare emoji placeholder tags like 📝 or 🌱 | Cleaning the surrounding YAML structure (null entries, missing blocks) — use vault-frontmatter | | Reducing over-tagged notes to 2-3 canonical tags | Grouping tag-aligned notes into a hub MOC — use vault-mocs |

A two-level tag scheme built around emoji-prefixed categories. Consistent tagging enables reliable search (tag:#🛠️/neovim), Dataview queries, and MOC coverage analysis.

Canonical Categories

| Emoji | Category | Examples | |-------|----------|----------| | 🛠️ | Development tools | 🛠️/neovim, 🛠️/git, 🛠️/terminal | | 💻 | Programming languages | 💻/python, 💻/rust, 💻/typescript | | ☁️ | Systems & infrastructure | ☁️/kubernetes, ☁️/docker, ☁️/linux | | 🔌 | Hardware & IoT | 🔌/esp32, 🔌/arduino, 🔌/electronics | | 🏠 | Home automation | 🏠/home-assistant, 🏠/esphome | | 🎮 | Entertainment | 🎮/games, 🎮/tabletop | | 🤖 | AI & ML | 🤖/comfyui, 🤖/llm, 🤖/ai-tools |

Note-Type Tags

| Tag | Meaning | |-----|---------| | 📝/moc | Map of Content | | 📝/notes | General note | | 📝/collection | Resource collection | | 📝/guide | How-to guide | | 📋/reference | Quick reference material | | 📋/commands | Command-line reference | | 📅/daily | Daily note |

Consolidation Table

When auditing reveals duplicate or drifted tags, apply these rewrites:

| Drift / Legacy | Canonical | Reason | |----------------|-----------|--------| | 🗺️ | 📝/moc | Old MOC marker | | 🔒/security | 🔍/security | Standardize on search emoji | | 🎨/comfyui | 🤖/comfyui | ComfyUI lives under AI | | gaming | 🎮/games | Flat → emoji-prefixed | | neovim (flat) | 🛠️/neovim | Flat → emoji-prefixed | | softwaredevelopment | 💻/development | Concatenated → slash | | project / projects | 💡/project | Pick one plural form | | Hardware (title-cased) | 🔌/hardware | Lowercase, emoji-prefixed |

Bare Placeholder Tags

The tags 📝, 🌱, 📝/🌱 are no-ops left over from unfinished template rendering. Treatment:

• If the note has other useful tags, remove the placeholder.
• If the note has only a placeholder, leave it flagged for manual review — removing would leave the note untagged, which is a different (but real) problem.

Over-Tagging

More than 5 tags suggests the note mixes topics and should be split, or that tags are being used as keywords. Bring it down to 2–3 by asking "what single category is this note about?" — the rest go in the body as text.

Detection

# Notes with a bare 📝 or 🌱 tag on its own line
rg -l '^\s*-\s+(📝|🌱|📝/🌱)\s*$' --glob '*.md'

# Notes with competing security prefixes
rg -l '🔒/security' --glob '*.md'
rg -l '🔍/security' --glob '*.md'

# Flat (non-emoji-prefix) tags
rg '^\s*-\s+[a-z][a-z0-9_-]+\s*$' --glob '*.md'

Offline Fallback (App Closed)

The detection methodology above is unchanged — only the data source changes when Obsidian (and its obsidian CLI / live tag index) is closed. The obsidian tags/tag queries in search-discovery are the live-index path; parsing the .md corpus directly with the rg Detection snippets above is the deterministic headless default, and for batch/scheduled audits it is often the better choice (reproducible, free of app/index state). vault-frontmatter already operates this way.

Tag taxonomy is pure frontmatter — read each note's YAML block between the leading --- fences and extract tags (and aliases / context where relevant); see vault-frontmatter for YAML-block mechanics. The consolidation and bare-placeholder passes need no running app: the rg snippets above read tags straight from the files.

Edit Pattern

For each note, use Edit with a small old_string / new_string that touches only the affected tag lines. Preserve indentation and the rest of the frontmatter block exactly.

When renaming a tag across the whole vault, batch into one commit titled fix(tags): consolidate 🔒/security → 🔍/security (N notes).

Anti-Patterns

• Do not invent new categories. Use the table above; propose additions via a conventional commit if truly needed.
• Do not use spaces inside tag values (AI tools → 🤖/ai-tools).
• Do not use multiple emoji in one tag (🛠️🔌/esp32 — pick one).
• Do not add tags purely for search — search works on content and filenames already.

Related Skills

• vault-frontmatter — general YAML repair patterns
• vault-mocs — how tag categories relate to MOCs
• search-discovery — runtime tag queries via Obsidian CLI