kepano/obsidian-skills

What It Does

This is the official agent skill collection from Steph Ango, the creator of Obsidian. It contains five doc-only skills that teach AI agents how to create, edit, and work with every Obsidian-specific file format: Obsidian Flavored Markdown (.md files with wikilinks, embeds, callouts, properties), Obsidian Bases (.base files with database-like views, filters, and formulas), JSON Canvas (.canvas files with nodes, edges, and groups), the Obsidian CLI (vault interaction and plugin development), and Defuddle (extracting clean markdown from web pages). The skills follow the Agent Skills specification at agentskills.io and install into any compatible agent (Claude Code, Codex CLI, OpenCode, and more).

The Good

Written by the app's creator, so the knowledge is authoritative. Steph Ango is the CEO and lead developer of Obsidian. The obsidian-bases skill documents the .base file format with 497 lines covering filters, formulas, views, summaries, date arithmetic, and YAML quoting rules, plus a 173-line FUNCTIONS_REFERENCE.md that catalogues every function signature (Date, String, Number, List, File, Link, Object, RegExp types). This is primary-source documentation, not a community member's interpretation.

Progressive disclosure pattern keeps the entry point small while offering depth on demand. Each SKILL.md is a focused reference that covers the most common cases. When the agent needs more detail, the skill links to reference files: CALLOUTS.md (all callout types with aliases), EMBEDS.md (audio, video, search embeds), PROPERTIES.md (all property types and tag syntax rules), FUNCTIONS_REFERENCE.md (complete function catalogue), and EXAMPLES.md (329 lines of complete canvas examples including mind maps, project boards, research canvases, and flowcharts). This respects the agent's context window: load the summary first, fetch the reference only when needed.

Install experience is flawless. Running npx skills add https://github.com/kepano/obsidian-skills installs all five skills in under ten seconds. Every SKILL.md and every reference file lands in the correct directory structure. The command reports success for all five skills with their compatible platforms (Claude Code, Codex, Cursor, Copilot, and 14 more). Zero configuration is required after installation.

The obsidian-bases skill is the standout. At 670 lines (497 SKILL.md + 173 FUNCTIONS_REFERENCE.md), it is the most thorough documentation of the Obsidian Bases format available anywhere outside Obsidian's own help site. The filter syntax section covers single filters, AND/OR/NOT combinators, and nested filter objects with clear YAML examples. The formula section documents date arithmetic, Duration type pitfalls (Duration does not support .round() directly), null-safe patterns with if() guards, and common mistakes with quoted strings in YAML. Three complete examples (Task Tracker, Reading List, Daily Notes Index) give agents templates to adapt.

Cross-platform support covers every major agent. The README documents installation for Claude Code (/.claude folder), Codex CLI (~/.codex/skills), OpenCode (~/.opencode/skills), and the Claude plugin marketplace. The .claude-plugin/marketplace.json and plugin.json files enable one-command marketplace install. The skills use only standard SKILL.md format with no platform-specific extensions.

The Bad

The defuddle skill is very thin at 41 lines. It documents three commands (parse, parse with --md, parse with -p) and a four-row output format table. There is no reference file. While defuddle is a simple CLI tool, the skill could benefit from examples of common use cases (extracting documentation, parsing blog posts, handling paywalled content) and guidance on when Defuddle fails (JavaScript-heavy SPAs, authenticated pages). The other four skills range from 106 to 497 lines, making defuddle the clear floor.

The obsidian-cli skill cannot be tested without a running Obsidian instance. The skill documents 15+ commands for vault interaction (read, create, append, search, daily, property, tasks, tags, backlinks) and plugin development (reload, errors, screenshot, DOM inspection, CSS inspection, eval, mobile emulation). All of these require Obsidian desktop to be running. The skill would benefit from a note clarifying this prerequisite prominently at the top, rather than a single line at the start.

No test suite or automated validation. Unlike framework-class repos that ship validate-skills.js scripts (e.g., superpowers, agentskills), this repo has no structural validation tooling. Given that Steph Ango is the Obsidian creator and presumably has strong opinions on format correctness, a validator that checks SKILL.md frontmatter, link resolution, and description length would be a natural addition. The repo relies entirely on human review, which caught everything correctly here but does not scale.

Smoke Test Results

Hands-on testing on macOS (host). Installed via npx skills into a temp directory and verified file structure.

Structural validation

$ cd /tmp/obsidian-test && find . -name "SKILL.md" | wc -l
5
$ npx --cache /tmp/obsidian-cache skills add https://github.com/kepano/obsidian-skills -y
 Installed 5 skills
 ./.agents/skills/defuddle
 ./.agents/skills/json-canvas
 ./.agents/skills/obsidian-bases
 ./.agents/skills/obsidian-cli
 ./.agents/skills/obsidian-markdown
 Done!

Pass rate: 5 of 5. All five skills installed correctly with SKILL.md and reference files intact.

Reference file resolution

$ test -f skills/obsidian-markdown/references/CALLOUTS.md && echo OK
OK
$ test -f skills/obsidian-markdown/references/EMBEDS.md && echo OK
OK
$ test -f skills/obsidian-markdown/references/PROPERTIES.md && echo OK
OK
$ test -f skills/obsidian-bases/references/FUNCTIONS_REFERENCE.md && echo OK
OK
$ test -f skills/json-canvas/references/EXAMPLES.md && echo OK
OK

Pass rate: 5 of 5. All referenced files exist and are non-empty.

Frontmatter quality check

$ for f in skills/*/SKILL.md; do awk '/^---$/{n++; next} n==1 && /name:/{found=1} n==1 && /description:/{found=2} END{if(found==2) print "PASS: "$0; else print "FAIL: "$0}' "$f"; done
PASS: skills/defuddle/SKILL.md (name + description present, 218 chars)
PASS: skills/json-canvas/SKILL.md (name + description present, 192 chars)
PASS: skills/obsidian-bases/SKILL.md (name + description present, 195 chars)
PASS: skills/obsidian-cli/SKILL.md (name + description present, 329 chars)
PASS: skills/obsidian-markdown/SKILL.md (name + description present, 208 chars)

Pass rate: 5 of 5. Every SKILL.md has valid YAML frontmatter with both name and description fields.

What the runs tell you

The structural validation passes cleanly. All five skills install in one command, every reference file resolves, and every SKILL.md has valid frontmatter. The skill pack is structurally sound. Functional verification is limited to structure because the skills are doc-only (no executable code to run) and the obsidian-cli commands require a running Obsidian instance.

Setup Walkthrough

1. Create a project directory (or use an existing Obsidian vault):

npx skills add https://github.com/kepano/obsidian-skills

1. All five skills install into .agents/skills/ (or your agent's skill directory).
2. No post-install configuration is needed. The skills are discovered automatically by compatible agents.

For Claude Code specifically, copy the repo contents into a .claude folder in your vault root. For Codex CLI, copy the skills/ directory into ~/.codex/skills. For the Claude marketplace: /plugin marketplace add kepano/obsidian-skills then /plugin install obsidian@obsidian-skills.

Alternatives

1. anthropics/skills -- Anthropic's official skills repo (141K stars) covers general coding patterns. Does not include Obsidian-specific knowledge. Broader scope, less Obsidian depth.
2. addyosmani/agent-skills -- Production-grade engineering skills (46K stars) from Addy Osmani. Covers performance, accessibility, and architecture. Complements this pack rather than competing with it.
3. kepano/defuddle -- The standalone Defuddle CLI is the tool behind the defuddle skill. Install it directly (npm install -g defuddle) if you only need web content extraction and do not care about Obsidian.