# Obsidian Skills: notes, Bases, Canvas and vault commands (obsidianmd/obsidian-skills) — skill card for AI agents

> AgentGid skill card. Checked on 2026-11-12 against commit 3981277 (version 1.2.0).
> Every fact comes from the pack's own files at that commit. Numbers marked "as reported" are the author's.
> Human page: https://agentgid.com/skills/obsidianmd/obsidian-skills/

## Explain it to a non-programmer
Seven skills from the Obsidian team that teach your AI assistant how Obsidian works. It writes notes, table and board views and canvases in the exact format Obsidian reads. With the Obsidian app open, it can also search, read, create and move notes in your vault, and it can save web pages as clean notes.

## Who it is for
- You keep notes in Obsidian and want your assistant to read, search and organise them
- You want the assistant to build Obsidian Bases views (tables, cards, kanban boards) or Canvas boards for you
- You want web articles saved as tidy notes, or many notes made from one template and a spreadsheet
- You use Claude Code, Codex, Cursor or OpenCode
- Not for: You only use a chat window with no terminal: the vault commands need an assistant that can run local commands
- Not for: You want your notes sorted and linked for you on autopilot: these skills explain formats and commands, they do not organise a vault on their own

## What it is
- Kind: knowledge
- License: MIT
- Repository: https://github.com/obsidianmd/obsidian-skills

## What it does
- Obsidian Markdown: wikilinks, embeds, callouts, properties, tags, comments, highlights, math, Mermaid diagrams and footnotes, with a five-step workflow for a new note
- Bases: the YAML format of .base files, with filters, formulas, summaries and table, cards, list, map and kanban views, plus a list of common errors and fixes
- JSON Canvas: nodes, edges, groups, colour presets, ID rules, layout sizes and a validation checklist for .canvas files
- Obsidian CLI: read, create, append, rename, move, delete and search notes, daily notes, tasks, properties and backlinks through the running app; plus reload, error, screenshot and DOM commands for plugin and theme developers
- Obsidian Headless (ob): set up and run Obsidian Sync and Obsidian Publish from a terminal or server, without the app
- Defuddle: turn a web page into clean Markdown without menus and ads
- Knap: render Markdown notes from a template and JSON or CSV data, one note or a whole batch
- Never cuts: ['Use rename and move, not a plain file move, so Obsidian updates links to the note', 'delete moves the note to the trash; permanent deletion only when you ask', 'Publish runs a dry run first and shows you the changes']

## Skills
| Skill | Call | Changes code? | In plain words |
|---|---|---|---|
| obsidian-markdown | plain language ("Write a note about ... with links to related notes") | yes | Writes and edits notes in Obsidian's own style, with links, callouts, properties and embeds |
| obsidian-bases | plain language ("Create a Base of ...") | yes | Builds Obsidian Bases, saved views that show your notes as a table, cards, a list, a map or a kanban board |
| json-canvas | plain language ("Make a Canvas of ...") | yes | Draws Obsidian Canvas boards, cards and arrows connecting ideas, notes, images and links |
| obsidian-cli | plain language ("Find my notes about ...") | yes | Searches, reads, creates, moves and deletes notes in your vault through the open Obsidian app; also helps people building Obsidian plugins and themes |
| obsidian-headless | plain language ("Set up Obsidian Sync for this vault on my server") | yes | Runs Obsidian Sync and Obsidian Publish from a terminal or server, without the app |
| defuddle | plain language ("Save this article as a note") | yes | Turns a web page into clean text without menus and ads, to read or save as a note |
| knap | plain language ("Use this template and data to make notes") | yes | Fills a note template with data, making one note or one note per spreadsheet row |

### obsidian-markdown
- Asks for: The note's topic and content
- Asks for: Notes in your vault it should link to
- Asks for: Properties you want, such as tags or status
- Gives: A note with properties at the top
- Gives: [[Links]] to other notes, embeds and callouts
- Gives: A check that it shows correctly in Obsidian's reading view
- Say: "Write a project note for Project Alpha with tags, a deadline callout and links to my meeting notes"

### obsidian-bases
- Asks for: Which notes to include: a tag, folder, property or date
- Asks for: Which columns or properties to show
- Asks for: The view you want: table, cards, list, map or kanban
- Gives: A .base file with filters and views
- Gives: Optional formulas, such as days until a due date
- Gives: Summaries such as sums or averages
- Gives: A check that the file is valid
- Say: "Create a reading list Base with a cards view and a table of books I still have to read"

### json-canvas
- Asks for: The ideas, notes or links to place
- Asks for: How they connect, and labels for the arrows
- Asks for: Groups to box them in, if any
- Gives: A .canvas file with cards, groups and arrows
- Gives: A layout with spacing between cards
- Gives: A check that every arrow points at a real card
- Say: "Make a Canvas with three idea cards and labeled connections"

