richfrem/obsidian-markdown-mastery

Dependencies

This skill requires Python 3.8+ and standard library only. No external packages needed.

To install this skill's dependencies:

pip-compile ./requirements.in
pip install -r ./requirements.txt

See ./requirements.txt for the dependency lockfile (currently empty — standard library only).

---

Obsidian Markdown Mastery (Protocol 129 COMPLIANT)

Status: Active Author: Obsidian Integration Plugin Domain: Obsidian Integration

Core Mandate

The obsidian-markdown-mastery skill is responsible for the exact formatting, extraction, and validation of Obsidian-flavoured Markdown. It provides the low-level string manipulation that allows higher-order agents (like the Graph Traverser or JSON Canvas Architect) to safely interpret relational links without breaking the .md Vault.

CRITICAL ARCHITECTURAL RULE: All vault data manipulation MUST occur through deterministic Python scripts rather than agent-prompted regex. This skill defines the obsidian-parser module that performs these deterministic actions.

Agnosticism Enforcement: This module knows NOTHING about project-specific protocols, persistence layers, or external services. It only knows how to parse text into valid Obsidian links and block-quotes. Project-specific configuration (vault paths, injection points) is managed via the OBSIDIAN_VAULT_PATH environment variable.

Available Commands

Analyze Markdown Content

Extracts all Obsidian-specific metadata (links, embeds, blocks) from a given markdown file or string. Command: python ./parser.py analyze --file <path_to_md>

Inject Callout

Wraps a target text block in an Obsidian-flavored callout. Command: python ./parser.py callout --type <type> --title <title> --text <content>

The Parsed Syntax (Data Dictionary)

When manipulating strings via this module, the following formats are enforced:

1. Linking and Aliasing

• Standard Link: [[Note Name]]
• Heading Link: [[Note Name#Heading Name]]
• Block Link: [[Note Name#^block-id]]
• Aliased Link: [[Note Name|Display Text]]

2. Transclusion (Embeds)

• Standard Embed: ![[Note Name]] (Note the leading !)
• (The parser specifically categorizes these differently so graph mappers know they are transclusions, not semantic links).

3. Callouts

• Syntax:

  > [!type] Title
  > Content block goes here.
  

• Supported Types: info, warning, error, success, note.

Configuration Environment Variable

Other tools (such as protocol-manager and chronicle-manager) rely on the unified OBSIDIAN_VAULT_PATH environment variable to discover where the root of the Obsidian Vault resides. If missing, it defaults to the project root.