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 the extra syntax Obsidian uses on top of standard Markdown, including wikilinks, embeds, callouts, properties, tags and comments. It is aimed at people who keep notes in an Obsidian vault and want an agent to draft or tidy them. By the end of this guide you will know what the skill changes, how to install it, how to ask for it, and where it falls short.
Obsidian Markdown Syntaxkepano/obsidian-skills · MIT Download the skill Quick start
- 1Download the ZIP. Get the obsidian-markdown skill ZIP from this page.
- 2Unzip into a skills folder. Extract it into ~/.claude/skills/ for personal use or into a project's .claude/skills/ folder.
- 3Or upload in the Claude apps. If you use the Claude apps, go to Settings → Capabilities → Skills and upload the skill there.
- 4Ask in plain language. Describe the note you want, mentioning wikilinks, callouts, frontmatter, tags or embeds.
- 5Check the result in Obsidian. Open the note in Obsidian's reading view to confirm the links, embeds and callouts render.
What the obsidian-markdown skill does
Obsidian is a note-taking app that stores notes as plain Markdown files with extra features: links between notes, embedded images and notes, highlighted callout boxes, and metadata headers called properties. Without guidance, an AI agent writes generic Markdown and misses these features.
This skill adds instructions and reference guides so the agent uses Obsidian syntax correctly when it writes or edits a note. It covers only Obsidian-specific extensions; standard Markdown such as headings, lists and tables is assumed.
- Wikilinks such as [[Note Name]] for links inside your vault
- Embeds such as ![[image.png|300]] for images, PDFs, notes and more
- Callouts such as > [!tip] for highlighted information
- Properties (frontmatter) for title, tags, aliases and cssclasses
- Tags, comments, highlights, LaTeX math, Mermaid diagrams and footnotes
Install the skill
Download the ZIP for this skill from this page. Then choose one of the two options below.
For a personal install available across your projects, unzip the download into ~/.claude/skills/. For a single project, unzip it into that project's .claude/skills/ folder.
If you use the Claude apps, you can instead upload the skill under Settings → Capabilities → Skills.
- Personal: ~/.claude/skills/
- Project only: .claude/skills/ inside the project folder
- Claude apps: Settings → Capabilities → Skills
Trigger the skill with natural requests
You do not need a special command. The skill's description says it applies when you work with .md files in Obsidian, or when you mention wikilinks, callouts, frontmatter, tags, embeds or Obsidian notes. Asking in plain language is usually enough.
Name the Obsidian features you want so the agent knows which syntax to use. Mention the note's purpose too, so it can choose sensible properties and links.
- "Draft a study note on photosynthesis in my Obsidian vault with a warning callout for common mistakes."
- "Add frontmatter with tags and an alias to this note and link it to my Meeting Notes 2024-01-10 note."
- "Tidy this Markdown file so it uses wikilinks and embeds the architecture diagram image at width 600."
Example: what the agent writes
The skill steers the agent toward the correct syntax. A typical output includes YAML frontmatter, internal wikilinks, a callout and an image embed with a width.
Compare the generic and Obsidian-aware forms of a link: a generic Markdown link to another note will not behave like a wikilink, and a callout written as a plain blockquote will not show the Obsidian callout styling.
---
title: Project Alpha
tags:
- project
- active
---
> [!important] Key Deadline
> The first milestone is due on ==January 30th==.
Reviewed in [[Meeting Notes 2024-01-10#Decisions]].
![[Architecture Diagram.png|600]]What you need and how it runs
The skill lists no requirements. It contains instructions and reference guides only (SKILL.md plus three reference files on callouts, embeds and properties). It does not add tools, run scripts or use the network.
The skill shapes only the text the agent writes. It does not open your vault in the Obsidian app, and it does not check that the note renders correctly there. Open the note in Obsidian's reading view yourself to confirm.
- Requires: nothing listed
- Runs scripts: no
- Uses network: no
- Licence: MIT
Tips for better results
Give the agent a clear target: say whether the note is for your vault, a study set or project documentation. For links to external web pages, the skill expects standard Markdown links, so say so if you want those.
Ask for a specific callout type from the supported list, such as tip, warning or question, rather than a vague style. Check the output in Obsidian before relying on it.
- Use wikilinks for notes in the vault and standard links for external URLs
- Name the exact embed size if you need one, for example a width of 300
- Review frontmatter types, since dates and tags must follow the property rules
What people use it for
- Drafting study notes with linked concepts, highlighted callouts and math
- Tidying a personal knowledge base so links, tags and frontmatter follow Obsidian syntax
- Maintaining project documentation stored in an Obsidian vault with embedded diagrams and images
- Adding consistent properties such as title, tags and aliases across many notes
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. In the Claude apps you can instead upload it under Settings → Capabilities → Skills.
Is the obsidian-markdown skill free?
The skill is published under the MIT licence. This page does not list any price for it, so check the licence file in the source repository for the terms.
What does the skill require?
The skill lists no requirements. It runs no scripts and uses no network. It contains only instructions and reference files.
Will the agent check that my note renders in Obsidian?
No. The skill only shapes the text the agent writes. Open the note in Obsidian's reading view yourself to confirm it looks right.
Can I use this skill for normal Markdown on GitHub or a blog?
Not really. It covers only Obsidian-specific extensions, so wikilinks, callouts and embeds will not render on GitHub, blogs or other tools. Use a general Markdown approach there.
Can the agent read or edit my vault directly in the app?
No. This skill does not give the agent access to your vault in the Obsidian app. It only helps the agent write correct Obsidian syntax in the text it produces.
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
This skill suits people who keep notes in Obsidian and want an agent to draft or tidy them with correct links, embeds, callouts and properties. Skip it if you only need standard Markdown for GitHub, blogs or other tools, or if you need the agent to work inside the Obsidian app itself.
Download the skill