### obsidian-cli
- Asks for: What to find or change
- Asks for: Which vault, if you have several
- Gives: Search results, note text, tasks, tags or backlinks
- Gives: New or updated notes, renamed or moved with links kept
- Gives: For plugin developers: reload, error list, screenshot and console output
- Say: "Find notes about my current project and summarize the open tasks"

### obsidian-headless
- Asks for: The vault folder
- Asks for: The remote vault or Publish site name
- Asks for: Your Obsidian login, typed by you in your own terminal
- Gives: A vault linked to Sync, synced once or continuously
- Gives: A Publish dry run to review, then the publish
- Gives: Sync and Publish settings changed as you ask
- Say: "Set up Obsidian Sync for my Research vault in ~/vaults/research"

### defuddle
- Asks for: The page address
- Gives: The page as Markdown, or saved to a file
- Gives: Or one detail: title, description or site
- Say: "Extract this public article into Markdown and save it as a note"

### knap
- Asks for: A template
- Asks for: Data: a JSON file, a CSV spreadsheet or a folder of JSON files
- Asks for: A folder for the new notes
- Gives: One rendered note, or one note per row or item
- Gives: A dry run that lists the files first
- Gives: Template checks before rendering
- Say: "Use my Knap template and this CSV of articles to make one note per row in notes/"

## Know before installing
- The vault commands only work with the Obsidian desktop app open and its command line turned on in settings.
- Notes you ask about are sent into the conversation and processed by the AI model you use, not only on your computer.
- No background programs: the plugin is skills only, with no hooks and no server.
- Helper tools (Defuddle, Knap, Obsidian Headless) are not included; when one is missing, the assistant offers a global install from npm and asks first.
- Do not run the app's Sync and command-line Sync on the same vault on the same computer; back up the vault before the first sync.
- The obsidian command comes with the Obsidian installer; an unrelated npm package with a similar name is not it.

## Install (official commands)
- Claude Code: `claude plugin marketplace add obsidianmd/obsidian-skills` && `claude plugin install obsidian@obsidian-skills` — Or inside a session: /plugin marketplace add obsidianmd/obsidian-skills, then /plugin install obsidian@obsidian-skills. Update later with claude plugin update obsidian@obsidian-skills.
- Codex: `codex plugin marketplace add obsidianmd/obsidian-skills` — Then install Obsidian from the plugin directory in Codex or the ChatGPT desktop app.
- Cursor: Install Obsidian from the Cursor Marketplace.
- Any skills-compatible agent (npx skills): `npx skills add https://github.com/obsidianmd/obsidian-skills`
- Claude Code (manual): Copy plugins/obsidian/skills/ to .claude/skills/ in the root of your vault. Remove: `delete the copied folders from .claude/skills/`.
- Codex (manual): Copy plugins/obsidian/skills/ into your Codex skills path, typically ~/.agents/skills. Remove: `delete the copied folders`.
- OpenCode: `git clone https://github.com/obsidianmd/obsidian-skills.git ~/.opencode/skills/obsidian-skills` — Clone the whole repository, not only the inner skills folder, then restart OpenCode. Remove: `delete ~/.opencode/skills/obsidian-skills`.

## What runs on the user's machine
- Code on the machine: no
- Network: none
- Install: Seven skill folders of markdown text. No hooks, no server, no background programs. scripts/bump.sh at the repository root only updates version numbers for the maintainers and is not part of the plugin.
- obsidian-cli at work: Tells your assistant to run the obsidian command that ships with the Obsidian app; it talks to the running app on your computer and can create, change, move or delete notes.
- defuddle at work: Tells your assistant to run Defuddle, which downloads the web page you name.
- obsidian-headless at work: Tells your assistant to run ob, which syncs your vault with Obsidian Sync or uploads notes to Obsidian Publish.
- A helper tool is missing: The assistant offers npm install -g defuddle, npm install -g knap (or npx knap) or npm install -g obsidian-headless, after asking you.

