name	obsidian-vault-manager
description	Manage Obsidian knowledge base - capture ideas, YouTube videos, articles, repositories, create study guides, and publish to GitHub Pages. Use smart AI tagging for automatic organization.
trigger	When user wants to capture content, create study guides, search vault, tag notes, or publish to GitHub Pages

Obsidian Vault Manager

Manage an AI-powered Obsidian knowledge base with automatic organization and GitHub Pages publishing.

Vault Configuration

Vault Path: /Users/zorro/Documents/Obsidian/Claudecode
Publishing Folder: documents/ (auto-deploys to GitHub Pages)
GitHub Repository: ZorroCheng-MC/sharehub

Tag Taxonomy (STRICT - Use Only These)

Content Type Tags (choose 1)

idea - Random thoughts, concepts, brainstorms
video - YouTube videos, lectures
article - Web articles, blog posts
study-guide - Learning materials, courses
repository - Code repositories, technical analysis
reference - Documentation, quick lookups
project - Project notes, planning

Status Tags (choose 1)

inbox - Just captured, needs processing
processing - Currently working on
evergreen - Timeless, permanent knowledge
published - Shared publicly
archived - Done, historical reference
needs-review - Requires attention

Core Operations

1. Capture Content (Universal Inbox)

Intelligently route content based on type and create properly tagged notes.

YouTube Videos

Bundled Resources:

Script: scripts/core/fetch-youtube-transcript.sh - Fetches transcript via uvx
Template: templates/youtube-note-template.md - Note structure
Validation: scripts/validation/validate-frontmatter.py - Quality check

When user provides a YouTube URL:

Step 1: Extract Video ID and Fetch Transcript

