Skip to content
Get packs

Guide · Open source

How to use obsidian-skills with your AI agent

Updated · written with AI from the project's own documentation and checked against our catalogue data

obsidian-skills is a set of Agent Skills written for Obsidian. Each skill is an instruction file that teaches an AI agent, such as Claude Code, Codex or OpenCode, the specific formats Obsidian uses, so the agent can create and edit vault files correctly instead of guessing at the syntax. This guide shows you how to install it, what each skill covers and how to check that it is working.

Obsidiankepano/obsidian-skills · ★ 50.6k · MIT

Quick start

  1. 1Check prerequisites. You need an AI agent that supports Agent Skills, such as Claude Code, Codex or OpenCode, and Git for cloning the repository.
  2. 2Pick an install route. Use the Claude Code marketplace, npx skills, or a manual install for Claude Code, Codex or OpenCode.
  3. 3Run the install commands. Run the marketplace commands, the npx skills command, or the git clone command shown in the README for your agent.
  4. 4Place the files correctly. For OpenCode, clone the full repo so each SKILL.md sits under ~/.opencode/skills/obsidian-skills/skills/<skill-name>/.
  5. 5Restart the agent. For OpenCode, restart so the skills are discovered. No config file changes are required.
  6. 6Ask for an Obsidian format task. Request a note, Bases view or Canvas file and check the output against your vault.

What the skills cover

The repository contains six skills. Three of them handle Obsidian file formats, one handles the Obsidian CLI, and two handle web extraction and template rendering.

  • obsidian-markdown: create and edit Obsidian Flavored Markdown (.md) with wikilinks, embeds, callouts, properties and other Obsidian-specific syntax.
  • obsidian-bases: create and edit Obsidian Bases (.base) files with views, filters, formulas and summaries.
  • json-canvas: create and edit JSON Canvas files (.canvas) with nodes, edges, groups and connections.
  • obsidian-cli: interact with Obsidian vaults via the Obsidian CLI, including plugin and theme development.
  • defuddle: extract clean markdown from web pages, removing clutter to save tokens.
  • knap: render Markdown templates from JSON or CSV data, including batch file generation.

Install with the Claude Code marketplace

If you use Claude Code, the marketplace route is the shortest. Run the two commands below inside Claude Code.

/plugin marketplace add kepano/obsidian-skills /plugin install obsidian@obsidian-skills

Install with npx skills

If you use the npx skills tool, add the repository with either SSH or HTTPS. The README lists both forms.

  • SSH: npx skills add git@github.com:kepano/obsidian-skills.git
  • HTTPS: npx skills add https://github.com/kepano/obsidian-skills

Install manually for Claude Code, Codex or OpenCode

For Claude Code, add the contents of this repo to a /.claude folder in the root of your Obsidian vault, or in whichever folder you use with Claude Code.

For Codex, copy the skills/ directory into your Codex skills path, which is typically ~/.codex/skills.

For OpenCode, clone the entire repo into the OpenCode skills directory. Do not copy only the inner skills/ folder. The directory structure must be ~/.opencode/skills/obsidian-skills/skills/<skill-name>/SKILL.md.

git clone https://github.com/kepano/obsidian-skills.git ~/.opencode/skills/obsidian-skills

Confirm the skills are loaded

For OpenCode, the README says it auto-discovers every SKILL.md file under ~/.opencode/skills/, and no changes to opencode.json or any other config file are needed. Restart OpenCode and the skills become available. For other agents, check that the skills folder is where that agent expects it.

Ask your agent to use the skills

Once installed, ask the agent for a task in Obsidian formats, such as adding a callout, a properties block, a Bases view or a Canvas file. The skill gives the agent the syntax rules for that format. The skills only add knowledge to the agent; they do not run on their own.

  • Write a note with wikilinks and an embedded image.
  • Build a Bases view with filters and a formula column.
  • Create a Canvas with linked nodes grouped into sections.
  • Pull the main text of a web article into a clean markdown note with defuddle.

What people use it for

  • Writing notes with wikilinks, embeds, callouts and properties that render correctly in Obsidian.
  • Creating Bases views with filters, formulas and summaries.
  • Building Canvas files with nodes, edges and groups.
  • Using the Obsidian CLI for plugin or theme development.
  • Extracting clean markdown from web pages with defuddle to save tokens.

Frequently asked questions

Is obsidian-skills free to use?

Yes. The repository is licensed under MIT, as stated in the project listing. The README does not describe any paid tier.

What do I need before installing obsidian-skills?

You need an AI agent that supports Agent Skills, such as Claude Code, Codex or OpenCode. You also need Git to clone the repository, or npx skills if you use that route.

Does obsidian-skills work with agents other than Claude Code?

The README says the skills follow the Agent Skills specification so any skills-compatible agent can use them, and it names Claude Code, Codex and Open Code. It does not list every agent, so check your agent's skill documentation.

Is obsidian-skills a plugin I install in Obsidian?

No. The repo contains instruction files for AI agents, not a standalone Obsidian plugin or app. The skills only add knowledge to an agent.

Why do I need to clone the whole repo for OpenCode?

The README says OpenCode needs the directory structure ~/.opencode/skills/obsidian-skills/skills/<skill-name>/SKILL.md. Copying only the inner skills/ folder breaks that structure.

What is the difference between obsidian-skills and the Obsidian CLI?

The Obsidian CLI is the command-line interface to Obsidian vaults. The obsidian-cli skill teaches your agent how to use it, including for plugin and theme development. The skill is not a replacement for the CLI itself.

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

Use obsidian-skills if you already work with an AI agent such as Claude Code, Codex or OpenCode and want it to write Obsidian syntax correctly. Skip it if you do not use an AI agent, or if you want a standalone plugin or app, since this repo only provides instruction files.

Install options & downloads