## Examples (from the pack's own files)
- A kanban board of projects (the Bases skill's own example): output format defined in plugins/obsidian/skills/obsidian-bases/SKILL.md
- Complete example files in the skills: output format defined in plugins/obsidian/skills/json-canvas/references/EXAMPLES.md

## Steps only the person can do
- Install the Obsidian desktop app, open it and turn on its command line (https://help.obsidian.md/cli) Then: The assistant runs obsidian help to check, then works with the vault
- Log in to Obsidian Headless with ob login in your own terminal (email, password, 2FA) (https://help.obsidian.md/headless) Then: The assistant lists vaults or sites and sets up Sync or Publish
- Have an active Obsidian Sync or Publish subscription (https://obsidian.md/) Then: The assistant can sync or publish the vault
- Approve a global npm install of Defuddle, Knap or Obsidian Headless when the assistant asks (your terminal) Then: The assistant runs the missing tool
- Enter the encryption password yourself when setting up an end-to-end encrypted vault (your terminal (ob sync-setup)) Then: The vault is linked and syncs

## Mistakes to avoid
- Not: Install the npm package obsidian-cli to get the obsidian command. Instead: Turn on the CLI in the Obsidian desktop app; the command ships with the installer. Why: The npm package with that name is unrelated
- Not: Trust the exit status of an obsidian command. Instead: Read the command's output before reporting success. Why: The CLI exits with status 0 even when a command fails
- Not: Pass long text or text with backslashes through content=, or create a .canvas file with obsidian create. Instead: Write such notes and all .canvas files directly to the file. Why: Every \n and \t in content= is converted, which corrupts LaTeX, Windows paths and canvas JSON
- Not: Run the desktop app's Sync and Headless Sync on the same vault on one device. Instead: Use one of them per vault per device, and back up the vault before the first sync. Why: The two cause sync conflicts
- Not: Write bare property names in the top-level properties section of a .base file. Instead: Use the note. prefix there, e.g. note.author. Why: Obsidian ignores a bare key there and shows the raw name as the column header

## What leaves the machine
- Vault content you ask about → The AI model your assistant uses, Whenever notes are read into the conversation. Opt out: Ask only about notes you are fine sending to the model
- A request for the web page → The site you name, When the defuddle skill extracts a page. Opt out: Do not use the defuddle skill
- Vault files, and notes marked for publishing → Obsidian Sync and Obsidian Publish servers, When ob sync or ob publish runs. Opt out: Do not use the obsidian-headless skill

## Lines in the pack aimed at agents (ask the person first)
- "If it is missing, explain the dependency and offer installation with `npm install -g defuddle`." (plugins/obsidian/skills/defuddle/SKILL.md): A global npm install; the skill already says to offer it. Get the person's yes and prefer a pinned version.
- "offer installation with `npm install -g knap` or execution with `npx knap`" (plugins/obsidian/skills/knap/SKILL.md): Unpinned global install or npx run; ask the person first.
- "offer installation with `npm install -g obsidian-headless`" (plugins/obsidian/skills/obsidian-headless/SKILL.md): Global install of the Sync and Publish tool; ask the person first.
- "Without `--yes`, `ob publish` waits for confirmation, so pass `--yes` once the user approves or for an unattended job they set up." (plugins/obsidian/skills/obsidian-headless/SKILL.md): Publishing makes notes public; show the dry run and get an explicit yes before passing --yes.
- "obsidian eval code="app.vault.getFiles().length"" (plugins/obsidian/skills/obsidian-cli/SKILL.md): eval runs JavaScript inside the person's Obsidian app; use dedicated commands for vault changes, as the skill also says.

## May I use it like this?
- commercial-app: yes (MIT)
- client-work: yes (MIT)
- redistribute-files: yes (MIT: keep the copyright and permission notice in copies)
- inside-app-bundle: yes (MIT: keep the notice)

## Which one to pick
- If You want the official formats and commands for notes, Bases, Canvas, the Obsidian CLI, Sync and Publish: skill:obsidianmd/obsidian-skills
- If You want an assistant that files and links everything you drop into a self-organising second brain: skill:AgriciDaniel/claude-obsidian
- If You want a vault that works as persistent memory for coding agents: skill:breferrari/obsidian-mind
- If You want Canvas, Excalidraw and Mermaid diagrams generated from text: skill:axtonliu/axton-obsidian-visual-skills

## Works well with
- tool:defuddle: The defuddle skill runs the Defuddle command to turn web pages into Markdown
- tool:obsidian: obsidian-cli has a reload, error and screenshot loop for building Obsidian plugins
- tool:mermaid: obsidian-markdown covers Mermaid diagrams inside notes

## Works in and needs
- Works in Claude Code: plugin
- Works in Codex: plugin
- Works in Cursor: plugin
- Works in OpenCode: skills folder
- Works in Any skills-compatible agent: skills folder (npx skills)
- Needs Obsidian desktop app with the CLI turned on: obsidian-cli talks to the running app
- Needs Node.js 20+ and Knap: knap renders templates
- Needs Node.js 22+, Obsidian Headless and a Sync or Publish subscription: obsidian-headless syncs and publishes
- Needs Defuddle CLI: defuddle extracts web pages

## How to tell it works
Install it, open Obsidian, and ask: "Create a reading list Base with table and card views from the books in my vault." A new .base file appears that opens in Obsidian as a table and a card gallery of your book notes.

## Related
- kepano/defuddle
- obsidianmd/knap
- obsidianmd/jsoncanvas

## Safety
Notes you ask about go into the conversation and are processed by your AI model. The obsidian-cli skill can run JavaScript inside the app (eval) and delete or overwrite notes; the skill tells the assistant to prefer dedicated commands and use overwrite only when replacing a file is intended.
