# Key Files in the obsidian-skills Repository: A Complete Guide > Explore the key files in the obsidian-skills repository, including SKILL.md definitions and reference docs. Understand how agents manipulate Obsidian vaults via markdown, bases, canvases, and CLI commands. - Repository: [Steph Ango/obsidian-skills](https://github.com/kepano/obsidian-skills) - Tags: how-to-guide - Published: 2026-03-24 --- **The obsidian-skills repository consists of [`SKILL.md`](https://github.com/kepano/obsidian-skills/blob/main/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`](https://github.com/kepano/obsidian-skills/blob/main/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`](https://github.com/kepano/obsidian-skills/blob/main/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`](https://github.com/kepano/obsidian-skills/blob/main/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`](https://github.com/kepano/obsidian-skills/blob/main/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`](https://github.com/kepano/obsidian-skills/blob/main/PROPERTIES.md) - Documents front-matter properties and metadata syntax - [`EMBEDS.md`](https://github.com/kepano/obsidian-skills/blob/main/EMBEDS.md) - Details Obsidian embed syntax for images and transcluded notes - [`CALLOUTS.md`](https://github.com/kepano/obsidian-skills/blob/main/CALLOUTS.md) - Specifies callout types, icons, and formatting rules ### obsidian-bases Skill Files For database-style functionality, [`skills/obsidian-bases/SKILL.md`](https://github.com/kepano/obsidian-skills/blob/main/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`](https://github.com/kepano/obsidian-skills/blob/main/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`](https://github.com/kepano/obsidian-skills/blob/main/skills/json-canvas/SKILL.md) validates and creates canvas files, supported by [`skills/json-canvas/references/EXAMPLES.md`](https://github.com/kepano/obsidian-skills/blob/main/skills/json-canvas/references/EXAMPLES.md) which contains sample canvas structures demonstrating nodes, edges, and groups. For vault automation, [`skills/obsidian-cli/SKILL.md`](https://github.com/kepano/obsidian-skills/blob/main/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`](https://github.com/kepano/obsidian-skills/blob/main/SKILL.md) files. The following examples demonstrate how these key files translate into practical vault manipulation. ### Installing the Skill Pack ```bash git clone https://github.com/kepano/obsidian-skills.git ~/.opencode/skills/obsidian-skills ``` Restart OpenCode to auto-discover all [`SKILL.md`](https://github.com/kepano/obsidian-skills/blob/main/SKILL.md) definitions within the cloned directory. ### Creating Markdown with obsidian-markdown ```yaml skill obsidian-markdown < [!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`](https://github.com/kepano/obsidian-skills/blob/main/references/PROPERTIES.md), outputting a properly formatted `.md` file in the vault. ### Building JSON Canvas Files ```json 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 ```bash 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`](https://github.com/kepano/obsidian-skills/blob/main/README.md) and `LICENSE` provide project entry points and legal framework for open-source reuse - Each skill directory contains a [`SKILL.md`](https://github.com/kepano/obsidian-skills/blob/main/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`](https://github.com/kepano/obsidian-skills/blob/main/.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`](https://github.com/kepano/obsidian-skills/blob/main/SKILL.md) files ## Frequently Asked Questions ### What is the purpose of the SKILL.md files in obsidian-skills? Each [`SKILL.md`](https://github.com/kepano/obsidian-skills/blob/main/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`](https://github.com/kepano/obsidian-skills/blob/main/PROPERTIES.md), [`EMBEDS.md`](https://github.com/kepano/obsidian-skills/blob/main/EMBEDS.md), and [`CALLOUTS.md`](https://github.com/kepano/obsidian-skills/blob/main/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`](https://github.com/kepano/obsidian-skills/blob/main/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`](https://github.com/kepano/obsidian-skills/blob/main/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.