obsidian-vault-manager

Context

• Current Directory: $PWD
• Plugin Location: ~/.claude/plugins/marketplaces/obsidian-vault-manager-plugin/

Task

Run the interactive setup wizard to configure Obsidian Vault Manager for this vault.

Important: You must run Claude Code from your Obsidian vault directory for this setup to work correctly.

Implementation

Execute the setup script from the plugin directory:

# Locate the plugin installation
PLUGIN_DIR="$HOME/.claude/plugins/marketplaces/obsidian-vault-manager-plugin"

# Check if plugin is installed
if [[ ! -d "$PLUGIN_DIR" ]]; then
    echo "❌ Plugin not found. Please install it first:"
    echo "   claude plugin add obsidian-vault-manager"
    exit 1
fi

# Run setup script
SETUP_SCRIPT="$PLUGIN_DIR/scripts/setup.sh"

if [[ -f "$SETUP_SCRIPT" ]]; then
    chmod +x "$SETUP_SCRIPT"
    bash "$SETUP_SCRIPT"
else
    echo "❌ Setup script not found at: $SETUP_SCRIPT"
    echo "Plugin may be corrupted. Try reinstalling:"
    echo "   claude plugin remove obsidian-vault-manager"
    echo "   claude plugin add obsidian-vault-manager"
    exit 1
fi

What This Does

The setup wizard will:

1. Detect Your Vault

   • Verifies you're in an Obsidian vault (checks for .obsidian/ folder)
   • Confirms the vault path

2. Check Dependencies

   • uv/uvx (for YouTube transcripts)
   • jq (for JSON processing)
   • python3 (for image path conversion)
   • git (for publishing)

3. Configure GitHub Pages (optional)

   • GitHub Pages repository path
   • GitHub Pages URL
   • Repository name

4. Create Configuration Files

   • .claude/settings.local.json (vault-specific settings)
   • .claude/config.sh (for bash scripts)
   • .claude/.gitignore (prevents committing personal paths)

After Setup

Your vault will have:

your-vault/
└── .claude/
    ├── settings.local.json    (vault-specific configuration)
    ├── config.sh              (script configuration)
    └── .gitignore             (prevents committing personal paths)

Troubleshooting

"Not in vault directory"

• Make sure you cd to your vault first
• Check that .obsidian/ folder exists

"Plugin not found"

• Install plugin: claude plugin add obsidian-vault-manager

"Missing dependencies"

• Install with: brew install uv jq git

Re-running Setup

You can run /setup again to:

• Update paths
• Reconfigure GitHub Pages
• Fix broken configuration

Existing configuration will be overwritten.

Task

Capture content to Obsidian vault with AI-powered smart tagging.

Input: $ARGUMENTS Today's Date: Run date "+%Y-%m-%d" to get current date

Content Routing

Analyze the input and process according to content type. Check patterns in this exact order:

Priority	Content Type	Pattern	Processing
1	YouTube	Domain is youtube.com or youtu.be	YouTube video note
2	GitHub	Domain is github.com	Repository analysis note
3	Web Article + Video	HTTP/HTTPS URL with ?y= param (non-YouTube domain)	Study guide WITH video transcript
4	Web Article	Other http:// or https:// URL	Study guide note
5	Plain Text	No URL pattern	Idea note

IMPORTANT: A URL like https://example.com/page?y=VIDEO_ID is a Web Article + Video (Priority 3), NOT a YouTube video. The ?y= param indicates an embedded video to include in the study guide.

---

YouTube Video Processing

ONLY for URLs where domain is youtube.com or youtu.be:

1. Extract video ID from URL
2. Use mcp__MCP_DOCKER__get_video_info for metadata (title, channel, duration)
3. Use mcp__MCP_DOCKER__get_transcript for transcript
4. Read template: cat ~/.claude/skills/obsidian-vault-manager/templates/youtube-note-template.md
5. Create note with mcp__MCP_DOCKER__obsidian_append_content (creates new file)

Note: URLs like https://othersite.com/page?y=VIDEO_ID are NOT YouTube - use "Web Article + Video" processing instead.

