When to Use This Skill

/auto-tag

Batch auto-tag Markdown notes by analysing their content and suggesting appropriate hierarchical tags. Uses parallel Haiku agents processing notes in batches of 15-20 for cost-effective, high-throughput tagging.

When to Use This Skill

• Tagging a batch of newly created notes
• Applying a consistent tag taxonomy to existing notes
• Re-tagging notes after a taxonomy migration
• Ensuring all notes meet minimum tag requirements
• Filling in missing tags across the vault

Usage

/auto-tag [--scope path/to/folder] [--mode suggest|apply] [--taxonomy path/to/taxonomy.md]
/auto-tag --type Meeting         # Only process notes of a specific type
/auto-tag --limit 50             # Process at most 50 notes

Parameters

Instructions

Phase 1: Identify Notes Needing Tags

1. Scan notes in scope -- Find all Markdown files
2. Parse frontmatter -- Extract existing tags
3. Filter to candidates:
   • Notes with no tags field
   • Notes with empty tags (tags: [])
   • Notes with fewer than 2 tags
   • Notes with flat (non-hierarchical) tags
4. Exclude directories: Templates/, .obsidian/, .claude/, Archive/, Attachments/
5. Load taxonomy -- If --taxonomy provided, use it as the tag reference. Otherwise, scan existing tags across the vault to build a frequency-based taxonomy.
6. Sort by type for batch efficiency
7. Divide into batches of 15-20 notes per agent

Phase 2: Batch Tagging -- Agent Team (Parallel Haiku Agents)

Use the Batch Processing pattern. Launch N parallel agents, each processing 15-20 notes.

Agent 1-N: Tag Analyst (Haiku) Task: Analyse content and suggest tags for assigned batch

For each note in the batch:

1. Read frontmatter -- extract type, title, project, status
2. Read body content -- first 500 words
3. Apply type-based auto-tags -- deterministic tags from the Type-Based Auto-Tags table below
4. Apply content keyword matching -- use the Content Keyword-to-Tag Mapping table below
5. Apply project field matching -- if project: field exists, derive a project/ tag
6. Suggest 2-5 hierarchical tags per note total
7. Validate tags -- check all suggested tags against the taxonomy (if provided); flag any tag not in the taxonomy as "novel"

Quality rules:

• No # prefix in YAML tags
• All lowercase
• Hierarchical format required (e.g., domain/data not just data)
• Hyphens for multi-word tags (e.g., domain/supply-chain)
• Minimum 2 tags, maximum 5 tags per note
• Prefer fewer, more accurate tags over many vague ones

Return: List of { filename, existingTags[], suggestedTags[], confidence, reason } per note

Tag Mapping Reference

Customise these tables for your vault. The mappings below are generic starting points. Replace or extend them with your own domain-specific keywords, project names, and technology stack.

Type-Based Auto-Tags

These deterministic tags are always added based on the note's type frontmatter field. They require no content analysis.

Content Keyword-to-Tag Mapping

When note content (title + body) contains these keywords, suggest the corresponding tag. This table is a template -- adapt the keywords and tags to match your vault's domain and technology stack.

Project Field Mapping

If the note has a project: frontmatter field containing a wiki-link, derive a project tag:

project: "[[Project - Orders Platform]]"  -->  project/orders-platform
project: "[[Project - Cloud Migration]]"  -->  project/cloud-migration

Rule: Lowercase the project name, replace spaces with hyphens, strip the Project - prefix.

Phase 3: Synthesise and Validate

1. Compile suggestions from all agents
2. Validate against taxonomy:
   • Check every suggested tag exists in the taxonomy file (if provided)
   • Flag tags not in the taxonomy as "novel" -- these need manual review
   • Do not auto-apply novel tags
3. Group by confidence:
   • High: Tags from the type-based auto-tags table, or exact matches in the taxonomy
   • Medium: Tags inferred from content keyword matching against known taxonomy entries
   • Low: Novel tags not found in the taxonomy
4. De-duplicate -- remove tags already present on the note

Phase 4: Apply Tags

If --mode apply:

1. Apply high-confidence tags automatically
2. Present medium/low confidence tags for user review before applying

For each note with approved tags:

1. Read current frontmatter
2. If tags: [] -- replace with suggested tags
3. If no tags field -- add tags: with suggested tags
4. Never overwrite existing non-empty tags -- only add to them
5. Write updated file using Edit tool

YAML Formatting Rules

# Inline format for 1-3 tags:
tags: [activity/research, domain/data]

# Multi-line format for 4+ tags:
tags:
  - activity/architecture
  - technology/aws
  - domain/cloud
  - project/cloud-migration

Rules:

• Use inline [tag1, tag2] format when there are 1-3 tags
• Switch to multi-line format (one tag per line with - prefix) when there are 4 or more tags
• Match whichever format the file already uses, if tags were previously present
• No # prefix -- ever -- in frontmatter YAML

Phase 5: Report

# Auto-Tag Report

**Date:** YYYY-MM-DD | **Notes Processed:** X | **Tags Suggested:** X

## Summary

| Confidence | Notes | Tags Added | Action         |
|------------|-------|------------|----------------|
| High       | X     | X          | Auto-applied   |
| Medium     | X     | X          | Needs review   |
| Low        | X     | X          | Manual review  |

## Tag Suggestions

### High Confidence

| Note                   | Existing Tags          | Suggested Tags                          |
|------------------------|------------------------|-----------------------------------------|
| `ADR - API Gateway.md` | `[]`                  | + `type/adr`, `activity/architecture`   |

### Medium Confidence

| Note                   | Existing Tags | Suggested Tags              | Reason                          |
|------------------------|---------------|-----------------------------|---------------------------------|
| `Meeting - 2026-01...` | `[]`          | `activity/meeting`, `domain/data` | Title mentions data review |

### New Tags Introduced

| Tag                     | Suggested For | In Taxonomy? |
|-------------------------|---------------|--------------|
| `domain/observability`  | 3 notes       | No           |

## By Type

| Type    | Tagged | Common Tags Applied         |
|---------|--------|-----------------------------|
| Meeting | 45     | `activity/meeting`, domain/* |
| ADR     | 20     | `type/adr`, technology/*     |
| Concept | 30     | `type/concept`, domain/*     |

Safety

• Always use --mode suggest first for vault-wide operations
• Never overwrite existing non-empty tags -- tags are additive only
• Commit to git before running --mode apply
• Review novel tags before applying -- they may indicate taxonomy gaps
• Validate against taxonomy to prevent tag drift and inconsistency

Examples

Example 1: Preview Tags for All Untagged Notes

/auto-tag --mode suggest

Example 2: Apply Tags to a Specific Folder

/auto-tag --scope Meetings/2026/ --mode apply

Example 3: With Custom Taxonomy

/auto-tag --taxonomy .claude/context/tag-taxonomy.md --mode suggest

Example 4: Process Only ADRs

/auto-tag --type ADR --mode suggest

Invoke with: /auto-tag to batch-tag notes with AI-suggested hierarchical tags