Obsidian File Manager

Obsidian File Manager Skill

Automated file management for Obsidian vault integration via the Local REST API.

Triggers

This skill should be used when:

• Creating session artifacts or documentation in the vault
• Moving planning documents from project directories to vault
• Updating document lifecycle states (active → processed → archived)
• Searching for documents by tags, project, or content
• Automating archival of old documents based on retention policies
• Managing documentation during task-startup/task-wrapup workflows

Quick Start

Prerequisites

1. Obsidian with Local REST API plugin installed and enabled
2. Ruby 2.7+ installed
3. API key configured in config/.env

Setup

# Configure API key (get from Obsidian → Settings → Local REST API)
echo "OBSIDIAN_API_KEY=your-key" > ~/.claude/skills/obsidian-file-manager/config/.env
chmod 600 ~/.claude/skills/obsidian-file-manager/config/.env

Operations

create - Create new document

~/.claude/skills/obsidian-file-manager/scripts/create_in_vault.rb \
  --type session \
  --project myproject \
  --subject "feature implementation" \
  --content "# Session Notes\n\n..." \
  --lifecycle active

move - Move file to vault

~/.claude/skills/obsidian-file-manager/scripts/move_to_vault.rb \
  --source /path/to/project/docs/plan.md \
  --type plan \
  --project myproject

update-lifecycle - Change document state

~/.claude/skills/obsidian-file-manager/scripts/update_lifecycle.rb \
  --path sessions/myproject/session_myproject_20251124.md \
  --lifecycle processed

search - Find documents

~/.claude/skills/obsidian-file-manager/scripts/search_vault.rb \
  --query "project:myproject lifecycle:active type:session"

archive - Auto-archive old documents

~/.claude/skills/obsidian-file-manager/scripts/auto_archive.rb --dry-run

Project Partitioning

Files are organized by type first, then by project:

{type}/{project}/filename.md

This enables multi-project support within a single vault. For example:

• planning/softtrak/plan_softtrak_auth_system.md
• planning/myotherproject/plan_myotherproject_api_design.md

Document Types

Lifecycle States

Error Codes

Resources

For detailed documentation, see references/:

• references/operations.md - Full parameter documentation
• references/configuration.md - Config file reference
• references/integration.md - Workflow integration patterns
• references/troubleshooting.md - Common issues and solutions

Scripts

All scripts are in scripts/:

• create_in_vault.rb - Create new documents
• move_to_vault.rb - Move files to vault
• update_lifecycle.rb - Change lifecycle state
• search_vault.rb - Search vault
• auto_archive.rb - Automatic archival

Core libraries in scripts/lib/:

• obsidian_client.rb - REST API wrapper
• file_namer.rb - Naming conventions
• tag_manager.rb - Tag/frontmatter utilities