obsidian

name	obsidian
description	Author, review, and optimize notes and structure using Obsidian-flavored Markdown (OFM) and vault-safe conventions. WHEN: User asks for vault optimization, note refactors, OFM syntax, linking/backlinks, properties, or note organization. WHEN NOT: Generic markdown only (no Obsidian features), or non-documentation coding tasks.
allowed-tools	Read, Grep, Glob, Bash
version	1.2.0
updated	"2026-02-23T00:00:00.000Z"

Obsidian Skill

Use this skill to produce clean, deterministic Obsidian notes with stable links, predictable metadata, and maintainable vault structure.

Quick Start

1. Confirm scope

• New note
• Note refactor
• Link graph cleanup
• Vault structure cleanup
• Vault migration or settings transfer

2. Baseline vault health before edits

• Count unresolved links.
• Count orphans/deadends.
• Identify hub/index notes.
• Confirm canonical folder paths.

3. Apply OFM-safe edits

• Use [[Wiki Links]] for internal references.
• Use ![[Embeds]] for note/file embeds.
• Use YAML properties only when metadata is meaningful.
• Keep headings shallow and scan-friendly.
• Use callouts (> [!note], > [!warning]) for critical context.

4. Verify after edits

• No broken wikilink targets.
• Backlinks exist for all operational notes.
• Tags are normalized.
• Footer/header navigation is consistent where required.

MCP Bridge (Implementation Boundary)

This skill is the vault quality layer; it relies on the MCP transport for execution.

• Tooling integration: use MCP server name obsidian (configured as @mauricio.wolff/mcp-obsidian@latest).
• Use MCP methods for all vault mutations and reads (read_note, write_note, delete_note, move_note, list_directory, search_notes, manage_tags, get/update_frontmatter).
• Keep this skill's workflow (link audits, naming conventions, backlink checks, migration checklists) as the human-facing standard.
• Keep MCP usage technical and predictable: deterministic paths, explicit confirmations, no invented note paths.

---

Official References

Topic	URL
Syntax	https://help.obsidian.md/syntax
Advanced Syntax	https://help.obsidian.md/advanced-syntax
Obsidian Flavored Markdown	https://help.obsidian.md/obsidian-flavored-markdown
Tags	https://help.obsidian.md/tags
Attachments	https://help.obsidian.md/attachments
Callouts	https://help.obsidian.md/callouts
Folding	https://help.obsidian.md/folding
Multiple Cursors	https://help.obsidian.md/multiple-cursors
Properties	https://help.obsidian.md/properties
Edit and Read	https://help.obsidian.md/edit-and-read
Editing Shortcuts	https://help.obsidian.md/editing-shortcuts
Embed Web Pages	https://help.obsidian.md/embed-web-pages
HTML Content	https://help.obsidian.md/Editing+and+formatting/HTML+content
Links	https://help.obsidian.md/links
Aliases	https://help.obsidian.md/aliases
Embeds	https://help.obsidian.md/embeds
File Formats	https://help.obsidian.md/file-formats
Configuration Folder	https://help.obsidian.md/configuration-folder
Data Storage	https://help.obsidian.md/data-storage
Manage Notes	https://help.obsidian.md/manage-notes
Manage Vaults	https://help.obsidian.md/manage-vaults

---

When to Use

Scenario	Use This Skill?	Instead Use
Convert plain Markdown into Obsidian style	Yes	-
Add properties/tags/aliases to notes	Yes	-
Build note templates for vault workflows	Yes	-
General repo coding/debugging	No	ix-codemode
Browser-based portal operations	No	browser-agent

---

Vault Management Rules

Use these rules when users ask to optimize or reorganize a vault:

1. Treat the vault as a file-system folder containing notes, attachments, and .obsidian settings.
2. Use the Vault switcher model for user-facing guidance (Manage Vaults, Open folder as vault, Remove from list).
3. Assume renaming a vault renames the underlying folder.
4. Prefer explicit migration checklists when moving vaults between locations.
5. For settings transfer, copy .obsidian from source vault root to destination vault root.
6. Avoid risky move targets when sync collisions are likely; validate contents after move.

Note Management Rules

1. Prefer stable, human-readable file names.
2. Keep one canonical note name per concept.
3. Use links instead of repeated prose across notes.
4. Rename notes through Obsidian-aware flows when possible so links auto-update.
5. Keep deletion behavior explicit (system trash, .trash, or permanent).

---

Core Rules

Linking

• Prefer [[Note Name]] for internal references.
• Use aliases when needed: [[Canonical Note|Display Text]].
• For known hub/index notes, prefer fully qualified paths when ambiguity exists.
• Keep note titles stable and avoid unnecessary renames.

Embeds

• Notes: ![[Other Note]]
• Attachments: ![[image.png]] or ![[doc.pdf]]
• Web pages: use explicit external links where embed support is uncertain.

Tags

• Keep tags lowercase and consistent (#ix, #utility, #handoff).
• Avoid duplicate variants (#IX and #ix).

Properties

• Use YAML frontmatter when metadata is needed:

  ---
  title: Note Title
  tags: [ix, handoff]
  aliases: [Alt Name]
  status: draft
  updated: 2026-02-23
  ---
  

Callouts

• Use callouts for operational risk and next action:

  > [!warning] Approval Gate
  > Human approval required before external submission.
  

---

Common Workflows

Workflow A: Normalize Existing Notes

1. Convert inline manual links to [[Wiki Links]].
2. Add/normalize frontmatter properties.
3. Consolidate tags to canonical set.
4. Replace ad-hoc emphasis blocks with callouts.
5. Add navigation backlinks to relevant hub notes.

Workflow B: Build an Ops Note Template

1. Add required properties (status, owner, updated, tags).
2. Add fixed sections (Context, Current State, Risks, Next Actions).
3. Include reusable callouts for blockers and approvals.
4. Add cross-links to index/hub notes.

Workflow C: Vault Hygiene Pass

1. Detect orphan notes (no inbound links).
2. Fix broken embeds/attachments.
3. Normalize naming conventions.
4. Ensure hub/index notes connect major areas.
5. Run unresolved + backlink checks after edits.

Workflow D: Vault Move / Clone Safety

1. Capture source vault path and destination path.
2. Confirm backup or snapshot exists.
3. Move/open vault in new location.
4. Validate note count, unresolved links, and critical hub notes.
5. Re-enable community plugins if restricted mode is active.

---

Validation Checklist

• Links resolve to existing notes.
• No accidental [[|]] or malformed links.
• Required hub notes have backlinks.
• Headers and footers follow vault conventions.
• YAML frontmatter is parseable.
• Deleted/renamed notes have no stale references.

---

Output Standard

When generating or editing notes:

• Keep Markdown valid and readable in both edit and read mode.
• Favor concise headings and short paragraphs.
• Ensure every operational recommendation is traceable to note evidence.
• Do not invent links/files that do not exist.

Included Examples

• examples/vault-optimization-checklist.md
• examples/utility-note-template.md
• examples/vault-migration-runbook.md
• examples/index-note-template.md