Extract VIDEO_ID from URL (e.g., https://youtu.be/VIDEO_ID or https://www.youtube.com/watch?v=VIDEO_ID)

Run bundled script to fetch transcript:

SKILL_DIR="$HOME/.claude/skills/obsidian-vault-manager"
TRANSCRIPT=$("$SKILL_DIR/scripts/core/fetch-youtube-transcript.sh" "$VIDEO_ID")

Use mcp__fetch__fetch to get YouTube page for metadata (title, channel, description)

Step 2: Analyze Content for Smart Tags Determine:

Main topics (choose 2-4 from taxonomy)
Complexity level:
- quick-read = under 10 minutes
- tutorial = step-by-step instructional
- deep-dive = 30+ minutes, complex
Content characteristics:
- technical = code-heavy, engineering
- conceptual = theory, frameworks
- actionable = practical steps
- inspiration = motivational
Priority (high/medium/low based on relevance)

Step 3: Generate Filename Format: [date]-[creator-or-channel]-[descriptive-title].md Example: 2025-10-24-ai-labs-context-engineering-claude-code.md

Step 4: Load Template and Substitute Variables

Load bundled template:

TEMPLATE=$(cat "$SKILL_DIR/templates/youtube-note-template.md")

Substitute placeholders with analyzed data:
- {{TITLE}} - Video title from metadata
- {{VIDEO_ID}} - Extracted video ID
- {{CHANNEL}} - Channel name
- {{DATE}} - Current date (YYYY-MM-DD)
- {{TOPIC_TAGS}} - 2-4 topic tags from taxonomy
- {{METADATA_TAGS}} - 1-2 metadata tags (tutorial, actionable, etc.)
- {{PRIORITY}} - high/medium/low
- {{DURATION}} - Estimated duration (~X minutes)
- {{DESCRIPTION}} - 2-3 sentence summary from transcript analysis
- {{LEARNING_OBJECTIVES}} - Bullet list of learning outcomes
- {{CURRICULUM}} - Structured outline with checkboxes
- {{MAIN_INSIGHTS}} - 3-5 key insights from transcript
- {{ACTIONABLE_POINTS}} - Practical takeaways
- {{TARGET_AUDIENCE}} - Who should watch this
- {{TOPIC_ANALYSIS}} - Explanation of chosen topics
- {{COMPLEXITY_LEVEL}} - quick-read/tutorial/deep-dive
- {{PRIORITY_REASONING}} - Why this priority
- {{TAG_REASONING}} - Tag selection explanation
- {{PRIMARY_TOPIC}} - Main topic for filtering
- {{RELATED_SEARCHES}} - Suggested semantic searches
- {{CONNECTIONS}} - Links to related notes

Step 5: Create Enhanced Video Entry

Use mcp__obsidian-mcp-tools__create_vault_file with the substituted template content.

Tag Count: 6-8 tags total Always include: video, inbox, 2-4 topic tags, 1-2 metadata tags, optional content-specific tags

Ideas & Quick Thoughts

Bundled Resources:

Template: templates/idea-template.md - Idea note structure

When user provides plain text (no URL):

Step 1: Analyze the Idea Extract:

Main concept (for title)
Related topics (choose 2-4 from taxonomy)
Idea type:
- actionable = has concrete next steps
- conceptual = theoretical, framework-based
- inspiration = creative, motivational
- high-priority = urgent or important
Brief description (1-2 sentences explaining the idea clearly)

Step 2: Generate Smart Filename Format: {date}-{3-5-word-idea-name}.md

Examples:

"Use AI to automatically categorize notes" → 2025-10-23-ai-note-categorization.md
"Knowledge compounds when connected" → 2025-10-23-knowledge-compound-connections.md

Step 3: Load Template and Substitute Variables

Load bundled template:

SKILL_DIR="$HOME/.claude/skills/obsidian-vault-manager"
TEMPLATE=$(cat "$SKILL_DIR/templates/idea-template.md")

Substitute placeholders with analyzed data:
- {{TITLE}} - Concise idea title
- {{TOPIC_TAGS}} - 2-4 topic tags from taxonomy (comma-separated)
- {{METADATA_TAGS}} - 1-2 metadata tags (actionable, conceptual, inspiration, etc.)
- {{DATE}} - Current date (YYYY-MM-DD)
- {{PRIORITY}} - high/medium/low
- {{CORE_IDEA}} - Cleaned idea description (1-2 paragraphs)
- {{WHY_MATTERS}} - 1-2 sentences on potential impact or value
- {{RELATED_CONCEPTS}} - Bullet list of related concepts
- {{NEXT_STEPS}} - If actionable: 2-3 next steps. Otherwise: "Further research needed"
- {{TOPICS_EXPLANATION}} - Explanation of why these topics were chosen
- {{CHARACTERISTICS_EXPLANATION}} - Why it's actionable/conceptual/inspiration
- {{PRIORITY_EXPLANATION}} - Reasoning for priority level
- {{TAG_REASONING}} - Overall tag selection explanation
- {{PRIMARY_TOPIC}} - Main topic for filtering
- {{SECONDARY_TOPIC}} - Secondary topic for filtering
- {{RELATED_CONCEPT}} - For semantic search suggestions

Step 4: Create Enhanced Idea File

Use mcp__obsidian-mcp-tools__create_vault_file with the substituted template content.

Tag Count: 5-8 tags total Always include: idea, inbox, 2-4 topic tags, 1-2 metadata tags

GitHub Repositories

When user provides a GitHub URL:

Step 1: Analyze Repository Use mcp__gitingest__gitingest-analyze with:

source: GitHub URL
include_patterns: ["*.md", "*.py", "*.js", "*.ts"] (adapt to repo language)
max_file_size: 10485760 (10MB)

Step 2: Create Repository Analysis Note

Use mcp__obsidian-mcp-tools__create_vault_file:

---
title: "[Repo Name] - Repository Analysis"
tags: [repository, {language}, {topic}, inbox, technical, reference]
url: [github_url]
date: YYYY-MM-DD
type: repository
status: inbox
priority: medium
---

## 📦 Repository Overview
[Repository description from README]

## 🏗️ Architecture
[Key components and structure from gitingest analysis]

## 📁 Key Files & Components
[Important files identified in analysis]

## 📝 Documentation Summary
[Main docs and README content]

## 💡 Key Patterns & Insights
[Notable patterns, technologies, approaches]

## 🏷️ Tags Analysis
- **Topics:** {why these topics}
- **Language:** {primary programming language}
- **Bases Filtering:** `type = repository AND tags contains "{topic}"`

---
*Captured: {date}*
*Source: {repo_url}*

Tag Count: 6-8 tags

Web Articles

When user provides web article URL:

Step 1: Fetch Content Use mcp__fetch__fetch to get article content

Step 2: Create Article Note

Use mcp__obsidian-mcp-tools__create_vault_file:

---
title: "[Article Title]"
tags: [article, {topic1}, {topic2}, {topic3}, inbox, quick-read]
url: [article_url]
date: YYYY-MM-DD
type: article
status: inbox
priority: medium
---

## 📄 Summary
[AI-generated summary of key points]

## 🔑 Key Takeaways
- [Point 1]
- [Point 2]
- [Point 3]

## 💭 Personal Notes
[Space for user's thoughts]

## 🔗 Related Resources
[Links mentioned in article]

## 🏷️ Tags Analysis
- **Topics:** {explanation}
- **Bases Filtering:** `type = article AND tags contains "{topic}"`

---
*Captured: {date}*

Tag Count: 6-8 tags

2. Create Study Guides

Bundled Resources:

Template: templates/study-guide-template.md - Study guide structure

When user requests study guide from URL or content:

Step 1: Fetch Content

If URL: use mcp__fetch__fetch
If file: use mcp__obsidian-mcp-tools__get_vault_file
If direct text: use provided content

Step 2: Analyze for Smart Tagging Identify:

Main topics and themes → Choose 2-4 topic tags from taxonomy
Complexity level → deep-dive (multi-hour), technical (code/math), conceptual (theory)
Practical application → actionable (exercises) or tutorial (step-by-step)
Learning prerequisites → Determines difficulty level
Estimated study time → Hours required
Priority (high/medium/low based on goals)

Step 3: Generate Filename Format: [date]-[topic-name]-study-guide.md

Examples:

Machine learning basics → 2025-10-28-machine-learning-study-guide.md
React advanced patterns → 2025-10-28-react-advanced-study-guide.md

Step 4: Load Template and Substitute Variables

Load bundled template:

SKILL_DIR="$HOME/.claude/skills/obsidian-vault-manager"
TEMPLATE=$(cat "$SKILL_DIR/templates/study-guide-template.md")

Substitute placeholders with analyzed data:
- {{TITLE}} - Study subject/topic name
- {{TOPIC_TAGS}} - 2-4 topic tags from taxonomy (comma-separated)
- {{METADATA_TAGS}} - 1-2 metadata tags (deep-dive, technical, tutorial, etc.)
- {{SOURCE}} - Source URL or file reference
- {{DATE}} - Current date (YYYY-MM-DD)
- {{DIFFICULTY}} - beginner/intermediate/advanced
- {{ESTIMATED_TIME}} - Study time (e.g., "40 hours", "2 weeks")
- {{PRIORITY}} - high/medium/low
- {{LEARNING_OBJECTIVES}} - Bulleted checklist of objectives
- {{PREREQUISITES}} - Required background knowledge
- {{STUDY_METHOD}} - Recommended approach (active reading, practice-based, mixed)
- {{CONTENT_STRUCTURE}} - Weekly breakdown with concepts/activities/assessments
- {{MATERIAL_STRATEGIES}} - Content-specific study strategies
- {{PRACTICE_EXERCISES}} - Practical exercises or projects
- {{TEACHING_TECHNIQUES}} - How to teach/explain concepts
- {{WEEK1_ASSESSMENT}} - Early knowledge check questions
- {{FINAL_ASSESSMENT}} - Comprehensive assessment questions
- {{PROGRESS_STATUS}} - Weekly completion tracking checklist
- {{NEXT_MILESTONE}} - Specific next goal
- {{RELATED_NOTES}} - Wiki-style links to related content
- {{TOPICS_EXPLANATION}} - Why these topics were chosen
- {{DIFFICULTY_EXPLANATION}} - Difficulty level reasoning
- {{CHARACTERISTICS_EXPLANATION}} - Content characteristics (technical, deep-dive, etc.)
- {{PRIORITY_EXPLANATION}} - Priority reasoning
- {{TAG_REASONING}} - Overall tag selection explanation
- {{PRIMARY_TOPIC}} - Main topic for filtering
- {{SECONDARY_TOPIC}} - Secondary topic for filtering
- {{RELATED_CONCEPT}} - For semantic searches
- {{FOUNDATIONAL_TOPIC}} - Base knowledge topic
- {{NEXT_ACTION}} - Specific next step in study plan

Step 5: Create Enhanced Study Guide

Use mcp__obsidian-mcp-tools__create_vault_file with the substituted template content.

Tag Count: 6-8 tags total Status: Always use processing for study guides (not inbox) Always include: study-guide, processing, 2-4 topic tags, 1-2 metadata tags

3. Search Vault (Semantic Search)

When user asks to search vault:

Use Local REST API Method:

Since Smart Connections is configured, use mcp__obsidian-mcp-tools__search_vault_smart with the query:

mcp__obsidian-mcp-tools__search_vault_smart({
  query: "[user's search query]",
  filter: {
    limit: 5
  }
})

Present results showing:

Note titles
Relevant excerpts
Tags and metadata
Connections to other notes

Example queries:

"Search for notes about productivity and AI"
"Find everything related to learning workflows"
"Show me all high-priority technical content"

4. Bulk Tag Existing Notes

When user asks to tag untagged notes:

Step 1: Discover Files Use mcp__obsidian-mcp-tools__list_vault_files to find markdown files

Step 2: Process Each File For each file:

Use mcp__obsidian-mcp-tools__get_vault_file to read content
Analyze existing frontmatter:
- Check if tags: field exists
- Check if tags are comprehensive (5+ taxonomy tags)
Skip if already well-tagged (has 5+ taxonomy-compliant tags)
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
Generate enhanced tag array (5-8 tags total)
Use mcp__obsidian-mcp-tools__patch_vault_file to update frontmatter:

mcp__obsidian-mcp-tools__patch_vault_file({
  filename: "[note-name].md",
  targetType: "frontmatter",
  target: "tags",
  operation: "replace",
  contentType: "application/json",
  content: "[{content-type}, {topic1}, {topic2}, {status}, {metadata}]"
})

Important Rules:

Preserve existing data - merge AI tags with existing tags
Be conservative - if uncertain, default to reference
Handle errors gracefully - skip invalid files
Respect user intent - enhance rather than replace

Step 3: Report Progress After every 5-10 files:

✅ 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: Final Summary

# 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

### By Topic
- AI: 23 notes
- productivity: 18 notes
- knowledge-management: 15 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 tags contains "AI" AND status = inbox`
2. **Quick Wins**: `tags contains "quick-read" AND tags contains "high-priority"`
3. **Technical Deep Dives**: `tags contains "technical" AND tags contains "deep-dive"`
4. **Actionable Items**: `tags contains "actionable" AND status != archived`

5. Publish to GitHub Pages

Bundled Resources:

Script: scripts/core/publish.sh - Complete publish workflow

When user asks to publish a note:

Step 1: Validate Input

Add .md extension if not provided and verify file exists in vault.

Step 2: Run Bundled Publish Script

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

What the script does:

Finds all image references in the note (supports jpg, jpeg, png, gif, svg, webp)
Copies images from Claudecode vault to sharehub repository (preserves directory structure)
Converts relative image paths to absolute GitHub Pages URLs:
- ./images/file.jpg → /sharehub/images/file.jpg
- images/file.jpg → /sharehub/images/file.jpg
Copies the note with converted paths to sharehub/documents/
Creates git commit with proper message format
Pushes to GitHub (triggers GitHub Pages deployment)

Step 3: Wait for Deployment

# Wait for GitHub Actions to start
sleep 3

# Show recent workflow runs
gh run list --limit 3 --repo ZorroCheng-MC/sharehub 2>/dev/null || echo "Install GitHub CLI with: brew install gh"

echo ""
echo "⏳ Waiting 60 seconds for GitHub Pages to deploy..."
sleep 60

Step 4: Verify Published Page

Use mcp__fetch__fetch to verify the page is live:

url: https://zorrocheng-mc.github.io/sharehub/documents/${NOTE_FILE%.md}.html
max_length: 2000

Check the fetched content for:

Page title matches the note title
Main heading is present
No 404 or error messages
Images are referenced correctly

Publishing Paths:

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

Notes:

This workflow requires filesystem access (works in Claude Code CLI)
For Claude Desktop: Consider using MCP GitHub tools as alternative
Script handles all image copying and path conversion automatically
Git commit includes Claude Code attribution

MCP Tools Reference

Primary Tools

mcp__obsidian-mcp-tools__create_vault_file - Create new notes
mcp__obsidian-mcp-tools__get_vault_file - Read note content
mcp__obsidian-mcp-tools__patch_vault_file - Update frontmatter/sections
mcp__obsidian-mcp-tools__search_vault_smart - Semantic search
mcp__obsidian-mcp-tools__list_vault_files - List files
mcp__fetch__fetch - Get web content
mcp__gitingest__gitingest-analyze - Analyze repositories
mcp__github__create_or_update_file - Publish to GitHub
mcp__git__git_status - Check git status

Response Format

When completing operations:

Confirm action: "✅ Created video note: [title]"
Show frontmatter: Display YAML tags and metadata
Provide path: Show filename and location
For publishing: Include GitHub Pages URL
Be concise: Action-oriented responses

Quality Standards

Consistent tagging: Use ONLY the defined taxonomy
Correct tag counts: 5-8 for ideas, 6-8 for videos/study-guides
Complete frontmatter: All required YAML fields
Clean formatting: Proper markdown structure
Meaningful titles: Descriptive, searchable
Actionable content: Include next steps where relevant
Smart defaults: Medium priority, inbox status for new captures (except study-guides use processing)
Date stamps: Always include capture date (YYYY-MM-DD)
Filename rules: Follow format for each content type

Integration with Bases

These tags enable powerful Bases filtering queries like:

"Show all inbox items with high-priority"
"Show video content about AI and productivity"
"Show actionable items in processing status"
"Show technical tutorial content for learning"

Always create tags with filtering in mind.

obsidian-vault-manager

Install Skill

SKILL.md

Obsidian Vault Manager

Vault Configuration

Tag Taxonomy (STRICT - Use Only These)

Content Type Tags (choose 1)

Topic Tags (choose 2-4 relevant)

Status Tags (choose 1)

Priority/Metadata Tags (choose 0-2)

Core Operations

1. Capture Content (Universal Inbox)

YouTube Videos

Ideas & Quick Thoughts

GitHub Repositories

Web Articles

2. Create Study Guides

3. Search Vault (Semantic Search)

4. Bulk Tag Existing Notes

5. Publish to GitHub Pages

MCP Tools Reference

Primary Tools

Response Format

Quality Standards

Integration with Bases