richfrem/agent-plugins-skills / plugins/agent-memory/.apm/skills/managing-obsidian-vaults
managing-obsidian-vaults
VerifiedInteractive vault, wiki and Super-RAG setup in the main conversation. Use for "set up my wiki", "initialize the full knowledge stack" or combined RLM/vector/wiki setup. Manage Obsidian vaults and LLM wikis: initialize vaults, author Markdown and wikilinks, safely edit notes and Bases, create Canvas diagrams, traverse graphs, build concept wikis, distill summary/bullets/deep layers, query and lint knowledge.
scripts/init_vault.py
View on GitHub"""
init_vault.py (CLI)
=====================================
Purpose:
Bootstrap any project directory as an Obsidian Vault.
Creates .obsidian/app.json with sensible exclusion filters for developer repos.
Layer: Core Operations
Usage Examples:
pythoninit_vault.py --vault-root /path/to/vault
pythoninit_vault.py --vault-root /path/to/vault --validate-only
Supported Object Types:
- .obsidian/app.json
CLI Arguments:
--vault-root: Root directory for the vault.
--exclude: Additional exclusion patterns.
--validate-only: Check without making changes.
Input Files:
- Project directories containing .md files.
Output:
- JSON results indicating initialization status.
Key Functions:
init_vault(): Initialize an Obsidian Vault.
count_markdown_files(): Count .md files in the vault.
Script Dependencies:
os, sys, json, argparse, pathlib
Consumed by:
- obsidian-init skill
"""
import os
import sys
import json
import argparse
from pathlib import Path
from typing import Optional, List, Dict, Any
DEFAULT_EXCLUSIONS = [
"node_modules/",
".worktrees/",
".vector_data/",
".git/",
"venv/",
"__pycache__/",
"*.json",
"*.jsonl",
"learning_package_snapshot.md",
"bootstrap_packet.md",
"learning_debrief.md",
"*_packet.md",
"*_digest.md",
"dataset_package/",
"rlm_summary_cache*",
"rlm_tool_cache*"
]
def count_markdown_files(vault_root: Path) -> int:
"""Count .md files in the vault (non-recursive top-level scan for speed)."""
count = 0
for root, dirs, files in os.walk(vault_root):
# Skip .git and other hidden dirs
dirs[:] = [d for d in dirs if not d.startswith('.')]
for f in files:
if f.endswith('.md'):
count += 1
return count
def _write_app_json(app_json: Path, exclusions: List[str]) -> None:
"""Merge exclusions into app.json's userIgnoreFilters and write it (preserving other keys)."""
app_config: Dict[str, Any] = {}
if app_json.exists():
try:
app_config = json.loads(app_json.read_text())
except json.JSONDecodeError:
pass
app_config["userIgnoreFilters"] = exclusions
app_json.write_text(json.dumps(app_config, indent=2) + "\n")
def _ensure_gitignore_excludes_obsidian(vault_root: Path) -> Optional[str]:
"""Append or create .gitignore's .obsidian/ exclusion. Returns 'updated', 'created', or None."""
gitignore = vault_root / ".gitignore"
if gitignore.exists():
content = gitignore.read_text()
if ".obsidian/" not in content:
with open(gitignore, 'a') as f:
f.write("\n# Obsidian local config (user-specific)\n.obsidian/\n")
return "updated"
return None
gitignore.write_text("# Obsidian local config (user-specific)\n.obsidian/\n")
return "created"
def _finalize_init_result(result: Dict[str, Any], vault_root: Path, exclusions: List[str]) -> Dict[str, Any]:
"""Populate the final 'initialized' status fields (status, exclusions_applied, next_steps, env_hint)."""
result["status"] = "initialized"
result["exclusions_applied"] = len(exclusions)
result["next_steps"] = [
"Open the Obsidian desktop app",
f"Click 'Open Folder as Vault' and select: {vault_root}",
"All non-excluded .md files will be indexed automatically"
]
if not os.environ.get("VAULT_PATH"):
result["env_hint"] = f"Consider setting: export VAULT_PATH={vault_root}"
return result
def init_vault(vault_root: Path, extra_exclusions: Optional[List[str]] = None, validate_only: bool = False) -> Dict[str, Any]:
"""Initialize an Obsidian Vault at the given root."""
vault_root = vault_root.resolve()
if not vault_root.exists():
return {"error": f"Directory does not exist: {vault_root}"}
if not vault_root.is_dir():
return {"error": f"Not a directory: {vault_root}"}
# Count markdown files
md_count = count_markdown_files(vault_root)
if md_count == 0:
return {"error": f"No .md files found in {vault_root}. Is this the right directory?"}
obsidian_dir = vault_root / ".obsidian"
app_json = obsidian_dir / "app.json"
result = {
"vault_root": str(vault_root),
"markdown_files_found": md_count,
"obsidian_dir_exists": obsidian_dir.exists(),
"app_json_exists": app_json.exists(),
}
if validate_only:
result["mode"] = "validate_only"
if obsidian_dir.exists():
result["status"] = "vault_already_initialized"
else:
result["status"] = "ready_to_initialize"
return result
# Build exclusion list
exclusions = list(DEFAULT_EXCLUSIONS)
if extra_exclusions:
exclusions.extend(extra_exclusions)
# Create .obsidian directory
obsidian_dir.mkdir(exist_ok=True)
_write_app_json(app_json, exclusions)
gitignore_status = _ensure_gitignore_excludes_obsidian(vault_root)
if gitignore_status:
result[f"gitignore_{gitignore_status}"] = True
return _finalize_init_result(result, vault_root, exclusions)
def main() -> None:
"""Parse CLI args, run init_vault, print the JSON result, and exit(1) on error."""
parser = argparse.ArgumentParser(description="Initialize an Obsidian Vault")
parser.add_argument('--vault-root', required=True, help='Root directory for the vault')
parser.add_argument('--exclude', nargs='*', help='Additional exclusion patterns')
parser.add_argument('--validate-only', action='store_true', help='Check without making changes')
args = parser.parse_args()
result = init_vault(Path(args.vault_root), args.exclude, args.validate_only)
print(json.dumps(result, indent=2))
if "error" in result:
sys.exit(1)
if __name__ == '__main__':
main()
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |