jaimeparker/obsidian-batch-yaml

Skill: Obsidian Batch YAML

Description

This skill automates the process of enhancing your Obsidian "Cyber Brain" by adding structured, AI-suitable YAML frontmatter to existing Markdown notes. It is designed to run autonomously across your most active research and project folders.

Trigger: Use when the user wants to "standardize", "process", or "add metadata/tags/summaries" to existing notes in the 00, 10, 20, or 30 directories.

Input: Obsidian vault directories 00, 10, 20, and 30. Output: Updated Markdown notes with merged YAML frontmatter including tags, summary, and aliases.

---

Workflow

Follow this iterative, batch-based process to execute the skill.

1. Discovery

1. User Declaration (Optional): Check if the user has explicitly provided a list of notes to process. This can be:
   • A list of note file paths (relative to the Obsidian vault root)
   • A list of note names
   • An example: ["00 Inbox/Research Notes.md", "10 Projects/AI Systems.md", "20 Areas/Machine Learning.md"]
2. Automatic Discovery: If no explicit list is provided, identify all Markdown (.md) files within the target directories:
   • 00 Inbox/
   • 10 Projects/
   • 20 Areas/
   • 30 Zettelkasten/
3. Filter & Batch: Exclude any files that are clearly non-content (e.g., templates, system logs). Organize the remaining files into batches of 5 notes to maintain efficiency.

2. Batch Processing Loop

For each batch of 5 notes, perform the following steps for every note:

A. Read Taxonomy & Analyze

1. Read Tag Taxonomy (MANDATORY): Before generating any tags, you MUST read the controlled tag vocabulary at 60 System/Tag Taxonomy.md. This file defines the approved tag categories:
   • L1 — Domain: reinforcement-learning, robotics, motion-planning, trajectory-optimization, optimal-control, control-systems
   • L2 — Methodology: offline-rl, offline-to-online, model-based-rl, world-models, imitation-learning, residual-rl, hierarchical-rl, diffusion-policy, real-world-rl, exploration, fine-tuning, reward-design, value-function, policy-gradient
   • L3 — Algorithm/Tool: sac, ppo, cql, cal-ql, iql, td-mpc, flow-matching, isaac-lab, px4, rlinf, maniskill
   • L4 — Project: aerial-grasping, aerial-manipulation, quadrotor-control, quadrotor-dynamics, ai-lab, fast-perching, agile-flight
   • L5 — Note Type: discussion, moc, paper-reading, design-doc, training-diagnostics, implementation-plan, sop, research-philosophy
2. Read Note: Use mcp_obsidian_read_note to load the full content, including any existing YAML.
3. Analyze Content: Analyze the body text to generate the following metadata:
   • summary: A concise, 1-2 sentence TL;DR of the core insight.
   • tags: 2-4 highly relevant conceptual tags. Priority rule: always select from the existing taxonomy (L1-L5) first. Only create a new tag if no existing tag captures the concept, and only if the concept applies to at least 2+ notes in the vault. All tags must be lowercase kebab-case (e.g., reinforcement-learning, NOT Reinforcement_Learning or RL). Never create tags from hex color codes, code keywords (e.g., include, define), or numeric values.
   • aliases: 1-3 alternative titles or keywords for easier cross-linking.

B. Intelligent Merge Logic

1. Parse Existing YAML: If the note has a frontmatter block (between --- delimiters), extract the existing fields.
2. Merge Data:
   • Tags: Combine existing tags with newly generated ones. Ensure no duplicates. Format as a YAML list.
   • Aliases: Combine existing aliases with newly generated ones. Ensure no duplicates.
   • Summary: Add the new summary field. If one already exists, replace it only if the existing one is empty or significantly less informative.
   • Preserve Others: Keep all other existing fields (e.g., date, type, source) exactly as they are.
3. Construct New YAML: Assemble the merged fields into a clean YAML block at the top of the file.

C. Tag Validation (Post-Generation Check)

Before writing, validate the generated tags:

1. Format Check: All tags must be lowercase with hyphens (kebab-case). Reject tags that contain underscores, uppercase letters, spaces, or special characters.
2. Noise Rejection: Reject tags that are:
   • Hex color codes (3, 6, or 8 character hex strings like 333, f9f, fff3a3a6)
   • Code keywords (include, file, define, config, common, index)
   • Pure numbers
   • Less than 2 characters
3. Singleton Warning: If a newly created tag is not in the taxonomy, flag it for review. It should only be added if it applies to at least 2 notes.
4. Deduplicate: Remove exact duplicates and case-variants (e.g., Offline-RL and offline-rl → keep offline-rl).

D. Write Update

1. Apply Update: Use mcp_obsidian_patch_note (if replacing only the top block) or mcp_obsidian_write_note to save the updated note.
2. Log Progress: Keep a brief internal log of which files have been updated in this turn.

3. Continuation & Finalization

1. Check for Next Batch: After completing a batch, automatically proceed to the next until all identified files are processed.
2. Final Report: Once the entire scope is complete, provide a summary to the user:
   • Total notes processed.
   • Folders covered.
   • A few examples of the generated metadata to confirm quality.

---

User Declaration Format

Users can explicitly declare which notes should be processed by providing:

Single Note: Single Folder:

"Process this folder: Research"
"Add YAML to: 10 Projects"
"Handle all notes in: 20 Areas/ML Systems"

Single Note:

"Process this note: My Research Note.md"
"Add YAML to: 10 Projects/AI Research.md"

Multiple Notes (List Format):

["00 Inbox/Note 1.md", "10 Projects/Note 2.md", "20 Areas/Note 3.md"]

Mixed Format (Folders and Notes):

["Research/Deep Learning", "10 Projects/AI Systems.md", "00 Inbox/Quick Notes.md"]

Declaration Rules:

• Folder paths: Relative to Obsidian vault root (e.g., "Research", "10 Projects/Subdir")
• Note paths: Must include .md extension (e.g., "10 Projects/Note.md")
• Path separators: Use forward slashes /
• The skill will automatically recursively scan folders for all .md files

Batch Processing: If a user provides more than 5 items (folders or notes), they will automatically be split into batches of 5 and processed iteratively.

---

Technical Constraints

• CRITICAL: NO CONTENT MODIFICATION: You MUST NOT under any circumstances modify, reformat, or delete the original body content of the note (everything below the second --- delimiter). This skill is strictly for YAML frontmatter enhancement.
• Tag Taxonomy Compliance: All generated tags must be validated against 60 System/Tag Taxonomy.md. Prefer existing taxonomy tags; new tags require justification and must follow kebab-case format.
• No Noise Tags: Never create tags from hex color codes (e.g., #fff3a3a6), code keywords (e.g., #include), or numeric values. These are parser artifacts, not semantic tags.
• Atomicity: Ensure the note content below the YAML block remains completely unchanged.
• Safety: If a note read fails or content is ambiguous, skip that note and move to the next to prevent stalling the loop.
• Formatting: Always use valid YAML syntax (e.g., spaces after colons, correct list formatting).