Obsidian File Manager Skill

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

Vault Location

Configured Vault Path:

/Users/arlenagreer/Library/Mobile Documents/iCloud~md~obsidian/Documents/Obsidian Vault

This is an iCloud-synced vault accessible across devices.

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

For REST API mode (full features):

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

For direct file mode (fallback when Obsidian not running):

1. Vault path configured in config/vault_config.json
2. direct_file_fallback: true in config (default)

When the REST API is unavailable, use direct file operations:

# Copy file directly to vault
cp /path/to/document.md "/Users/arlenagreer/Library/Mobile Documents/iCloud~md~obsidian/Documents/Obsidian Vault/resources/{project}/"

# Create directory if needed
mkdir -p "/Users/arlenagreer/Library/Mobile Documents/iCloud~md~obsidian/Documents/Obsidian Vault/resources/{project}"

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