Obsidian

Obsidian Vault Manager

Assets

This skill uses a modular assets architecture. Detailed workflows, templates, and helpers are in the assets/ directory:

• assets/modes/ - 2 operation modes with detailed workflows
• assets/helpers/ - Shared helpers for frontmatter, cross-refs, ranking, batch operations

See assets/README.md for the directory index.

Metadata note: This file's YAML frontmatter defines runtime behavior (auto_invoke triggers, allowed-tools, scope). The manifest.json defines registry metadata (version, tags, providers, dependencies). The frontmatter is consumed by the Claude Code skill loader; the manifest is consumed by the skills CLI for installation and updates.

Purpose

Unified skill for all Obsidian vault operations. Acts as a bidirectional knowledge bridge between the agent workspace and your Obsidian vault (MCP preferred, filesystem fallback when unavailable):

• SYNC mode: Write documents from workspace to vault (markdown reports, plans, analysis)
• READ mode: Read, search, and reason over vault notes as contextual knowledge source

Combines the capabilities of the former obsidian-sync and obsidian-reader skills into one cohesive tool with progressive disclosure.

Language Support (i18n)

This skill supports bilingual operation (English + Spanish):

• Trigger keywords: Both English (sync, read, search) and Spanish (guardar, lee, busca) are recognized for mode detection.
• ## Referencias section header: Uses the Spanish form intentionally as an Obsidian convention adopted by this project. All documents produced by this skill use ## Referencias (not ## References).
• Example queries: Documentation includes examples in both languages to reflect real bilingual usage.
• Output language: The skill responds in the same language the user uses. If the user writes in Spanish, respond in Spanish. If in English, respond in English. Document content is never translated — it is synced/read exactly as-is.

Convention: ## Referencias is a fixed section header. Never translate it to ## References in generated documents.

Critical Rules

RULE 1 — MODE DETECTION: AUTO-SELECT FROM USER INTENT

Detect the operation mode from the user's input. Never force a mode that doesn't match the scenario.

RULE 2 — PRESERVE CONTENT INTEGRITY (SYNC mode)

