Guide · Agent skill
How to use the Obsidian Markdown Syntax agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The obsidian-markdown skill teaches an AI agent Obsidian's note syntax: YAML properties, wikilinks, embeds, callouts, tags, highlights, block references, math and Mermaid diagrams. It is for people who keep notes in Obsidian and want the agent to explain that syntax, draft notes in it, or check a drafted note for broken links and formatting errors. This guide covers what the skill does, how to install it, how to trigger it, what it needs and what to watch for.
Obsidian Markdown SyntaxAgriciDaniel/claude-obsidian · MIT Download the skill Quick start
- 1Download the ZIP. Download the obsidian-markdown skill ZIP from this page. It contains SKILL.md.
- 2Unzip into a skills folder. Unzip it into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder to limit it to that project.
- 3Or upload it in the apps. In the Claude apps, go to Settings → Capabilities → Skills and upload the ZIP.
- 4Check the requirements. Confirm Python 3 is installed and that the claude-obsidian product is installed locally if you plan to request vault edits.
- 5Ask with Obsidian in the request. Ask for explanation, a drafted note or a validation check, naming Obsidian explicitly.
- 6Review before approving edits. For vault changes, read the inspected bundle diff and only then approve the apply step.
What the skill makes the agent do
Once installed, the agent knows Obsidian's special note syntax. It can explain a piece of syntax, draft a complete note in that syntax, or validate a drafted note. Validation covers parsing the YAML property block, checking that internal link and heading targets can be verified locally, and confirming that code fences and callout quoting are balanced.
The skill is scoped to Obsidian syntax. Its own instructions say it should not handle general Markdown or broad vault operations, and it treats the official Obsidian Help site as the reference for detailed or version-sensitive questions.
- Properties: flat YAML with YYYY-MM-DD dates and quoted wikilinks inside YAML
- Wikilinks and embeds, such as [[Note Name]], [[Note Name|Display text]] and ![[diagram.png|480]]
- Callouts, including collapsed (-) and expanded (+) forms
- Tags, highlights, comments, block references, inline and block math, and Mermaid diagrams
Install the obsidian-markdown skill
Download the skill ZIP from this page. The package contains a single file, SKILL.md. Then choose one of two ways to install it.
For a personal install, unzip the folder into ~/.claude/skills/. To limit it to one project, unzip it into that project's .claude/skills/ folder. You can also upload the ZIP in the Claude apps under Settings → Capabilities → Skills.
- Personal: ~/.claude/skills/
- Single project: the project's .claude/skills/ folder
- Claude apps: Settings → Capabilities → Skills, then upload the ZIP
Meet the requirements before you rely on it
Answering syntax questions needs only the skill itself, but the skill's file points to a local product root. The skill expects the claude-obsidian product to be installed locally, with its scripts and wiki/references files present. Python 3 is needed because the edit path runs scripts/claude-obsidian.py. A local Obsidian vault path is required only if you request vault edits.
The skill does not use the network, but it does run scripts.
- Python 3
- The claude-obsidian product installed locally, with its scripts and wiki/references files
- A local Obsidian vault path, only if you request vault edits
Trigger the skill with clear requests
The skill is meant to activate when you explicitly ask for Obsidian note formatting or syntax help. Name Obsidian and say what you want. General Markdown questions are outside its scope.
For a read-only answer, ask a syntax question. For a drafted note, describe the note and ask for it in Obsidian format. For a check, paste the note and ask the agent to validate it.
- Explain: 'Explain how Obsidian block references work.'
- Draft: 'Draft an Obsidian note about retrieval with YAML properties and a related link to [[Retrieval]].'
- Validate: 'Check this Obsidian note for broken wikilinks and formatting errors.'
How vault edits are approved
If you ask the agent to change your vault, it does not write the note directly. It drafts the complete note, builds a reviewable transaction bundle with targets limited to wiki/ paths, and shows the bundle for inspection. Only after you approve does it apply the change through the repository's transaction tooling. The commands below come from the skill file.
Read the diff before approving. Approving without reading it can still alter or remove wiki pages. After an applied edit, the agent is expected to report the transaction operation ID and the exact changed paths.
- Inspect: python3 "$CORE" transaction inspect "$BUNDLE" --vault "$VAULT"
- Apply after approval: python3 "$CORE" transaction apply "$BUNDLE" --vault "$VAULT" --approved-plan-sha256 "$APPROVAL_SHA256"
PRODUCT_ROOT=/absolute/path/to/installed/claude-obsidian
CORE="$PRODUCT_ROOT/scripts/claude-obsidian.py"
test -f "$CORE"Tips for cleaner Obsidian notes
Match wikilink targets to filenames exactly. If a basename is ambiguous, use a vault-relative folder path. Use standard Markdown links for external URLs and wikilinks only for notes in your vault.
Tags need at least one non-numeric character. A numeric-only tag is invalid even when quoted, so use something like year/2026 or store a number in a year property instead.
- Use block lists for properties rather than inline YAML arrays
- Do not nest objects in generated properties
- Keep custom callout types already in your vault; the skill is told not to rewrite them
- Avoid HTML when native Markdown is enough
What people use it for
- Drafting a new concept note with YAML properties, aliases and related wikilinks
- Checking a drafted note for broken wikilinks, heading references and unbalanced callouts
- Adding callouts such as warnings or open questions to an existing note's format
- Writing a Mermaid flowchart or math block inside a note that follows Obsidian conventions
Frequently asked questions
How do I install the obsidian-markdown skill?
Download the ZIP from this page and unzip it into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder. You can also upload the ZIP in the Claude apps under Settings → Capabilities → Skills.
Is the obsidian-markdown skill free?
The skill is listed under the MIT licence. Check the repository's licence file for the full terms before reuse.
What does the obsidian-markdown skill require?
It requires Python 3 because the edit path runs scripts/claude-obsidian.py. It also expects the claude-obsidian product installed locally with its scripts and wiki/references files. A local Obsidian vault path is needed only for vault edits.
Does the skill edit my Obsidian vault directly?
No. It builds a reviewable transaction bundle limited to wiki/ paths, shows it for inspection, and applies it only after you approve. Read the diff before approving, since approval alone can still change or remove wiki pages.
Why doesn't the skill trigger on general Markdown questions?
It is scoped to Obsidian Flavored Markdown and activates when you explicitly ask for Obsidian note formatting or syntax help. General Markdown and broad vault operations are outside its scope.
How does this compare with other Obsidian syntax skills?
The skill's own file says to prefer a separately installed kepano/obsidian-skills obsidian-markdown skill when it is available, and to use it as a compact fallback. For version-sensitive questions, it points to the official Obsidian Help site.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use this skill if you keep notes in Obsidian and want an agent to write or check properties, links, callouts and Mermaid blocks correctly, with edits gated behind an approval step. Skip it for general Markdown, non-Obsidian note-taking, or if you need current Obsidian version details, since the skill defers those to the official help site.
Download the skill