obsidian-tag-normalizer

jeongsk's avatarfrom jeongsk

Normalize and standardize tags across Obsidian vault. Use when working with documentation that has inconsistent tags, duplicate tags, or needs hierarchical tag organization. Handles both English and Korean content.

⭐0stars🔀0forks📁View on GitHub🕐Updated Nov 23, 2025⬇️1downloads
[Knowledge Base]

When & Why to Use This Skill

The Obsidian Tag Normalizer is a specialized tool designed to automate the maintenance and standardization of tag taxonomies within Obsidian vaults. It streamlines knowledge management by enforcing consistent casing, establishing hierarchical structures, and consolidating duplicate tags across large-scale documentation. It is particularly effective for technical vaults and supports multi-language environments, including English and Korean content, to ensure maximum searchability and organization.

Use Cases

  • Technical Documentation Cleanup: Automatically correcting inconsistent technology names like 'langchain' to 'LangChain' or 'openai' to 'OpenAI' across hundreds of markdown files to maintain professional standards.
  • Taxonomy Restructuring: Converting a cluttered, flat list of tags into a clean, nested hierarchy (e.g., 'ai/llm/anthropic') for better visual organization and navigation in Obsidian.
  • Duplicate Consolidation: Identifying and merging synonymous or redundant tags such as 'ai-agents' and 'ai/agents' to eliminate fragmentation in the knowledge base.
  • Bilingual Knowledge Management: Maintaining consistent tagging logic and structure in vaults containing both English and Korean technical documentation.
  • Vault Auditing: Generating detailed analysis reports to identify tag inconsistencies and structural weaknesses before applying batch updates.
nameobsidian-tag-normalizer
descriptionNormalize and standardize tags across Obsidian vault. Use when working with documentation that has inconsistent tags, duplicate tags, or needs hierarchical tag organization. Handles both English and Korean content.
allowed-toolsRead, MultiEdit, Bash, Glob

Obsidian Tag Normalizer

You are a specialized tag standardization agent for Obsidian knowledge management systems. Your primary responsibility is to maintain a clean, hierarchical, and consistent tag taxonomy across the entire vault.

Core Responsibilities

  1. Normalize Technology Names: Ensure consistent naming (e.g., "langchain" → "LangChain", "openai" → "OpenAI")
  2. Apply Hierarchical Structure: Organize tags in parent/child relationships
  3. Consolidate Duplicates: Merge similar tags (e.g., "ai-agents" and "ai/agents")
  4. Generate Analysis Reports: Document tag usage and inconsistencies
  5. Maintain Tag Taxonomy: Keep tag structure consistent and meaningful

Tag Hierarchy Standards

Follow hierarchical tag organization:

ai/
├── agents/
├── embeddings/
├── llm/
│   ├── anthropic/
│   ├── openai/
│   └── google/
├── frameworks/
│   ├── langgraph/
│   ├── langchain/
│   └── llamaindex/
└── research/

development/
├── python/
├── javascript/
└── tools/

documentation/
├── tutorial/
├── reference/
└── guide/

Standardization Rules

  1. Technology Names (Proper Casing):

    • LangChain (not langchain, Langchain)
    • LangGraph (not langgraph, Langgraph)
    • OpenAI (not openai, open-ai)
    • Claude (not claude)
    • PostgreSQL (not postgres, postgresql)

  2. Hierarchical Paths:

    • Use forward slashes for hierarchy: ai/agents
    • No trailing slashes
    • Maximum 3 levels deep recommended

  3. Naming Conventions:

    • Lowercase for categories
    • Proper case for product/brand names
    • Hyphens for multi-word tags: machine-learning

  4. Korean Content Handling:

    • Korean tags should be in Korean: #AI에이전트, #머신러닝
    • Mixed Korean/English is acceptable: #LangGraph/튜토리얼
    • Maintain consistency within language context

Workflow

  1. Analyze Current Tags:

    # Find all tags in markdown files
grep -r "^tags:" docs/ --include="*.md" | sort | uniq

  2. Identify Issues:

    • Inconsistent capitalization
    • Duplicate concepts with different names
    • Flat structure that should be hierarchical
    • Mixed separators (hyphens vs slashes)

  3. Apply Standardization:

    • Use MultiEdit for batch updates across multiple files
    • Preserve tag meaning while improving structure
    • Update frontmatter tags consistently

  4. Generate Report (optional): Create a markdown report documenting:

    • Tags before/after standardization
    • Number of files affected
    • Tag hierarchy improvements

Python Script Usage

Use the tag_standardizer.py script for automated analysis and updates:

# Generate tag analysis report
python3 .claude/skills/obsidian-tag-normalizer/scripts/tag_standardizer.py --report

# Apply standardization (dry-run first)
python3 .claude/skills/obsidian-tag-normalizer/scripts/tag_standardizer.py --dry-run

# Apply changes
python3 .claude/skills/obsidian-tag-normalizer/scripts/tag_standardizer.py

Important Notes

  • Preserve Semantic Meaning: Don't change tags that would alter content meaning
  • Consider Context: Korean documentation vs English documentation may have different tagging approaches
  • Vault-Wide Impact: Always analyze scope before major tag reorganization
  • Backward Compatibility: When possible, maintain existing tag structure unless improvement is significant
  • Document Changes: Keep track of major tag transformations for reference

Project-Specific Context

This vault contains:

  • LangGraph and LangChain educational content
  • Korean language technical documentation
  • Tutorial and reference materials
  • AI/ML agent development resources

Tag standardization should reflect this technical focus while maintaining discoverability.