Tag Agent Partner

Taxonomy enforcement agent that normalizes, deduplicates, and hierarchically structures tags across an entire Obsidian vault.

When to Use This Agent

Choose this agent when you need to:

• Standardize inconsistent technology name casing across vault tags (e.g., "langchain" to "LangChain")
• Merge duplicate tags that represent the same concept with different syntax
• Enforce a hierarchical tag taxonomy with parent-child relationships
• Generate a tag usage analysis report showing frequency, orphans, and violations

Consider alternatives when:

• You need to validate frontmatter metadata fields beyond tags (use Guide Metadata Navigator)
• Your goal is content deduplication rather than tag normalization

Quick Start

Configuration

Copy
name: tag-agent-partner
type: agent
category: obsidian-ops-team

Example Invocation

Copy
claude agent:invoke tag-agent-partner "Standardize all tags and merge duplicates per taxonomy"

Example Output

=== Tag Standardization Report ===
Vault: ~/KnowledgeBase (1,107 notes, 342 unique tags)

CASING FIXES: 18 tags normalized
  - langchain → LangChain (in 47 notes)
  - openai → OpenAI (in 83 notes)
  - postgresql → PostgreSQL (in 12 notes)

DUPLICATE MERGES: 7 tag groups consolidated
  - ai-agents + ai/agents → ai/agents (91 notes updated)
  - dev-tools + development/tools → development/tools (34 notes)

HIERARCHY VIOLATIONS: 4 tags exceed 3-level depth
  - ai/frameworks/langchain/plugins/auth → ai/frameworks/langchain

ORPHANED TAGS: 11 tags used by only 1 note
TAXONOMY UPDATED: Tag_Taxonomy.md regenerated

Core Concepts

Tag Classification Tiers Overview

Aspect	Details
Category Tags	Top-level domain identifiers like ai/, business/, development/
Subcategory Tags	Second-level specializations like ai/agents, ai/llm
Product Tags	Proper-cased technology names like LangChain, PostgreSQL
Status Tags	Workflow markers like draft, active, archived

Tag Normalization Pipeline Architecture

┌─────────────┐     ┌─────────────┐
│  Tag         │────▶│  Casing     │
│  Extractor   │     │  Normalizer │
└─────────────┘     └─────────────┘
        │                   │
        ▼                   ▼
┌─────────────┐     ┌─────────────┐
│  Duplicate   │────▶│  Taxonomy   │
│  Merger      │     │  Enforcer   │
└─────────────┘     └─────────────┘

Configuration

Parameter	Type	Default	Description
taxonomy_path	string	"/System_Files/Tag_Taxonomy.md"	Path to the master tag taxonomy definition document
max_hierarchy_depth	integer	3	Maximum allowed nesting levels for hierarchical tags
case_map_path	string	"/System_Files/case_mappings.yml"	YAML file mapping lowercase tag variants to proper casing
merge_threshold	float	0.88	String similarity threshold for suggesting tag merges
dry_run	boolean	true	When true, generates report without modifying any files

Best Practices

1. Start With Dry Run Mode Always run the agent in dry_run mode first to review proposed changes. Tag normalization affects every note that uses the modified tags, so previewing changes prevents unintended bulk modifications.

2. Maintain a Case Mapping File Technology names have specific capitalization that cannot be inferred algorithmically (e.g., PostgreSQL, not Postgresql). Keep a curated case_mappings.yml file that authoritatively defines the correct casing for every product name in your domain.

3. Limit Hierarchy to Three Levels Deeply nested tags like ai/frameworks/langchain/plugins/auth become unwieldy to type and difficult to browse. Three levels provide sufficient granularity while keeping the taxonomy navigable and maintainable.

4. Consolidate Before Expanding Before introducing new tag categories, check whether existing tags already cover the concept under a different name. Running a merge analysis first prevents creating duplicates that will need consolidation later.

5. Version Your Taxonomy Document Keep the Tag_Taxonomy.md file under version control so that changes to the taxonomy are tracked over time. This provides an audit trail and makes it easy to revert problematic taxonomy decisions.

Common Issues

1. Merge incorrectly combines tags that look similar but mean different things Raise the merge_threshold from 0.88 to 0.95 if semantically distinct tags are being grouped. For example, "api-gateway" and "api-gateway-v2" might be flagged as duplicates when they represent different systems.

2. Proper casing not applied to tags inside inline text The agent normalizes tags in frontmatter YAML arrays and inline hashtags. If tags appear inside prose text without the # prefix, they are treated as regular words and not modified. Use frontmatter tags for consistent normalization.

3. New tags created by other agents bypass taxonomy validation When MOC or curation agents add tags programmatically, they may not consult the taxonomy. Configure those agents to use the same taxonomy_path so that all tag creation is validated against the approved hierarchy.