Obsidian Markdown
Author and edit Obsidian vault notes with wikilinks, embeds, callouts, properties, and Obsidian-specific Markdown that renders correctly in reading view.
Overview
obsidian-markdown is an agent skill most often used in Build (also Idea, Operate) that creates and edits Obsidian Flavored Markdown with wikilinks, embeds, callouts, and properties.
Install
npx skills add https://github.com/kepano/obsidian-skills --skill obsidian-markdownWhat is this skill?
- Six-step workflow: frontmatter properties, content, wikilinks, embeds, callouts, reading-view verify
- Covers Obsidian-only syntax beyond CommonMark/GFM—wikilinks, ![[embeds]], > [!callout], properties
- Points to PROPERTIES, EMBEDS, and CALLOUTS reference files for exhaustive syntax
- Guidance on wikilinks vs external Markdown links for internal vault vs web URLs
- Explicit scope: standard Markdown structure is assumed; skill focuses on Obsidian extensions
- Six-step Obsidian note creation workflow documented in SKILL.md
Adoption & trust: 41k installs on skills.sh; 34.9k GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
You want agents to edit vault notes but generic Markdown skills break wikilinks, callouts, and Obsidian property frontmatter.
Who is it for?
Solo builders using Obsidian as a second brain for specs, ADRs, research, and project wikis edited by Claude Code or Cursor.
Skip if: Pure MDX/React doc sites, Notion-only workflows, or repos that forbid Obsidian-specific syntax in committed markdown.
When should I use this skill?
Working with .md files in Obsidian, or when the user mentions wikilinks, callouts, frontmatter, tags, embeds, or Obsidian notes.
What do I get? / Deliverables
Notes ship with valid Obsidian extensions, linked related pages, and embeds that render in Obsidian reading view.
- Valid Obsidian Flavored Markdown note with optional frontmatter
- Internal wikilinks and embeds where appropriate
- Callout blocks for highlighted sections
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Canonical shelf is Build/docs because the skill primarily produces .md knowledge artifacts, but notes support planning and ops across the journey. Vault documentation, specs, and linked knowledge bases live in the docs subphase of product work.
Where it fits
Capture competitor notes with wikilinks into a hub MOC and tagged frontmatter.
Write an architecture note with callouts and embed the API spec page.
Draft a scoped PRD in the vault with aliases and internal links to user stories.
Maintain an incident runbook with embedded checklists and property-driven status.
How it compares
Obsidian vault dialect skill—not generic technical writing or static-site MDX templates.
Common Questions / FAQ
Who is obsidian-markdown for?
Indie builders and knowledge workers who store agent-edited notes in Obsidian and need wikilinks, embeds, callouts, and properties handled correctly.
When should I use obsidian-markdown?
Use it during Build for project docs; during Idea for research notes; during Operate for runbooks—whenever .md files target an Obsidian vault or the user mentions wikilinks and callouts.
Is obsidian-markdown safe to install?
It is formatting guidance without shell or network calls by default; review the Security Audits panel on this Prism page for the upstream skill package.
SKILL.md
READMESKILL.md - Obsidian Markdown
# Obsidian Flavored Markdown Skill Create and edit valid Obsidian Flavored Markdown. Obsidian extends CommonMark and GFM with wikilinks, embeds, callouts, properties, comments, and other syntax. This skill covers only Obsidian-specific extensions -- standard Markdown (headings, bold, italic, lists, quotes, code blocks, tables) is assumed knowledge. ## Workflow: Creating an Obsidian Note 1. **Add frontmatter** with properties (title, tags, aliases) at the top of the file. See [PROPERTIES.md](references/PROPERTIES.md) for all property types. 2. **Write content** using standard Markdown for structure, plus Obsidian-specific syntax below. 3. **Link related notes** using wikilinks (`[[Note]]`) for internal vault connections, or standard Markdown links for external URLs. 4. **Embed content** from other notes, images, or PDFs using the `![[embed]]` syntax. See [EMBEDS.md](references/EMBEDS.md) for all embed types. 5. **Add callouts** for highlighted information using `> [!type]` syntax. See [CALLOUTS.md](references/CALLOUTS.md) for all callout types. 6. **Verify** the note renders correctly in Obsidian's reading view. > When choosing between wikilinks and Markdown links: use `[[wikilinks]]` for notes within the vault (Obsidian tracks renames automatically) and `[text](url)` for external URLs only. ## Internal Links (Wikilinks) ```markdown [[Note Name]] Link to note [[Note Name|Display Text]] Custom display text [[Note Name#Heading]] Link to heading [[Note Name#^block-id]] Link to block [[#Heading in same note]] Same-note heading link ``` Define a block ID by appending `^block-id` to any paragraph: ```markdown This paragraph can be linked to. ^my-block-id ``` For lists and quotes, place the block ID on a separate line after the block: ```markdown > A quote block ^quote-id ``` ## Embeds Prefix any wikilink with `!` to embed its content inline: ```markdown ![[Note Name]] Embed full note ![[Note Name#Heading]] Embed section ![[image.png]] Embed image ![[image.png|300]] Embed image with width ![[document.pdf#page=3]] Embed PDF page ``` See [EMBEDS.md](references/EMBEDS.md) for audio, video, search embeds, and external images. ## Callouts ```markdown > [!note] > Basic callout. > [!warning] Custom Title > Callout with a custom title. > [!faq]- Collapsed by default > Foldable callout (- collapsed, + expanded). ``` Common types: `note`, `tip`, `warning`, `info`, `example`, `quote`, `bug`, `danger`, `success`, `failure`, `question`, `abstract`, `todo`. See [CALLOUTS.md](references/CALLOUTS.md) for the full list with aliases, nesting, and custom CSS callouts. ## Properties (Frontmatter) ```yaml --- title: My Note date: 2024-01-15 tags: - project - active aliases: - Alternative Name cssclasses: - custom-class --- ``` Default properties: `tags` (searchable labels), `aliases` (alternative note names for link suggestions), `cssclasses` (CSS classes for styling). See [PROPERTIES.md](references/PROPERTIES.md) for all property types, tag syntax rules, and advanced usage. ## Tags ```markdown #tag Inline tag #nested/tag Nested tag with hierarchy ``` Tags can contain letters, numbers (not first character), underscores, hyphens, and forward slashes. Tags can also be defined in frontmatter under the `tags` property. ## Comments ```markdown This is visible %%but this is hidden%% text. %% This entire block is hidden in reading view. %% ``` ## Obsidian-Specific Formatting ```markdown ==Highlighted text==