How to use the Obsidian Canvas Builder agent skill

What is an agent skill, and what does the canvas skill do?

An agent skill is a folder with a SKILL.md instruction file that an AI agent loads when a request matches the skill's description. The canvas skill covers Obsidian JSON Canvas boards, which are JSON files with the .canvas extension that hold nodes (text, file, link and group nodes) and edges (the arrows between them).

With the skill installed, the agent can report on existing boards, including node counts, group labels, broken edge endpoints and missing file targets. It can also build or change boards by adding vault notes, text cards and connections. Reads are read-only. Every change is drafted, previewed and applied as one recoverable transaction that you approve before anything is written.

Install the canvas skill from the ZIP

Download the ZIP for skills/canvas from this page and unzip it. You can place the resulting canvas folder in one of two locations: ~/.claude/skills/ for personal use across projects, or .claude/skills/ inside a specific project folder.

If you use the Claude apps, you can instead upload the skill under Settings → Capabilities → Skills.

• Personal install: unzip into ~/.claude/skills/
• Project install: unzip into the project's .claude/skills/ folder
• Claude apps: Settings → Capabilities → Skills, then upload the skill

Check the requirements before you start

The skill depends on the wider claude-obsidian product, so it will not work on its own. The product must be installed locally with scripts/claude-obsidian.py available. You also need Python 3 to run the transaction inspect and apply commands, and an Obsidian vault set up with the wiki/ directory structure.

Boards are stored under wiki/canvases/. The skill uses wiki/canvases/main.canvas as the default board only when you do not name one. If wiki/canvases/_index.md exists, it is treated as an optional catalog and is updated when a new board is added.

• claude-obsidian product installed locally, with scripts/claude-obsidian.py
• Python 3
• An Obsidian vault with the wiki/ directory structure

Trigger the skill with natural requests

You do not need special syntax. Describe what you want in ordinary language. The skill is triggered by requests about canvas status, canvas lists, visual maps, zones, spatial layouts, adding vault notes or media to a .canvas file, and phrases such as create canvas, add to canvas, or put this on the canvas.

• Status: "What is the status of my research canvas?"
• List: "List my canvases."
• Create: "Create a canvas that maps my notes on retrieval."
• Add: "Add the Contextual Retrieval note to my canvas."
• Layout: "Put these notes into a zone called Methods on the canvas."

Review and approve changes

For any change, the agent first reads the whole board, drafts the nodes or edges, and validates them. Validation checks that the JSON parses, IDs are unique, edge endpoints exist, sizes are positive integers, and file paths are safe vault-relative paths that exist. You then see a preview.

After you approve, the agent inspects the transaction bundle and applies it with the approval hash. The agent reports the operation ID, the exact changed paths, the board name, node IDs and final positions. It does not commit to Git. Removing nodes or edges requires explicit consent after the preview.

Understand the limits and safety notes

The skill can create and replace board files, but it cannot delete or rename them. For a removal or rename request, the agent explains this limit and returns a separate manual cleanup plan rather than copying the file or using other file tools.

Link nodes accept HTTPS URLs only, and creating one does not fetch the page. However, opening the board in Obsidian may fetch Open Graph metadata from the URL's host. Only use link nodes for URLs you trust, or use a text node containing the URL instead. The skill runs scripts and uses the network, so review the bundle before approving it.

• Paths must be vault-relative. Absolute paths, .. traversal, home shortcuts and symlink escapes are rejected.
• Files are referenced only if they are already in the vault or created in the same reviewed transaction.
• The skill does not download or copy media assets.

Tips for better results

Name the board when you have several, because the default is main.canvas. Ask for zones or groups when you want a spatial layout, and the agent will use 20 px inner padding and 40 px gaps between items. For a status check, ask first; the agent will not create a missing default board during a status request.

If you already have a separately installed kepano/obsidian-skills json-canvas skill, the agent will prefer it for format details, while this skill still handles vault workflow and safety.

• Name the board explicitly when you have more than one.
• Ask for a status report before large edits to see broken links and missing files.
• Expect a preview before any write.