CLI tool
kepano/obsidian-skills avatar
kepano/obsidian-skills

Obsidian Skills: A Spec-Compliant Bridge Between Agents and Your Vault

GitHub describes it as Agent skills for Obsidian. Teach your agent to use Obsidian CLI and open formats including Markdown, Bases, JSON Canvas.. The metadata lists the MIT license. This article stays within the project description and details documented in the GitHub repository README.

52,781 stars3,760 forksUnknownMIT

At a glance

What is it?
This repository packages six agent skills that teach Claude Code, Codex, and Open Code to work with Obsidian's own file formats and CLI. The value is in the shared spec, not in any single agent integration.
Who is it for?
Adopt obsidian-skills if you already run an agent like Claude Code or Codex inside an Obsidian vault and want a common vocabulary for its native formats. Do not adopt it if you only need one-off markdown editing, because the skill overhead may outweigh the benefit.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 4 days ago.
What is it written in?
GitHub does not report a main language for this repository.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • kepano/obsidian-skills52,781 ★ · +7,256
Star history
Repository2026-08-132026-11-15
kepano/obsidian-skills45.5k52.8k

7,256 Stars in the last 94 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

What This Repo Actually Solves

The problem is that agents like Claude Code or Codex have no built-in knowledge of Obsidian's file formats. Wikilinks, embeds, callouts, properties, Bases views, and JSON Canvas nodes all have syntax rules that a generic model will guess at and often get wrong. This repository packages that knowledge as six separate skills, each following the Agent Skills specification from agentskills.io. The intended user is someone who already works with Obsidian and wants an agent to create or edit notes, bases, canvases, or even develop plugins, without having to paste format documentation into every prompt. It is a bridge between a general-purpose agent and a specific application's conventions.

How the Skills Are Structured

Each skill lives in its own directory under `skills/` and contains a `SKILL.md` file, which is the standard entry point defined by the Agent Skills specification. The README lists six skills: obsidian-markdown for Obsidian Flavored Markdown, obsidian-bases for `.base` files, json-canvas for `.canvas` files, obsidian-cli for interacting with vaults via the Obsidian CLI, defuddle for extracting clean markdown from web pages, and knap for rendering Markdown templates from JSON or CSV data. The defuddle skill is interesting because it is not about Obsidian syntax at all; it wraps an external library to strip clutter from web pages before you paste content into a note. That suggests the repo is not just about format compliance, but about reducing token usage when bringing external content into a vault.

Installation Paths Depend on Your Agent

The README gives three installation routes. The first is a marketplace command: `/plugin marketplace add kepano/obsidian-skills` followed by `/plugin install obsidian@obsidian-skills`. The second is via npx: `npx skills add [email protected]:kepano/obsidian-skills.git`, with an https variant. The third is manual, and this is where the agent matters. For Claude Code, you add the repo contents to a `/.claude` folder in your vault root. For Codex, you copy the `skills/` directory into `~/.codex/skills`. For OpenCode, you clone the entire repo into `~/.opencode/skills/obsidian-skills` and must not copy only the inner `skills/` folder; the full repo structure is required so OpenCode's auto-discovery finds `SKILL.md` files. OpenCode needs no config changes, just a restart. That variation is a real friction point: the same skill set has five different install procedures, and the README does not explain why the marketplace route works or what plugin manager it refers to.

What Each Skill Covers, According to the README

The table in the README gives one line per skill. obsidian-markdown covers wikilinks, embeds, callouts, properties, and other Obsidian-specific syntax in `.md` files. obsidian-bases covers `.base` files with views, filters, formulas, and summaries. json-canvas covers `.canvas` files with nodes, edges, groups, and connections. obsidian-cli covers interacting with vaults via the Obsidian CLI, including plugin and theme development. defuddle covers extracting clean markdown from web pages using the Defuddle library, with the stated goal of removing clutter to save tokens. knap covers rendering Markdown templates from JSON or CSV data using Knap, including batch file generation. The README does not show any actual skill instructions, so you cannot tell from it how detailed or accurate each `SKILL.md` file is. If you plan to use these skills, you should open each directory and read the prompts yourself before trusting them with your vault.

