Agent Skills Specification for Obsidian: A Complete Guide to AI‑Ready Note Workflows

The Obsidian agent skills specification is a declarative YAML‑fronted markdown format that teaches AI agents to create, edit, and validate Obsidian notes, Bases, Canvas files, and CLI commands without writing custom code.

The kepano/obsidian-skills repository defines a machine‑readable framework for AI agents working within the Obsidian ecosystem. Each skill lives under the skills/ directory as a self‑contained specification file (SKILL.md) that combines metadata, schema definitions, and executable examples, allowing agents to understand Obsidian’s file formats through pure documentation rather than imperative code.

Core Components of the Agent Skills Specification

Every skill in the specification follows a rigid structure that separates machine‑readable metadata from human‑readable implementation details.

Skill Directory Structure

Each capability resides in its own folder under skills/. For example, the Markdown skill is located at skills/obsidian-markdown/ and contains:

• SKILL.md — The primary specification with YAML front‑matter and Markdown documentation.
• references/ — Sub‑folder containing deep‑dive tables (e.g., PROPERTIES.md, EMBEDS.md, CALLOUTS.md).

This modular layout allows an agent to load only the capabilities required for a specific task.

YAML Front‑Matter Interface

The top of every SKILL.md file contains a YAML block that acts as the function signature for the agent:

name: obsidian-markdown
description: Create and edit Obsidian‑flavored Markdown (wikilinks, embeds, callouts, frontmatter, etc.)

The name field serves as the unique identifier, while description provides the semantic context used by large language models to select the appropriate tool. No executable logic resides here—only declarative metadata that the agent parses to understand its available capabilities.

Markdown‑Based Schema Documentation

Following the front‑matter, the file uses standard Markdown to describe:

• Workflow — Step‑by‑step sequences (e.g., Add frontmatter → Write content → Link notes).
• Schema tables — Formal definitions of file structures, such as the exact YAML structure for Base filters or JSON attributes for Canvas nodes.
• Code examples — Ready‑to‑copy snippets that demonstrate valid output.

Agents parse these sections to extract validation rules and generation templates without executing external scripts.

Available Skills in the Specification

The repository currently defines five distinct capabilities, each addressing a different Obsidian subsystem:

Skill	Purpose	Specification Path
obsidian-markdown	Markdown notes with wikilinks, callouts, and frontmatter	skills/obsidian-markdown/SKILL.md
obsidian-bases	.base database definitions, filters, and formulas	skills/obsidian-bases/SKILL.md
json-canvas	JSON Canvas files (.canvas) for visual note mapping	skills/json-canvas/SKILL.md
obsidian-cli	Command‑line interface commands for the Obsidian app	skills/obsidian-cli/SKILL.md
defuddle	Experimental text‑to‑structure transformation	skills/defuddle/SKILL.md

Each skill references supplementary files in its references/ sub‑folder. For instance, obsidian-bases links to references/FUNCTIONS_REFERENCE.md for formula syntax, while obsidian-markdown points to references/PROPERTIES.md for frontmatter types.

How Agents Parse the Specification

An agent implementation reads the skill file by splitting the YAML header from the Markdown body. Below is a Python‑style pseudo‑code illustrating the parsing pattern used by agent frameworks:

import yaml, pathlib

def load_skill(name: str):
    """Load a skill definition from the repository."""
    skill_path = pathlib.Path('skills') / name / 'SKILL.md'
    text = skill_path.read_text(encoding='utf-8')
    
    # Split front‑matter (--- ... ---) from the body

    parts = text.split('---', 2)
    front = parts[1]
    body = parts[2]
    
    meta = yaml.safe_load('---' + front + '---')
    return {
        "name": meta["name"],
        "description": meta["description"],
        "markdown_context": body,
        "references_dir": skill_path.parent / 'references'
    }

# Load the Markdown skill

md_skill = load_skill('obsidian-markdown')
print(md_skill["description"])  # → Create and edit Obsidian‑flavored Markdown...

