playbooks

home / skills / zpankz / mcp-skillset / obsidian-batch

obsidian-batch skill

/obsidian-batch

This skill enables large-scale Obsidian vault automation, performing bulk tag normalization, wikilink fixes, frontmatter edits, and analytics-driven migrations.

npx playbooks add skill zpankz/mcp-skillset --skill obsidian-batch

Review the files below or copy the command above to add this skill to your agents.

Files (14)
SKILL.md
2.1 KB
---
name: obsidian-batch
description: "Batch processing for Obsidian vaults: bulk tag normalization, wikilink extraction/fixing, frontmatter edits, vault analysis, and migration workflows. Use when asked to analyze or modify many notes in an Obsidian vault at scale, or to script/automate vault-wide changes."
---

# Obsidian Batch Processing Skill

Use this skill to perform repeatable, vault-wide operations on Obsidian markdown files.
Keep this file lean and route to the correct reference or script instead of duplicating detail.

## Routing Map (read only what you need)

- `references/quickstart.md` - Setup plus a 5-minute tutorial. Use for first run or quick orientation.
- `references/cli-usage.md` - Full CLI reference. Use for exact flags, subcommands, and examples.
- `references/obsidian-syntax.md` - Obsidian markdown syntax, regex patterns, and edge cases. Use when parsing or transforming content.
- `references/processing-patterns.md` - Advanced workflows, migrations, QA, rollback strategies. Use for multi-step or high-risk operations.
- `examples/use-case-1-migrate-flat-to-hierarchical.md` - Large-scale migration example.
- `examples/use-case-2-fix-broken-links.md` - Broken link repair example.
- `examples/use-case-3-normalize-tags.md` - Tag normalization example.
- `examples/use-case-4-vault-statistics-report.md` - Analytics/reporting example.

## Script Index (entry points)

- `scripts/batch_processor.py` - Main CLI entry point and command routing.
- `scripts/wikilink_extractor.py` - Extract and analyze wikilinks.
- `scripts/tag_normalizer.py` - Normalize tags across a vault.
- `scripts/frontmatter_processor.py` - Bulk frontmatter operations.
- `scripts/vault_analyzer.py` - Vault statistics and health reports.

## Standard Workflow

1. Back up the vault.
2. Run a dry run when available.
3. Execute the operation.
4. Verify results with a report or spot checks.

## How to Use This Skill

- Pick the smallest reference file that answers the question.
- Summarize only what is needed, then point to the exact script or command.
- If the user asks for edits or new behavior, modify the relevant script and keep the CLI consistent with `references/cli-usage.md`.

Overview

This skill provides batch processing tools for Obsidian vaults to automate vault-wide edits, analysis, and migrations. It bundles targeted scripts for tag normalization, wikilink extraction/fixing, frontmatter edits, and vault health reporting to run repeatable operations at scale. Use it to safely apply consistent transformations across many markdown notes.

How this skill works

The skill exposes small, focused scripts that operate on the vault filesystem and parse Obsidian markdown patterns. Typical flow: back up the vault, run a dry-run mode to preview changes, execute the chosen script, and produce a report for verification. Scripts include a CLI entry point and specialized modules for tags, links, frontmatter, and analytics.

When to use it

  • Normalize tag formats or consolidate tag variants across thousands of notes.
  • Find, repair, or canonicalize broken or inconsistent wikilinks.
  • Apply bulk frontmatter additions, removals, or schema migrations.
  • Generate vault statistics and health reports before or after a migration.
  • Perform large-scale migrations (flat → hierarchical) or restructure note organization.

Best practices

  • Always create a full vault backup before running destructive operations.
  • Start with a dry run to preview changes and check the generated report.
  • Work on a smaller subset of files first to validate rules and regexes.
  • Use the provided reports and spot checks to validate correctness after execution.
  • Follow the routing map: consult the smallest reference that answers your question (quickstart, CLI usage, syntax, or processing patterns).

Example use cases

  • Normalize all tags to lowercase and replace deprecated tag variants with canonical tags across the vault.
  • Extract all wikilinks to identify broken targets, then run a fix pass to repair or alias links.
  • Add a standardized frontmatter block to notes missing key metadata fields before exporting.
  • Run a vault analyzer to produce a report of orphan notes, backlink density, and file-size distribution.
  • Migrate a flat note structure into a hierarchical folder layout using the migration example as a template.

FAQ

Which script should I run to analyze links?

Use the wikilink_extractor.py script to gather and analyze wikilinks; follow with the broken-links example for repair workflows.

How do I ensure I can undo changes?

Create a full vault backup before running operations and use dry-run mode to preview edits. The processing patterns reference covers QA and rollback strategies.