Filename: {date}-{channel-name}-{descriptive-title}-{video_id}.md CRITICAL: Include video ID in filename to ensure each video gets a separate note file.

Required sections:

• Frontmatter with cover, url, channel, video_date, duration
• Clickable YouTube thumbnail
• Description and learning objectives
• Structured curriculum with timestamps
• Key takeaways
• Rating section

---

Web Article + Video Processing (Priority 3)

For URLs with ?y=VIDEO_ID param on NON-YouTube domains (e.g., https://agenticengineer.com/page?y=abc123):

This is a web article with an embedded video. Create a study guide that includes BOTH:

1. Fetch article content using mcp__MCP_DOCKER__firecrawl_scrape or WebFetch
2. Extract video ID from ?y= parameter
3. Use mcp__MCP_DOCKER__get_video_info for video metadata
4. Use mcp__MCP_DOCKER__get_transcript for video transcript
5. Create comprehensive study guide combining article + video content:
   • Learning objectives (checkboxed)
   • Key concepts from article AND video
   • Course structure (if applicable)
   • Study strategies
   • Self-assessment questions
   • Progress tracking
6. Create note with mcp__MCP_DOCKER__obsidian_append_content (creates new file)

Filename: {date}-{source-name}-{topic}-study-guide.md Type: study-guide Status: processing

---

Web Article / Study Guide Processing (Priority 4)

For other non-YouTube, non-GitHub URLs (no ?y= param):

1. Fetch content using WebFetch or mcp__MCP_DOCKER__fetch or mcp__MCP_DOCKER__firecrawl_scrape
2. Analyze content and create comprehensive study guide with:
   • Learning objectives (checkboxed)
   • Key concepts breakdown
   • Study strategies
   • Self-assessment questions
   • Progress tracking
3. Create note with mcp__MCP_DOCKER__obsidian_append_content (creates new file)

Filename: {date}-{source-name}-{topic}-study-guide.md Status: processing (active study material)

---

Idea Processing

For plain text (no URL):

1. Analyze the text for main concepts
2. Generate smart tags from taxonomy
3. Create note with sections:
   • Core idea explanation
   • Why it matters
   • Related concepts
   • Next steps (if actionable)
4. Create note with mcp__MCP_DOCKER__obsidian_append_content (creates new file)

Filename: {date}-{3-5-word-idea-name}.md Status: inbox

---

Tag Taxonomy

Content Types: video, article, study-guide, idea, repository Topics: AI, Claude, productivity, knowledge-management, development, learning, research, writing, tools, business, design, automation, data-science, web-development, personal-growth, finance, coding, architecture Status: inbox (default), processing (for study guides) Metadata: tutorial, deep-dive, quick-read, technical, conceptual, actionable, inspiration

Critical Requirements

1. MUST call mcp__MCP_DOCKER__obsidian_append_content to save the file (creates new file if doesn't exist)
2. Use 6-8 tags total from the taxonomy
3. Include proper frontmatter with all required fields
4. For YouTube: include clickable thumbnail and structured curriculum
5. For articles with embedded videos: capture BOTH article content AND video transcript

Task

Publish note to GitHub Pages using the bundled publish script.

Input: $ARGUMENTS (filename with or without .md extension) Operation: Publish to GitHub Pages with image handling

Implementation

Run the bundled publish script directly:

SKILL_DIR="$HOME/.claude/skills/obsidian-vault-manager"
"$SKILL_DIR/scripts/core/publish.sh" "$ARGUMENTS"

The script will:

1. Validate note exists in vault
2. Find all image references in note
3. Copy images from vault to sharehub repository
4. Convert image paths (./images/ → /sharehub/images/)
5. Copy note with converted paths to sharehub/documents/
6. Git commit and push to GitHub
7. Output the published URL

After Script Completes

1. Wait for GitHub Pages deployment (~60 seconds):

   sleep 60
   

2. Verify published page using mcp__fetch__fetch

Publishing Configuration

• Vault Path: /Users/zorro/Documents/Obsidian/Claudecode
• Sharehub Path: /Users/zorro/Dev/sharehub
• Repository: ZorroCheng-MC/sharehub
• GitHub Pages URL: https://zorrocheng-mc.github.io/sharehub

Image Path Conversion

The script automatically converts:

• ./images/file.jpg → /sharehub/images/file.jpg
• images/file.jpg → /sharehub/images/file.jpg
• External URLs (https://...) remain unchanged

Expected Output

After successful publish:

• ✅ Images copied to sharehub repository
• ✅ Note copied with converted paths
• ✅ Git commit created with proper message
• ✅ Pushed to GitHub
• ✅ GitHub Pages deployment triggered
• ✅ Published URL: https://zorrocheng-mc.github.io/sharehub/documents/{filename}.html

Examples

Publish with extension:

/publish my-article.md

Publish without extension (auto-adds .md):

/publish my-article

Password Protection (Sharehub Feature)

Sharehub supports password-protected documents via frontmatter!

To Make a Document Private:

Add access: private to the frontmatter:

---
title: "Confidential Document"
access: private
---

How it works:

• Documents without access: private → Publicly accessible
• Documents with access: private → Password-protected
• Password: "maco" (shared password for all private documents)
• Session: Password remembered until browser closed

Example: Publishing Private Document

Frontmatter:

---
title: "Claude Dev Users: Multi-User Docker Environment"
tags:
  - repository
  - docker
  - infrastructure
access: private
---

Result:

• Document published to sharehub
• Requires password "maco" to view
• Listed in index with 🔒 lock icon (after login)

Index Page Behavior

• Before login: Shows only public documents
• After login: Shows all documents (public + private) with 🔒 icons

Publishing Workflow

1. Add access: private to frontmatter (if needed)
2. Run /publish filename.md
3. Script publishes to sharehub/documents/
4. GitHub Pages builds (~60 seconds)
5. Document accessible with password protection

Important Notes

• Default: Documents are public unless access: private is specified
• Password: All private documents use "maco"
• No folder restrictions: Protection is tag-based, not folder-based
• Session storage: Login persists until browser closed

Quality Checklist

Before publishing, verify:

• Note has proper frontmatter (title, tags, date)
• Add access: private if document contains sensitive information
• Images exist in vault at specified paths
• Image paths are relative (./images/ or images/)
• Note is ready for viewing (public or password-protected)

Task

Execute the obsidian-vault-manager skill for idea capture.

Input: $ARGUMENTS (Plain text idea or concept) Operation: Idea note creation Today's Date: Run date "+%Y-%m-%d" to get current date

Process

The skill will:

1. Analyze idea content and determine main concepts
2. Apply bundled template: templates/idea-template.md
3. Analyze content and apply AI-powered smart tagging (using tag taxonomy)
4. Generate smart filename: {date}-{3-5-word-idea-name}.md
5. Substitute all template variables with analyzed data
6. Create note in vault using MCP Obsidian tools

Tag Taxonomy Reference

Topics: AI, productivity, knowledge-management, development, learning, research, writing, tools, business, design, automation, data-science, web-development, personal-growth, finance Status: inbox (default for new ideas) Metadata: actionable, conceptual, inspiration, high-priority

Expected Output

A comprehensive idea note with:

• Proper frontmatter (title, tags, date, type, status, priority)
• Core idea explanation
• Why it matters section
• Related concepts
• Next steps (if actionable)
• Tags analysis and filtering suggestions
• Semantic search suggestions

File naming format: [date]-[3-5-word-idea-name].md Tag count: 5-8 tags total

Examples

Input: "Use AI to automatically categorize notes" → 2025-10-23-ai-note-categorization.md

Input: "Knowledge compounds when connected properly" → 2025-10-23-knowledge-compound-connections.md

Task

Execute the obsidian-vault-manager skill for YouTube note capture.

Input: $ARGUMENTS (YouTube URL or video ID) Operation: YouTube video note creation Today's Date: Run date "+%Y-%m-%d" to get current date

Process

The skill will:

1. Extract video ID from URL/argument
2. Use bundled script: scripts/core/fetch-youtube-transcript.sh to fetch transcript
3. Fetch video metadata from YouTube page
4. Apply bundled template: templates/youtube-note-template.md
5. Analyze content and apply AI-powered smart tagging (using tag taxonomy)
6. Substitute all template variables with analyzed data
7. Create note in vault using MCP Obsidian tools

Tag Taxonomy Reference

Topics: AI, productivity, knowledge-management, development, learning, research, writing, tools, business, design, automation, data-science, web-development, personal-growth, finance Status: inbox (default for new videos) Metadata: tutorial, deep-dive, quick-read, technical, conceptual, actionable, inspiration

Expected Output

A comprehensive video note with:

• Proper frontmatter (title, tags, url, cover, date, type, status, priority, duration, channel)
• Clickable YouTube thumbnail
• Description and learning objectives
• Structured curriculum with timestamps
• Key takeaways and insights
• Rating section
• Tags analysis and filtering suggestions
• Related topics

File naming format: [date]-[creator-name]-[descriptive-title].md Tag count: 6-8 tags total

Task

Execute the obsidian-vault-manager skill for study guide creation.

Input: $ARGUMENTS (file path, URL, or direct text) Operation: Study guide creation Today's Date: Run date "+%Y-%m-%d" to get current date

Process

The skill will:

1. Fetch content from URL, file, or direct text
2. Apply bundled template: templates/study-guide-template.md
3. Analyze content complexity, topics, and learning requirements
4. Apply AI-powered smart tagging (using tag taxonomy)
5. Generate structured learning plan with objectives and assessments
6. Substitute all template variables with analyzed data
7. Create note in vault using MCP Obsidian tools

Tag Taxonomy Reference

Topics: AI, productivity, knowledge-management, development, learning, research, writing, tools, business, design, automation, data-science, web-development, personal-growth, finance Status: processing (default for study guides - active learning) Metadata: deep-dive, technical, conceptual, actionable, tutorial

Expected Output

A comprehensive study guide with:

• Proper frontmatter (title, tags, source, date, type, status, difficulty, estimated-time, priority)
• Overview with subject and generated date
• Learning objectives (specific, measurable, checkboxed)
• Study plan with time estimates and difficulty level
• Structured content breakdown (weekly/modular)
• Study strategies (material-specific and active learning techniques)
• Self-assessment questions (intermediate and final)
• Progress tracking section
• Related notes and connections
• Tags analysis with filtering suggestions
• Semantic search suggestions

File naming format: [date]-[topic-name]-study-guide.md Tag count: 6-8 tags total Status: Always processing (active study material)

Examples

Input (URL): "https://example.com/machine-learning-course" → 2025-10-28-machine-learning-study-guide.md

Input (File): "react-advanced-patterns.md" → 2025-10-28-react-advanced-study-guide.md

Input (Text): "Deep dive into distributed systems architecture" → 2025-10-28-distributed-systems-study-guide.md

Context

• Search Query: $ARGUMENTS
• API Configuration: Local REST API running on https://127.0.0.1:27124/
• Smart Connections Endpoint: /search/smart

Your task

Execute a semantic search in the Obsidian vault using the Smart Connections plugin via curl.

Run this single command to perform the search:

curl -k -X POST \
  https://127.0.0.1:27124/search/smart \
  -H "Authorization: Bearer $(grep LOCAL_REST_API_KEY .env | cut -d'=' -f2)" \
  -H "Content-Type: text/plain" \
  -d "{\"query\": \"$ARGUMENTS\", \"filter\": {\"limit\": 5}}" | jq .

Context

• Today's Date: !date "+%Y-%m-%d"
• Target: $ARGUMENTS (defaults to all .md files if not specified)

Tag Taxonomy Reference

Use the same taxonomy as /capture:

Content Types: idea, video, article, study-guide, repository, reference, project Topics: AI, Claude, Gemini, product, marketing, projects, workflow, architecture, design, UI-UX, coding, productivity, knowledge-management, development, learning, research, writing, tools, business, automation, data-science, web-development, personal-growth, finance Status: inbox, processing, evergreen, published, archived, needs-review Metadata: high-priority, quick-read, deep-dive, technical, conceptual, actionable, tutorial, inspiration

Your Task

Step 1: Discover Files to Tag

# If user provided pattern:
find . -name "$ARGUMENTS" -type f

# If no arguments (tag everything):
find . -name "*.md" -type f -not -path "./.obsidian/*" -not -path "./.claude/*"

Step 2: Process Each File

For each discovered file:

1. Read the file content

2. Analyze existing frontmatter:

   • Check if tags: field exists
   • Check if tags are already comprehensive (5+ tags from taxonomy)

3. Skip if already well-tagged (has 5+ taxonomy-compliant tags)

4. Analyze content to determine:

   • Content type (from filename, existing tags, content)
   • Main topics (2-4 from content analysis)
   • Status (infer from content or default to evergreen for old notes)
   • Metadata characteristics

5. Generate enhanced tag array:

   tags: [{content-type}, {topic1}, {topic2}, {topic3}, {status}, {metadata}]
   

6. Update frontmatter while preserving existing data:

   ---
   title: "{existing or generated}"
   tags: [{enhanced-tag-array}]
   date: "{existing or file creation date}"
   type: "{content-type}"
   status: "{status}"
   # preserve any other existing fields
   ---
   

Step 3: Report Progress

After processing each batch of 5-10 files, report:

✅ Tagged 10 files:
   - 3 ideas tagged with [idea, productivity, ...]
   - 2 videos tagged with [video, AI, learning, ...]
   - 5 articles tagged with [article, development, ...]

📊 Progress: 10/47 files processed
🏷️  Total tags added: 73 tags

Step 4: Summary Report

After all files processed:

# Bulk Tagging Report

## Summary
- **Files processed:** 47
- **Files updated:** 43
- **Files skipped:** 4 (already well-tagged)
- **Total tags added:** 312
- **Average tags per note:** 7.3

## Tag Distribution

### By Content Type
- idea: 15 notes
- video: 8 notes
- article: 12 notes
- study-guide: 6 notes
- repository: 2 notes

### By Topic
- AI: 23 notes
- productivity: 18 notes
- knowledge-management: 15 notes
- development: 12 notes
- learning: 10 notes

### By Status
- inbox: 12 notes
- evergreen: 28 notes
- published: 7 notes

## Bases Filtering Suggestions

You can now create Bases views like:
1. **AI Learning Pipeline**: `type = video AND topic = AI AND status = inbox`
2. **Quick Wins**: `metadata = quick-read AND priority = high-priority`
3. **Technical Deep Dives**: `metadata = technical AND metadata = deep-dive`
4. **Actionable Items**: `metadata = actionable AND status != archived`

## Next Steps
1. Review auto-tagged notes in Obsidian
2. Create Bases views using these tags
3. Refine tags manually if needed
4. Run `/bulk-auto-tag` periodically for new notes

Important Rules

1. Preserve existing data: Never delete user-added tags or properties
2. Merge intelligently: Combine AI tags with existing tags (deduplicate)
3. Be conservative: If uncertain about content type, default to reference
4. Handle errors gracefully: Skip files with invalid frontmatter, report errors
5. Respect user intent: If a file has explicit tags, enhance rather than replace

Example Transformations

Before (minimal tags):

---
tags: [idea]
date: 2025-09-15
---

# AI-powered tagging
Use Claude to auto-tag notes for better organization

After (enhanced tags):

---
title: "AI-powered tagging"
tags: [idea, AI, knowledge-management, tools, evergreen, actionable, technical]
date: 2025-09-15
type: idea
status: evergreen
priority: medium
---

# AI-powered tagging
Use Claude to auto-tag notes for better organization

Performance Considerations

• Process files in batches of 10
• Show progress every batch
• Allow user to cancel with Ctrl+C
• Estimate time for large vaults: ~2-3 seconds per file

Safety Features

1. Dry run mode (optional): Show what would be changed without modifying files
2. Backup reminder: Remind user to commit to git before bulk operations
3. Undo support: Provide git commands to rollback if needed