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

> Master the Obsidian agent skills specification a YAML markdown format to teach AI agents how to create edit and validate Obsidian notes Canvas files and CLI commands without code.

- Repository: [Steph Ango/obsidian-skills](https://github.com/kepano/obsidian-skills)
- Tags: deep-dive
- Published: 2026-03-24

---

**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`](https://github.com/kepano/obsidian-skills/blob/main/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`](https://github.com/kepano/obsidian-skills/blob/main/SKILL.md) — The primary specification with YAML front‑matter and Markdown documentation.
- `references/` — Sub‑folder containing deep‑dive tables (e.g., [`PROPERTIES.md`](https://github.com/kepano/obsidian-skills/blob/main/PROPERTIES.md), [`EMBEDS.md`](https://github.com/kepano/obsidian-skills/blob/main/EMBEDS.md), [`CALLOUTS.md`](https://github.com/kepano/obsidian-skills/blob/main/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`](https://github.com/kepano/obsidian-skills/blob/main/SKILL.md) file contains a YAML block that acts as the function signature for the agent:

```yaml
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`](https://github.com/kepano/obsidian-skills/blob/main/skills/obsidian-markdown/SKILL.md) |
| **obsidian-bases** | `.base` database definitions, filters, and formulas | [`skills/obsidian-bases/SKILL.md`](https://github.com/kepano/obsidian-skills/blob/main/skills/obsidian-bases/SKILL.md) |
| **json-canvas** | JSON Canvas files (`.canvas`) for visual note mapping | [`skills/json-canvas/SKILL.md`](https://github.com/kepano/obsidian-skills/blob/main/skills/json-canvas/SKILL.md) |
| **obsidian-cli** | Command‑line interface commands for the Obsidian app | [`skills/obsidian-cli/SKILL.md`](https://github.com/kepano/obsidian-skills/blob/main/skills/obsidian-cli/SKILL.md) |
| **defuddle** | Experimental text‑to‑structure transformation | [`skills/defuddle/SKILL.md`](https://github.com/kepano/obsidian-skills/blob/main/skills/defuddle/SKILL.md) |

Each skill references supplementary files in its `references/` sub‑folder. For instance, `obsidian-bases` links to [`references/FUNCTIONS_REFERENCE.md`](https://github.com/kepano/obsidian-skills/blob/main/references/FUNCTIONS_REFERENCE.md) for formula syntax, while `obsidian-markdown` points to [`references/PROPERTIES.md`](https://github.com/kepano/obsidian-skills/blob/main/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:

```python
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:

```markdown
---
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`](https://github.com/kepano/obsidian-skills/blob/main/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:

```yaml
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`](https://github.com/kepano/obsidian-skills/blob/main/skills/obsidian-bases/SKILL.md) schema section and [`references/FUNCTIONS_REFERENCE.md`](https://github.com/kepano/obsidian-skills/blob/main/references/FUNCTIONS_REFERENCE.md).

### Building Canvas Files

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

```json
{
  "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`](https://github.com/kepano/obsidian-skills/blob/main/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:

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

```

*Source:* [`skills/obsidian-cli/SKILL.md`](https://github.com/kepano/obsidian-skills/blob/main/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`](https://github.com/kepano/obsidian-skills/blob/main/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`](https://github.com/kepano/obsidian-skills/blob/main/skills/obsidian-bases/SKILL.md). Detailed function references—such as `if()`, `date()`, and `today()`—are documented in [`skills/obsidian-bases/references/FUNCTIONS_REFERENCE.md`](https://github.com/kepano/obsidian-skills/blob/main/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`](https://github.com/kepano/obsidian-skills/blob/main/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.