---

name: obsidian-file-manager description: > This skill should be used when managing documentation files in an Obsidian vault, including creating session artifacts, moving planning documents from project directories to the vault, updating document lifecycle states (active → processed → archived), searching for documents by tags or content, and automating archival of old documents. Integrates with task-startup/task-wrapup workflows for any coding project.

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

Copy# 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

Copy~/.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

Copy~/.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

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

search - Find documents

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

archive - Auto-archive old documents

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

Project Partitioning

Files are organized by type first, then by project:

Copy{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