A Genuine Limitation: No Versioning and No Error Handling

The repository has no releases listed and the last push was on September 15, 2026. That means there is no pinned version to depend on. If Obsidian changes its Bases syntax or the Agent Skills spec evolves, this repo may lag behind, and you will not get a release note to warn you. The README also does not describe any fallback behavior. What happens when an agent tries to create a `.base` file in a vault that does not have the Bases core plugin enabled? The skill file might mention it, but the README does not. That is a real gap. For a tool meant to teach agents, the absence of explicit error handling or validation instructions is a warning sign. This is the wrong tool if you need guaranteed format correctness; the skills are best-effort prompts, not validators.

The Real Alternative: Inline Prompts or Custom Scripts

The obvious alternative is to skip the skill system entirely and paste the relevant Obsidian documentation into your agent prompt each time. That approach has no install step, no directory structure to maintain, and no dependency on the Agent Skills spec. The difference is that a skill gives the agent a reusable, structured reference that is always loaded when the skill is active, whereas an inline prompt requires you to remember to include it and adds tokens to every request. Another alternative is to write your own scripts that call the Obsidian CLI directly, but that loses the natural language interaction the skills enable. For a user who only occasionally asks an agent to create a note, the inline prompt might be simpler. For a heavy user who wants consistent behavior across multiple agents, the skill approach wins. The trade-off is between convenience and control.

Licence and Maintenance Cost

The repository is licensed under MIT, which means you can copy, modify, and redistribute the skill files with minimal restrictions. The maintenance cost is on you. There are no releases, so you cannot track upstream changes via tags or changelogs. You will need to monitor the repository manually if you want updates. The skills themselves are text files, so updating them is as simple as pulling the repo or copying new files, but you have to notice that a change happened. This is fine for a personal vault, but for a team that relies on these skills for plugin development or large-scale note generation, the lack of a versioning strategy is a liability. The MIT licence does not protect you from syntax drift in Obsidian itself; that is an external dependency you must track.

Editorial conclusion

Adopt obsidian-skills if you already run an agent like Claude Code or Codex inside an Obsidian vault and want a common vocabulary for its native formats. Do not adopt it if you only need one-off markdown editing, because the skill overhead may outweigh the benefit. Verify first that your agent actually supports the Agent Skills specification, since the manual install paths differ per agent and the repo does not list any releases or version pins. Then check the skill contents yourself, because the README only gives you the names and one-line descriptions, not the actual constraints each skill enforces. The project is MIT licensed, so you can adapt the skills freely, but you take on the maintenance burden of tracking changes to both the spec and Obsidian's syntax.

Frequently asked questions

How do I install obsidian skills?

Through a plugin marketplace with /plugin marketplace add kepano/obsidian-skills followed by /plugin install obsidian@obsidian-skills, through npx skills add over ssh or https, or by copying the skills into the agent's own skills directory.

What is obsidian-skills?

A set of six agent skills for Obsidian that follow the Agent Skills specification, so they work with any skills-compatible agent including Claude Code, Codex and Open Code. The repository holds skill definitions and no source code.

How do I use obsidian skills with Open Code?

Clone the whole repository into ~/.opencode/skills/obsidian-skills with git clone, so the SKILL.md files sit at ~/.opencode/skills/obsidian-skills/skills/<skill-name>/SKILL.md. Do not copy only the inner skills folder, and restart Open Code afterwards.

Official sources

  1. Official README
  2. Project repository
  3. README
  4. Releases
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/kepano-obsidian-skills.svg)](https://hysenlabs.com/projects/kepano-obsidian-skills)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/kepano-obsidian-skills.svg)](https://hysenlabs.com/projects/kepano-obsidian-skills)

Was this useful?