The agent treats the YAML as the function signature and the remaining Markdown as prompt context, enabling zero‑code integration with OpenAI function calling or similar frameworks.

Practical Examples

Generating Markdown with Frontmatter

The obsidian-markdown skill specifies exact syntax for notes. A valid generation target includes YAML frontmatter and Obsidian‑flavored elements:

---
title: Project Alpha
date: 2024-01-15
tags:
  - project
  - active
aliases:
  - Alpha Project
---

# Project Alpha

> [!important] Key Deadline
> The first milestone is due on ==January 30th==.

## Tasks

- [x] Initial planning
- [ ] Development phase

Source: skills/obsidian-markdown/SKILL.md sections on frontmatter and callouts.

Defining Base Database Views

The obsidian-bases skill documents the complete schema for .base files, including filters, formulas, and view configurations:

filters:
  and:
    - file.hasTag("task")
    - 'file.ext == "md"'

formulas:
  days_until_due: 'if(due, (date(due) - today()).days, "")'

properties:
  status:
    displayName: Status
  formula.days_until_due:
    displayName: "Days Until Due"

views:
  - type: table
    name: "Active Tasks"
    order:
      - file.name
      - status
      - formula.days_until_due
    summaries:
      formula.days_until_due: Average

Source: skills/obsidian-bases/SKILL.md schema section and references/FUNCTIONS_REFERENCE.md.

Building Canvas Files

For visual knowledge mapping, the json-canvas skill defines the JSON structure for nodes and edges:

{
  "id": "6f0ad84f44ce9c17",
  "type": "text",
  "x": 200,
  "y": 100,
  "width": 300,
  "height": 150,
  "text": "# New Idea\n\nExplore AI‑assisted note‑taking."

}

Source: skills/json-canvas/SKILL.md section on generic node attributes.

Executing CLI Commands

The obsidian-cli skill enables agents to interact with a running Obsidian instance via shell commands:

obsidian create name="Daily Log" content="# $(date)\n- [ ]"

Source: skills/obsidian-cli/SKILL.md common patterns section.

Summary

• The agent skills specification for Obsidian resides in the kepano/obsidian-skills repository under the skills/ directory.
• Each skill is a declarative Markdown file (SKILL.md) with a YAML front‑matter header containing name and description fields.
• The specification covers Markdown notes, Base databases, JSON Canvas files, CLI commands, and experimental text processing.
• Agents parse the YAML as metadata and the Markdown body as implementation context, requiring no custom code to support new capabilities.
• Reference documentation in references/ sub‑folders provides exhaustive schema details for validation and code generation.

Frequently Asked Questions

What makes the Obsidian agent skills specification different from a traditional API?

Unlike a code‑based API, the specification uses declarative markdown files with YAML headers. An agent reads the name and description fields to understand the capability, then parses the Markdown tables and code blocks to learn valid syntax. This allows the spec to evolve without changing the agent’s core logic—new skills are simply new folders in skills/.

Where does the agent find the schema for Obsidian Bases formulas and filters?

The complete schema for filters, formulas, and view definitions lives in skills/obsidian-bases/SKILL.md. Detailed function references—such as if(), date(), and today()—are documented in skills/obsidian-bases/references/FUNCTIONS_REFERENCE.md, which the main skill file links to via relative Markdown links.

Can an agent use these skills without internet access?

Yes. Because the specification is pure data stored in the repository, an agent can load all necessary context by reading local files from the skills/ directory. The YAML front‑matter and Markdown tables provide all required structural information, eliminating the need for external API calls or documentation lookups.

How does the specification handle visual formats like Canvas?

The json-canvas skill treats Canvas files as JSON data with a strict schema. The SKILL.md file defines tables for node attributes (id, type, x, y, width, height) and edge attributes (fromNode, toNode, label), allowing agents to programmatically generate .canvas files that render correctly in Obsidian’s visual editor.

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