home / skills / bdambrosio / cognitive_workbench / search-obsidian

search-obsidian skill

safe

This skill enables fast Obsidian note search via the Local REST API, returning structured JSON notes with uri, domain, format, and character count.

npx playbooks add skill bdambrosio/cognitive_workbench --skill search-obsidian

Review the files below or copy the command above to add this skill to your agents.

Files (3)

Skill.md

1.2 KB

---
name: search-obsidian
type: python
description: "Search Obsidian notes using Obsidian Local REST API. Returns Collection of JSON Notes with fields text, metadata.uri (alias: source_url), metadata.domain, format, char_count"
---

# search-obsidian

Search Obsidian vault using Local REST API. Returns Collection of structured Notes.

## Input

- `query`: Query string (literal search text, NOT a variable)

## Output

Success (`status: "success"`):
- `resource_id`: Collection ID containing structured Notes, each with:
  - `text`: Note content
  - `format`: "markdown"
  - `metadata.uri`: Obsidian URI
  - `metadata.domain`: "obsidian"
  - `char_count`: Character count

## Behavior

- Searches by filename first, then content match
- Only searches markdown files (`.md`)
- Returns structured Notes matching search-web/semantic-scholar format

## Requirements

- Obsidian Local REST API plugin installed and enabled
- `OBSIDIAN_MCP_URL` environment variable (default: `http://127.0.0.1:27123`)
- `OBSIDIAN_MCP_API_KEY` environment variable

## Examples

```json
{"type":"search-obsidian","query":"neural networks","out":"$notes"}
{"type":"summarize","target":"$notes","focus":"what are neural networks","out":"$summary"}
```

Overview

This skill lets you search an Obsidian vault through the Obsidian Local REST API and returns a collection of structured JSON Notes. It focuses on Markdown files and provides note text plus metadata fields like an Obsidian URI, domain, format, and character count. Use it to integrate Obsidian content into pipelines for search, summarization, or downstream analysis.

How this skill works

The skill queries the Obsidian Local REST API (configured via OBSIDIAN_MCP_URL and OBSIDIAN_MCP_API_KEY) and searches Markdown files by filename first, then by content. It returns a Collection resource containing Notes with fields: text, format (markdown), metadata.uri (alias source_url), metadata.domain (obsidian), and char_count. Only .md files are considered and results are structured for easy consumption by search and summarization tools.

When to use it

You need to index or search notes stored in an Obsidian vault from external tools.
You want structured note content (text + metadata) for summarization or semantic search.
You are building automation that pulls specific notes by filename or content match.
You need a repeatable programmatic way to extract Markdown notes for analysis or export.
You want to combine Obsidian content with other knowledge sources in an application pipeline.

Best practices

Ensure the Obsidian Local REST API plugin is installed and enabled in the vault before using the skill.
Set environment variables OBSIDIAN_MCP_URL and OBSIDIAN_MCP_API_KEY for secure, repeatable access.
Prefer targeted filename queries when you know the note id or title for faster, more precise results.
Validate char_count and metadata.uri in downstream logic to avoid relying on display-only fields.
Filter or post-process results if your vault contains many large notes to limit payload size.

Example use cases

Run a query like “neural networks” to retrieve all matching Markdown notes, then summarize findings for a literature review.
Automate extraction of meeting notes tagged with a specific project name for project dashboards.
Feed returned notes into a semantic search index to power a knowledge assistant that covers personal research.
Pull technical design documents from Obsidian to generate release notes or API documentation drafts.

FAQ

What setup is required to use this skill?

Install and enable the Obsidian Local REST API plugin, then set OBSIDIAN_MCP_URL and OBSIDIAN_MCP_API_KEY environment variables.

Does this search non-Markdown files?

No. The skill only searches and returns .md Markdown files from the vault.