--- description: Batch auto-tag notes using parallel Haiku agents to analyse content and suggest hierarchical tags model: haiku --- # /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 | Parameter | Description | Required | |---------------|------------------------------------------------------|----------| | `--scope` | Folder or glob pattern (default: notes missing tags) | No | | `--mode` | `suggest` shows tags; `apply` writes them (default: `suggest`) | No | | `--taxonomy` | Path to tag taxonomy file for reference | No | | `--type` | Only process notes of a specific frontmatter type | No | | `--limit` | Maximum number of notes to process | No | ## 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. | Type | Auto-tags | Notes | |-------------|-----------------------------------------|------------------------------------------| | ADR | `type/adr`, `activity/architecture` | Architecture Decision Records | | Project | `activity/delivery` | Also add `project/` from title | | Meeting | `activity/meeting` | Infer topic tags from title/content | | Task | `activity/task` | Infer project from `project:` field | | Research | `activity/research` | Research and investigation notes | | Incubator | `activity/research` | Early-stage ideas and explorations | | Concept | `type/concept` | Infer domain tags from content | | Pattern | `type/pattern` | Infer domain tags from content | | Reference | `type/reference` | Also infer from `referenceType` if set | | System | `type/system` | Technology entity notes | | Daily | `daily` | Daily journal entries | | Email | _(infer from content)_ | No deterministic tags | | Trip | _(skip)_ | Typically no tags needed | ### 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. | Content Keywords | Suggested Tag | |--------------------------------------------|---------------------------| | AWS, Lambda, S3, EC2, CloudFormation | `technology/aws` | | Kafka, streaming, event-driven | `technology/kafka` | | API, REST, GraphQL, endpoint, OpenAPI | `technology/api` | | database, SQL, migration, schema, ORM | `technology/database` | | Docker, Kubernetes, container, helm | `technology/containers` | | CI/CD, pipeline, deployment, GitHub Actions| `technology/cicd` | | Python, JavaScript, TypeScript, Go, Rust | `technology/` | | security, IAM, encryption, authentication | `domain/security` | | data, analytics, pipeline, warehouse | `domain/data` | | cloud, infrastructure, networking | `domain/cloud` | | integration, middleware, message broker | `domain/integration` | | architecture, design, pattern, C4 | `activity/architecture` | | research, investigation, POC, spike | `activity/research` | | governance, compliance, policy, audit | `activity/governance` | | meeting, standup, review, retrospective | `activity/meeting` | | risk, threat, vulnerability, CVE | `domain/security` | | documentation, guide, how-to, runbook | `activity/documentation` | | planning, roadmap, strategy, vision | `activity/planning` | | monitoring, observability, logging, alerts | `domain/operations` | ### 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 ```yaml # 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 ```markdown # 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