Read source files completely before writing. Never modify document body content (headings, paragraphs, tables, code blocks, ## Referencias section). Only add/merge frontmatter metadata. Cross-reference fixes update the related frontmatter array only — never the document body.

RULE 3 — NEVER FABRICATE CONTENT (READ mode)

Only report information that exists verbatim in notes. Quote sources with paths. Distinguish between "the note says X" and "I interpret X based on notes".

RULE 4 — FOLLOW OBSIDIAN MARKDOWN STANDARD

All operations follow the Obsidian markdown standard specification for frontmatter, wiki-links, types, and cross-references.

Tool Dependencies

This skill uses native Claude Code tools only: Read, Write, Edit, Glob, Grep, Bash, AskUserQuestion. No MCP or external dependencies required.

Operation Modes

Mode Detection

Auto-detect from user intent using these signals:

Ambiguous intent resolution: If the user's intent does not clearly match SYNC or READ signals (e.g., "help me with obsidian", "manage my notes", "obsidian" with no verb), ask the user to clarify:

AskUserQuestion:
  question: "What would you like to do with your Obsidian vault?"
  header: "Mode"
  options:
    - label: "Read / Search"
      description: "Read notes, search for information, or get project context from your vault"
    - label: "Sync / Write"
      description: "Save or sync documents from your workspace to your vault"

Mode Capabilities Matrix

Asset Loading (Mode-Gated)

After detecting the mode, read ONLY the assets listed for that mode. Do NOT read assets for other modes — they waste context tokens.

Each mode asset references its required helpers and standards internally. Read them on-demand as the mode workflow instructs — not upfront.

For MCP tool parameter contracts (needed in both modes), see assets/helpers/tool-reference.md — read only if ToolSearch output is insufficient.

Quick Start

SYNC Mode

Use to save documents from workspace to your Obsidian vault:

Sync this report to obsidian.

Assets to read now: assets/modes/SYNC.md (references frontmatter-generator, cross-ref-validator, batch-sync-pattern on-demand)

READ Mode

Use to read, search, and reason over your vault notes:

Read my vault notes about the architecture.

Assets to read now: assets/modes/READ.md (references priority-ranking, obsidian-linter on-demand)

Mode Workflows

SYNC Mode - Write to Obsidian Vault

Sync markdown documents from workspace to Obsidian vault with proper frontmatter and cross-reference validation.

Assets to read now: assets/modes/SYNC.md (references frontmatter-generator, cross-ref-validator, batch-sync-pattern on-demand)

Quick summary:

1. Identify source files (Glob workspace docs)
2. Detect access mode (MCP or filesystem fallback)
3. Browse vault and ask user for destination
4. Read source files
5. Generate frontmatter (→ SYNC.md references frontmatter-generator)
6. Write to vault with mcp__obsidian__write_note
7. Validate cross-references (→ SYNC.md references cross-ref-validator)
8. Report results

READ Mode - Read from Obsidian Vault

Read, search, and reason over vault notes to provide contextual knowledge for decision-making.

Assets to read now: assets/modes/READ.md (references priority-ranking, obsidian-linter on-demand)

Quick summary:

1. Load MCP tools (fallback to filesystem if MCP unavailable)
2. Parse user intent (read note, search, get project context, answer question)
3. Execute operation (search/read/reason)
4. Rank results by priority (→ READ.md references priority-ranking)
5. Present structured output with source citations

Configuration Resolution

{vault_destination} is resolved at runtime — SYNC mode browses the vault and asks the user where to save. No pre-configuration or persistence needed. See SYNC.md Step 3.

Staging-aware: When the user says "sync my output to vault", SYNC mode detects .agents/ directories from producer skills (universal-planner, code-analyzer), lists available output, lets the user pick, and syncs to the chosen vault destination.

Shared Helpers

• frontmatter-generator - Generate Obsidian frontmatter following universal schema
• cross-ref-validator - Validate bidirectional references
• batch-sync-pattern - Optimized batch file sync workflow
• priority-ranking - Rank search results by relevance

Obsidian Output Standard

All operations follow the internal Obsidian markdown standard:

1. Frontmatter: Universal schema with title, date, project, type, status, version, tags, changelog, related
2. Type taxonomy: 14 document types (analysis, plan, sprint-plan, technical-report, etc.)
3. Wiki-links: [[note-name]] format, never markdown links
4. Bidirectional refs: If A→B, then B→A
5. Status transitions: draft → active → completed → archived

For compliance validation, see assets/validators/obsidian-linter.md.

Integration with Other Skills

Composition pattern:

Producer skill generates docs → obsidian SYNC mode writes to vault
Agent needs context → obsidian READ mode retrieves from vault

Cross-Skill Invocation

When another skill or agent needs to invoke obsidian, use this priority order:

Priority 1: Skill Tool (recommended)

If running in Claude Code with skills loaded:

Skill("obsidian")

Then describe the operation (e.g., "sync the files in .agents/staging/code-analyzer/ to the vault").

Priority 2: Natural Language Trigger

Say a phrase that matches auto_invoke:

• "Sync the output to obsidian"
• "Save these reports to the vault"
• "Guardar en obsidian"

Priority 3: Direct SKILL.md Read (subagents without skill context)

If the Skill tool is unavailable (e.g., team subagents via Task tool), read the SKILL.md directly:

Read: cognitives/skills/integrations/obsidian/SKILL.md

Then follow the SYNC or READ mode workflow. NEVER call mcp__obsidian__* tools without reading this skill first.

Best Practices

SYNC mode:

• Verify source files exist before syncing
• Always ask user where to save (never assume destination)
• Validate cross-references after batch syncs
• Report exact vault paths where files were saved

READ mode:

• Try MCP first, fallback to filesystem if unavailable
• Scope searches to relevant folders (don't search entire vault unnecessarily)
• Always cite sources with exact note paths
• Distinguish quoted content from interpretation

Limitations

• Markdown only: Handles .md files, not binary assets/images
• Single vault: Operates on one vault at a time
• No bidirectional sync: Writes TO vault (SYNC) or reads FROM vault (READ), not both-way sync
• Read-only in READ mode: Cannot modify notes in READ mode (use SYNC for writing)
• Search is regex/literal: Uses Grep — no fuzzy search. Broaden the pattern if results are sparse.

Troubleshooting