Key Files in the obsidian-skills Repository: A Complete Guide

The obsidian-skills repository consists of SKILL.md definitions, reference documentation under references/, and configuration files that enable Claude Code, OpenCode, and other agents to manipulate Obsidian vaults via markdown, bases, canvases, and CLI commands.

The obsidian-skills repository by kepano provides a structured collection of Agent Skills for extending Obsidian-compatible AI agents. Understanding the key files in the obsidian-skills repository is essential for developers who want to customize how agents interact with vaults, notes, and canvas files.

Repository Architecture and Top-Level Files

The repository follows a strict organizational pattern designed for agent auto-discovery. At the root level, README.md serves as the project overview and installation guide, while LICENSE establishes legal permissions for open-source reuse.

The .claude-plugin/ directory contains plugin.json, which provides metadata required for publishing to the Claude Code marketplace. This file enables seamless integration with the Claude ecosystem without manual configuration.

The skills/ Directory and SKILL.md Pattern

Every skill resides in its own subdirectory under skills/. Each skill follows the Agent Skills specification, requiring a SKILL.md file that contains a YAML header with name and description fields, followed by human-readable workflows that agents invoke.

The primary skill directories include:

• skills/obsidian-markdown/ - Markdown-specific extensions for wikilinks, embeds, and callouts
• skills/obsidian-bases/ - .base file syntax for views, filters, and formulas
• skills/json-canvas/ - JSON Canvas format handling for node-based diagrams
• skills/obsidian-cli/ - CLI interaction commands for plugin and theme management
• skills/defuddle/ - Web-page to markdown extraction capabilities

obsidian-markdown Skill Files

The skills/obsidian-markdown/SKILL.md file defines how agents handle wikilinks, embeds, callouts, and YAML front-matter. Supporting this are three critical reference files in skills/obsidian-markdown/references/:

• PROPERTIES.md - Documents front-matter properties and metadata syntax
• EMBEDS.md - Details Obsidian embed syntax for images and transcluded notes
• CALLOUTS.md - Specifies callout types, icons, and formatting rules

obsidian-bases Skill Files

For database-style functionality, skills/obsidian-bases/SKILL.md defines the .base file syntax used for creating views, filters, and formulas. The skills/obsidian-bases/references/FUNCTIONS_REFERENCE.md provides exhaustive tables of available functions and syntax examples that agents use to generate valid base queries.

json-canvas and CLI Skill Files

The skills/json-canvas/SKILL.md validates and creates canvas files, supported by skills/json-canvas/references/EXAMPLES.md which contains sample canvas structures demonstrating nodes, edges, and groups. For vault automation, skills/obsidian-cli/SKILL.md enables plugin and theme management through command forwarding to the Obsidian CLI.

How Agents Consume These Files

Agents like OpenCode and Claude Code auto-discover skills by scanning for SKILL.md files. The following examples demonstrate how these key files translate into practical vault manipulation.

Installing the Skill Pack

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

Restart OpenCode to auto-discover all SKILL.md definitions within the cloned directory.

Creating Markdown with obsidian-markdown

skill obsidian-markdown <<EOF
---
title: Project Overview
tags:
  - project
  - planning
---

# Project Overview

> [!note] Goal
> Summarize the main objective.

![[architecture.png|400]]
[[Next Steps]]
EOF

The skill parses the YAML front-matter and markdown body according to the specifications in references/PROPERTIES.md, outputting a properly formatted .md file in the vault.

Building JSON Canvas Files

skill json-canvas <<'CANVAS'
{
  "nodes": [
    { "id": "1", "type": "note", "text": "Start", "x": 0, "y": 0 },
    { "id": "2", "type": "note", "text": "Review", "x": 200, "y": 0 }
  ],
  "edges": [{ "from": "1", "to": "2", "label": "next" }]
}
CANVAS

This validates the JSON structure against the canvas specification and saves it as my-project.canvas.

Executing CLI Commands

skill obsidian-cli <<'CMD'
plugin enable quickadd
theme set Minimal
CMD

The skill forwards these commands directly to the Obsidian CLI, enabling automated plugin management and theme switching within the vault.

Summary

• The README.md and LICENSE provide project entry points and legal framework for open-source reuse
• Each skill directory contains a SKILL.md following the Agent Skills specification with YAML metadata defining name and description
• Reference files in references/ directories supply concrete syntax specifications for markdown properties, embeds, callouts, base functions, and canvas examples
• The .claude-plugin/plugin.json enables marketplace integration for Claude Code distribution
• Agents auto-discover capabilities by scanning the skills/ directory structure for valid SKILL.md files

Frequently Asked Questions

What is the purpose of the SKILL.md files in obsidian-skills?

Each SKILL.md file serves as a formal skill definition containing YAML metadata with name and description fields, followed by human-readable workflows. These files enable auto-discovery by OpenCode, Claude Code, and other compatible agents, allowing them to understand available capabilities without manual configuration.

Where can I find the syntax specifications for Obsidian markdown features?

Detailed syntax specifications reside in the skills/obsidian-markdown/references/ directory. The PROPERTIES.md, EMBEDS.md, and CALLOUTS.md files provide exhaustive tables and examples for front-matter properties, image embeds including wikilink syntax, and callout formatting rules respectively.

How do agents detect and load skills from this repository?

Agents scan the skills/ directory for files named exactly SKILL.md. Upon detection, they parse the YAML header to identify the skill name and description, then load the associated workflow instructions. For OpenCode, placing the repository in ~/.opencode/skills/obsidian-skills enables automatic discovery after restarting the agent.

What is the role of the .claude-plugin directory?

The .claude-plugin/ directory contains plugin.json, which stores metadata required for publishing to the Claude Code marketplace. This configuration file allows Claude Code to recognize and integrate the obsidian-skills package seamlessly into the Claude ecosystem, facilitating one-click installation for users.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}