AGENTS/skills/obsidian/SKILL.md

name, description, compatibility

name	description	compatibility
obsidian	Obsidian Local REST API integration for knowledge management. Use when: (1) Creating, reading, updating, or deleting notes in Obsidian vault, (2) Searching vault content by title, content, or tags, (3) Managing daily notes and journaling, (4) Working with WikiLinks and vault metadata. Triggers: 'Obsidian', 'note', 'vault', 'WikiLink', 'daily note', 'journal', 'create note'.	opencode

Obsidian

Knowledge management integration via Obsidian Local REST API for vault operations, note CRUD, search, and daily notes.

Prerequisites

• Obsidian Local REST API plugin installed and enabled in Obsidian
• API server running on default port 27124 (or configured custom port)
• Vault path configured in plugin settings
• API key set (optional, if authentication enabled)

API endpoints available at http://127.0.0.1:27124 by default.

Core Workflows

List Vault Files

Get list of all files in vault:

curl -X GET "http://127.0.0.1:27124/list"

Returns array of file objects with path, mtime, ctime, size.

Get File Metadata

Retrieve metadata for a specific file:

curl -X GET "http://127.0.0.1:27124/get-file-info?path=Note%20Title.md"

Returns file metadata including tags, links, frontmatter.

Create Note

Create a new note in the vault:

curl -X POST "http://127.0.0.1:27124/create-note" \
  -H "Content-Type: application/json" \
  -d '{"content": "# Note Title\n\nNote content..."}'

Use path parameter for specific location:

{
  "content": "# Note Title\n\nNote content...",
  "path": "subdirectory/Note Title.md"
}

Read Note

Read note content by path:

curl -X GET "http://127.0.0.1:27124/read-note?path=Note%20Title.md"

Returns note content as plain text or structured JSON with frontmatter parsing.

Update Note

Modify existing note:

curl -X PUT "http://127.0.0.1:27124/update-note" \
  -H "Content-Type: application/json" \
  -d '{"path": "Note Title.md", "content": "# Updated Title\n\nNew content..."}'

Delete Note

Remove note from vault:

curl -X DELETE "http://127.0.0.1:27124/delete-note?path=Note%20Title.md"

Warning: This operation is irreversible. Confirm with user before executing.

Search Notes

Find notes by content, title, or tags:

# Content search
curl -X GET "http://127.0.0.1:27124/search?q=search%20term"

# Search with parameters
curl -X GET "http://127.0.0.1:27124/search?q=search%20term&path=subdirectory&context-length=100"

Returns array of matches with file path and context snippets.

Daily Notes

Get Daily Note

Retrieve or create daily note for specific date:

# Today
curl -X GET "http://127.0.0.1:27124/daily-note"

# Specific date (YYYY-MM-DD)
curl -X GET "http://127.0.0.1:27124/daily-note?date=2026-02-03"

Returns daily note content or creates using Obsidian's Daily Notes template.

Update Daily Note

Modify today's daily note:

curl -X PUT "http://127.0.0.1:27124/daily-note" \
  -H "Content-Type: application/json" \
  -d '{"content": "## Journal\n\nToday I learned..."}'

Get Vault Info

Retrieve vault metadata:

curl -X GET "http://127.0.0.1:27124/vault-info"

Returns vault path, file count, and configuration details.

Note Structure Patterns

Frontmatter Conventions

Use consistent frontmatter for note types:

---
date: 2026-02-03
created: 2026-02-03T10:30:00Z
type: note
tags: #tag1 #tag2
status: active
---

WikiLinks

Reference other notes using Obsidian WikiLinks:

• [[Note Title]] - Link to note by title
• [[Note Title|Alias]] - Link with custom display text
• [[Note Title#Heading]] - Link to specific heading
• ![[Image.png]] - Embed images or media

Tagging

Use tags for categorization:

• #tag - Single-word tag
• #nested/tag - Hierarchical tags
• Tags in frontmatter for metadata
• Tags in content for inline categorization

Workflow Examples

Create Brainstorm Note

curl -X POST "http://127.0.0.1:27124/create-note" \
  -H "Content-Type: application/json" \
  -d '{
    "path": "03-resources/brainstorms/2026-02-03-Topic.md",
    "content": "---\ndate: 2026-02-03\ncreated: 2026-02-03T10:30:00Z\ntype: brainstorm\nframework: pros-cons\nstatus: draft\ntags: #brainstorm #pros-cons\n---\n\n# Topic\n\n## Context\n\n## Options\n\n## Decision\n"
  }'

Append to Daily Journal

# Get current daily note
NOTE=$(curl -s "http://127.0.0.1:27124/daily-note")

# Append content
curl -X PUT "http://127.0.0.1:27124/daily-note" \
  -H "Content-Type: application/json" \
  -d "{\"content\": \"${NOTE}\n\n## Journal Entry\n\nLearned about Obsidian API integration.\"}"

Search and Link Notes

# Search for related notes
curl -s "http://127.0.0.1:27124/search?q=Obsidian"

# Create note with WikiLinks to found notes
curl -X POST "http://127.0.0.1:27124/create-note" \
  -H "Content-Type: application/json" \
  -d '{
    "path": "02-areas/Obsidian API Guide.md",
    "content": "# Obsidian API Guide\n\nSee [[API Endpoints]] and [[Workflows]] for details."
  }'

Integration with Other Skills

From Obsidian	To skill	Handoff pattern
Note created	brainstorming	Create brainstorm note with frontmatter
Daily note updated	reflection	Append conversation analysis to journal
Research note	research	Save research findings with tags
Project note	task-management	Link tasks to project notes
Plan document	plan-writing	Save generated plan to vault
Vault search	qmd	Search vault content via qmd hybrid search
Memory note	qmd	Create/read memory notes in 80-memory/

Best Practices

1. Use paths consistently - Follow PARA structure or vault conventions
2. Include frontmatter - Enables search and metadata queries
3. Use WikiLinks - Creates knowledge graph connections
4. Validate paths - Check file existence before operations
5. Handle errors - API may return 404 for non-existent files
6. Escape special characters - URL-encode paths with spaces or symbols
7. Backup vault - REST API operations modify files directly

---

Memory System

Memory storage and retrieval is handled by the qmd skill (skills/qmd/SKILL.md).

• Search: Use qmd for searching vault content (hybrid BM25 + vector + reranking)
• Write: Use this skill's REST API or direct filesystem writes for creating/updating notes
• Structure: 80-memory/ folder with subdirectories (preferences, facts, decisions, entities, other, sessions)

See the qmd skill for memory workflows, session summaries, and auto-recall patterns.

---

Error Handling

Common HTTP status codes:

• 200 OK - Success
• 404 Not Found - File or resource doesn't exist
• 400 Bad Request - Invalid parameters or malformed JSON
• 500 Internal Server Error - Plugin or vault error

Check API response body for error details before retrying operations.