What are Claude Skills and why would I install one for my notes?

A skill is a folder with a SKILL.md file holding instructions an AI agent loads when the task is relevant. It follows the Agent Skills open standard, so the same folder works in Claude Code, Codex and other compatible agents. Installing the note.md skills means an agent editing files in your vault knows which markdown note.md actually renders, instead of guessing from Obsidian conventions that only partly apply.

Do I need these skills to use note.md?

No. note.md works entirely on its own and nothing in the app depends on them. The skills matter only if you point an AI agent at your vault folder and let it read or write notes. If you never do that, you can ignore them.

Does installing a skill in claude.ai make it available in Claude Code?

No, and this catches people out. The three surfaces are separate: skills uploaded to claude.ai stay in claude.ai, Claude Code reads skills from the filesystem, and the API is separate again. If you use both Claude Code and the Claude desktop app, install the skills in both places.

Are the skills free, and can I modify them?

Yes to both. They are MIT licensed and adapted from Steph Ango's obsidian-skills, which is also MIT. Fork them, edit them, or copy the parts you want into your own skill. If you find something note.md renders that the markdown skill gets wrong, a pull request on the repo is welcome.

Do the skills send my notes anywhere?

The skills themselves are plain text instruction files and do nothing on their own. What sends data is the agent you install them into. Claude Code and the Claude desktop app both process your files in the cloud, so connecting either one to your vault means the notes it reads leave your Mac. That is a separate decision from installing a skill, and it is worth making deliberately.

Claude Skills for your note.md vault

An Agent Skill is a folder containing a SKILL.md file of instructions that an AI agent loads when the task is relevant. These two describe note.md’s markdown dialect and its knowledge graph, so an agent working inside your vault follows the rules note.md actually enforces rather than guessing from Obsidian conventions that only partly apply.

The problem they solve

Why an agent gets your vault wrong

note.md stores Obsidian-compatible markdown on disk and renders a subset of it. That subset is the whole issue. Ask any capable agent to write a note and it will reach for the full Obsidian vocabulary it learned from thousands of public vaults: an ![[embed]], a mermaid diagram, a ==highlight==, a callout type like [!danger].

Every one of those saves without an error and then renders as literal text, or degrades to a plain note, the next time you open the file. Nothing warns you. You find out weeks later, halfway down a chapter, looking at a paragraph of raw syntax where a callout was supposed to be.

A skill fixes that by telling the agent the boundaries up front. It is a small thing. It is also the difference between an agent that is useful in your vault and one that quietly makes a mess in it.

What you get

Two skills

notemd-markdown

Teaches an agent the exact markdown note.md renders: wikilinks, the five supported callout types, tags, KaTeX math, the frontmatter schema, and folder-note hierarchy.

note.md reads Obsidian-flavored markdown but renders a subset of it. An agent that writes an embed, a mermaid diagram, a %%comment%% or ==highlight== produces a file that saves without complaint and then renders as raw text in your vault. The failure is silent, which is the worst kind.

Wikilinks, including when to disambiguate with a folder path and why not to hand-write notemd:// links
The five callout types that render (note, tip, important, warning, caution) and the fact that every other type silently degrades to note
The frontmatter schema, including that the id is note.md's durable identity and must never be written or copied by hand
Folder-note hierarchy, where a note's parent comes from folder layout rather than a frontmatter field
KaTeX math, footnotes, task lists, tables and toggles

notemd-knowledge-graph

A read-only reference explaining that note.md's graph is derived rather than authored, and that argument maps are model output anchored to real quotes.

Agents like to be helpful, and an agent asked to 'make a knowledge graph' will happily invent one. There is no file to author here. Worse, a hand-written argument map carries confidence tiers that would be fabricated, which turns a trust signal into a lie.

The three edge kinds and where each comes from: wikilinks, folder-note hierarchy, and citations to indexed sources
That the only way to shape the graph is to change the notes themselves
What an argument map is, its node and edge kinds, and how quote anchors and confidence tiers work
An explicit instruction never to fabricate or hand-edit an argument map

Download

Get the files

Both skillsOne ZIP, both folders. Unpack into your Claude Code skills directory.Download ↓notemd-markdownSingle skill, folder at the archive root. This is the shape claude.ai's uploader wants.Download ↓notemd-knowledge-graphSingle skill, folder at the archive root. This is the shape claude.ai's uploader wants.Download ↓

The source lives at a-aigner/notemd-skills. Both skills follow the Agent Skills specification, so they are not Claude-specific. Codex and other compatible agents read the same files.

Install

Where the files have to go

Claude Code

Filesystem based. The plugin route keeps the skills updatable from the repo.

01Add the marketplace

/plugin marketplace add a-aigner/notemd-skills

02Install the bundle
```
/plugin install notemd@notemd-skills
```

Or install by hand, into your personal skills folder

mkdir -p ~/.claude/skills
cd ~/.claude/skills
curl -L https://github.com/a-aigner/notemd-skills/archive/refs/heads/main.tar.gz | \
  tar xz --strip-components=2 notemd-skills-main/skills

Claude Desktop and claude.ai

Upload based. Each skill goes up as its own ZIP, with the skill folder at the root of the archive.

01Download the ZIP for a skill
02In Claude, open Settings, then Customize, then Skills
03Choose the + button, then Create skill, and upload the ZIP

Pointing an agent at your vault

Skills only matter once an agent can actually see your notes, which is a separate setup and a decision worth taking seriously. Connecting Claude to your vault covers how to do it, what Claude can see once you have, and what to keep out of a connected folder.

Credit

Where these came from

Adapted from kepano/obsidian-skills by Steph Ango, MIT licensed, and reworked for what note.md renders. The Obsidian markdown skill became a narrower one describing note.md’s subset. The JSON Canvas skill was replaced, since note.md has no canvas file and its graph is derived rather than authored. The Bases and CLI skills were dropped because note.md has neither. Our versions are MIT too.

Claude Skills for your vault.