DavidROliverBA/ArchitectKB / .claude/skills/tag-management
tag-management
VerifiedTag Management Skill
Purpose: Analyze, refactor, and maintain tags across the vault according to the official taxonomy.
Taxonomy Reference: [[.claude/rules/tag-taxonomy.md]]
Commands
/tag-analyze [scope]
Analyze tag quality and compliance.
Scopes:
/tag-analyze- Current note (if applicable)/tag-analyze vault- Full vault analysis/tag-analyze <path>- Specific file or folder
Analysis Includes:
- Tag coverage (has tags vs no tags)
- Hierarchical compliance (proper prefixes)
- Case violations (uppercase, mixed case)
- Inline prefix violations (
#in frontmatter) - Template variable contamination
- Flat tag orphans (no hierarchy)
- Minimum tag requirements by note type
- Tag recommendations
Output:
- Summary of violations
- Specific issues found
- Suggested fixes
/tag-refactor [scope]
Refactor tags to follow official taxonomy.
Scopes:
/tag-refactor- Current note/tag-refactor vault- Full vault refactor/tag-refactor <path>- Specific file or folder/tag-refactor --dry-run- Preview changes without applying
Refactoring Rules:
-
Case Normalization
ADR→type/adrMROSystem→technology/mroPlatformAWS→technology/aws- All tags to lowercase
-
Inline Prefix Removal
#activity/architecture→activity/architecture#technology/aws→technology/aws
-
Flat to Hierarchical
mroSystem→technology/mroPlatformaws→technology/awsdataPlatform→project/dataPlatformarchitecture→activity/architectureintegration→domain/integrationoractivity/integration(context-dependent)
-
Template Variable Removal
- Delete:
{{3-5 relevant tags}},{{project|lower}}, etc.
- Delete:
-
Capitalized Prefixes
Project/ModernizationProject→project/modernizationTechnology/AWS→technology/aws
Safety:
- Always backup before vault-wide refactoring
- Preview changes with
--dry-runfirst - Commit changes to git before refactoring
/tag-suggest <note>
Suggest appropriate tags for a note based on content analysis.
Process:
- Read note frontmatter and content
- Analyze note type (
type:field) - Extract key terms and context
- Suggest tags from approved taxonomy
Example:
/tag-suggest "ADR - AIIncidentProcessor - Bedrock.md"
Output:
# Current tags:
tags: [ADR, activity/architecture, AWS, Bedrock]
# Suggested tags (normalized):
tags: [
type/adr,
activity/architecture,
technology/aws,
technology/bedrock,
project/aiProcessor,
domain/cloud,
domain/security
]
# Changes:
- Remove: ADR (flat) → Add: type/adr
- Normalize: AWS → technology/aws
- Normalize: Bedrock → technology/bedrock
- Add missing: project/aiProcessor, domain/cloud, domain/security
/tag-find-violations [type]
Find specific tag violations across the vault.
Types:
/tag-find-violations case- Case violations (uppercase, mixed case)/tag-find-violations inline- Inline#prefix in frontmatter/tag-find-violations flat- Orphan flat tags (no hierarchy)/tag-find-violations template- Template variable contamination/tag-find-violations missing- Notes missing required tags/tag-find-violations all- All violations (default)
Output:
- List of files with violations
- Specific violations per file
- Count summary
/tag-migrate <old> <new>
Batch rename a tag across the entire vault.
Examples:
/tag-migrate "ADR" "type/adr"
/tag-migrate "AWS" "technology/aws"
/tag-migrate "project/modernization" "project/modernization-legacy"
Process:
- Find all notes with
<old>tag - Replace with
<new>tag - Update frontmatter YAML
- Report changes made
Safety:
- Shows preview before applying
- Requires confirmation for vault-wide changes
Implementation Guide
Tag Refactoring Process
When implementing /tag-refactor:
-
Read note frontmatter
import re, yaml with open(file_path) as f: content = f.read() # Extract frontmatter match = re.match(r'^---\n(.*?)\n---', content, re.DOTALL) frontmatter = yaml.safe_load(match.group(1)) tags = frontmatter.get('tags', []) -
Apply refactoring rules
refactored_tags = [] for tag in tags: # Remove inline prefix tag = tag.lstrip('#') # Apply migrations tag = apply_migrations(tag, note_type, note_content) # Normalize case tag = tag.lower() # Skip template variables if '{{' in tag: continue refactored_tags.append(tag) -
Contextual flat tag resolution
def apply_migrations(tag, note_type, content): # Simple mappings FLAT_TO_HIERARCHICAL = { 'adr': 'type/adr', 'mroSystem': 'technology/mroPlatform', 'aws': 'technology/aws', 'ai': 'technology/ai', 'dataPlatform': 'project/dataPlatform', 'modernization': 'project/modernization', 'myProject': 'project/myProject', 'moc': 'moc', # Approved special tag 'daily': 'daily', # Approved special tag } # Context-dependent if tag == 'architecture': # Check if it's an activity or domain if 'decision' in content.lower() or note_type == 'Adr': return 'activity/architecture' else: return 'domain/engineering' if tag == 'integration': if 'integration pattern' in content.lower(): return 'activity/integration' else: return 'domain/integration' # Direct mapping if tag in FLAT_TO_HIERARCHICAL: return FLAT_TO_HIERARCHICAL[tag] # Already hierarchical - normalize case only return tag -
Update frontmatter
frontmatter['tags'] = refactored_tags # Rebuild YAML new_frontmatter = yaml.dump(frontmatter, sort_keys=False) # Replace in file new_content = re.sub( r'^---\n.*?\n---', f'---\n{new_frontmatter}---', content, count=1, flags=re.DOTALL ) with open(file_path, 'w') as f: f.write(new_content)
Tag Migration Reference
Common Flat Tag Migrations
| Old Tag | New Tag | Context |
|---|---|---|
ADR | type/adr | Always |
MROSystem | technology/mroPlatform | Always |
AWS | technology/aws | Always |
AI | technology/ai | Always |
MRO | technology/mro-software | Technology context |
mroSystem | technology/mroPlatform | Always |
aws | technology/aws | Always |
dataPlatform | project/dataPlatform | Always |
modernization | project/modernization | Always |
myProject | project/myProject | Always |
ecp | project/ecp | Always |
architecture | activity/architecture | Activity context |
architecture | domain/engineering | Domain context (rare) |
integration | activity/integration | Activity context |
integration | domain/integration | Domain context |
security | domain/security | Always |
governance | activity/governance | Always |
documentation | activity/documentation | Always |
Capitalized Hierarchy Migrations
| Old Tag | New Tag |
|---|---|
Project/ModernizationProject | project/modernization |
Project/LegacyEngineeringSystem-Futures | project/modernization |
Technology/MROPlatform | technology/mroPlatform |
Technology/AWS | technology/aws |
Domain/Engineering-Systems | domain/engineering |
Inline Prefix Removal
| Old Tag | New Tag |
|---|---|
#activity/architecture | activity/architecture |
#technology/aws | technology/aws |
#project/myProject | project/myProject |
Usage Examples
Example 1: Analyze Current Note
$ /tag-analyze
Analyzing: ADR - AIIncidentProcessor - Bedrock.md
Current tags: [ADR, activity/architecture, AWS, Bedrock, aiProcessor]
Issues Found:
✗ Flat tag: ADR (should be type/adr)
✗ Case violation: AWS (should be technology/aws)
✗ Flat tag: Bedrock (should be technology/bedrock)
✗ Flat tag: aiProcessor (should be project/aiProcessor)
✗ Missing minimum tags: Only 5 tags, ADRs need 4-7 with required hierarchies
Missing Required Hierarchies:
✗ No domain/ tag (required for ADRs)
Suggestions:
+ Add: type/adr (artifact type)
+ Add: technology/aws (platform)
+ Add: technology/bedrock (AI service)
+ Add: project/aiProcessor (project context)
+ Add: domain/cloud (business area)
+ Add: domain/security (security considerations)
Recommended tags:
tags: [type/adr, activity/architecture, technology/aws, technology/bedrock, project/aiProcessor, domain/cloud, domain/security]
Example 2: Refactor Vault (Dry Run)
$ /tag-refactor vault --dry-run
Vault Tag Refactoring Preview
==============================
Analyzing 2,535 markdown files...
Summary:
- 732 files with tags to refactor
- 1,148 files with no tags (skipped)
- 655 files with empty tags [] (skipped)
Changes Preview (first 10):
1. ADR - AIIncidentProcessor - Bedrock.md
- Remove: ADR → Add: type/adr
- Normalize: AWS → technology/aws
- Normalize: Bedrock → technology/bedrock
- Normalize: aiProcessor → project/aiProcessor
2. Project - MyDataIntegration.md
- Remove: Project → Add: project/myProject
- Normalize: SAP → technology/sap
- Add recommended: domain/data, domain/integration
3. System - DataPlatform.md
- Remove inline: #activity/architecture → activity/architecture
- Normalize: DataPlatform → type/system
- Add missing: criticality/critical
...
Total Changes:
- 124 case normalizations
- 67 flat to hierarchical conversions
- 10 inline prefix removals
- 11 template variable deletions
- 203 recommended tags to add
Run without --dry-run to apply changes.
Recommend: git commit current state first.
Example 3: Find Specific Violations
$ /tag-find-violations case
Finding case violations across vault...
Found 47 files with case violations:
1. ADR - SAP to AWS Connectivity.md
- ADR (should be lowercase in hierarchy)
- AWS (should be lowercase in hierarchy)
2. Project - ModernizationProject.md
- MROPlatform (should be lowercase)
- SAP (should be lowercase)
3. Meeting - 2026-01-10 ECP Core.md
- ECP (should be lowercase or hierarchical)
...
Summary:
- 24 files with uppercase flat tags
- 18 files with mixed case in hierarchies
- 5 files with capitalized prefixes (Project/, Technology/)
Run /tag-refactor to fix these violations.
Example 4: Migrate Specific Tag
$ /tag-migrate "ADR" "type/adr"
Migrating tag: ADR → type/adr
Found 41 files with tag "ADR":
1. ADR - API Gateway Selection.md
2. ADR - AIIncidentProcessor - AI Services.md
3. ADR - AIIncidentProcessor - Bedrock.md
...
Preview changes? [y/N]: y
Changes to apply:
- Replace "ADR" with "type/adr" in 41 files
- Preserve all other tags
- Update frontmatter YAML
Apply changes? [y/N]: y
✓ Updated 41 files successfully
✓ No errors
Summary:
- 41 files updated
- 0 files skipped
- 0 errors
Best Practices
- Always run --dry-run first - Preview changes before applying
- Commit to git before refactoring - Easy rollback if needed
- Refactor incrementally - Start with specific violations, then full vault
- Review suggestions - AI suggestions may need manual adjustment
- Use /tag-suggest liberally - Get recommendations for new notes
- Run quarterly audits - Use
/tag-analyze vaultto monitor quality
Integration with Other Skills
This skill works well with:
/quality-report- Includes tag analysis/vault-maintenance- Includes tag health checks/adr- Suggests tags when creating ADRs/project-status- Analyzes project tags
References
- [[.claude/rules/tag-taxonomy.md]] - Official taxonomy (authoritative)
- [[.claude/vault-conventions.md]] - Tag syntax and conventions
- [[.claude/rules/quality-patterns.md]] - Quality patterns and tag guidance
Sources:
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: 197k | 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 |