dgtags

name	DgTags
description	Tag indexing, analysis, and optimization for the Alternef Digital Garden. USE WHEN tag quality, tag indexing, tag suggestion, tag vocabulary, bulk tag cleanup, untagged notes.

Customization

Before executing, check for user customizations at: ~/.claude/PAI/USER/SKILLCUSTOMIZATIONS/DgTags/

If this directory exists, load and apply any PREFERENCES.md, configurations, or resources found there. These override default behavior. If the directory does not exist, proceed with skill defaults.

MANDATORY: Voice Notification (REQUIRED BEFORE ANY ACTION)

You MUST send this notification BEFORE doing anything else when this skill is invoked.

1. Send voice notification:

   curl -s -X POST http://localhost:8888/notify \
     -H "Content-Type: application/json" \
     -d '{"message": "Loading DgTags skill for tag management"}' \
     > /dev/null 2>&1 &
   

2. Output text notification:

   Loading **DgTags** skill for tag management...
   

This is not optional. Execute this curl command immediately upon skill invocation.

Digital Garden Tag Management

Single source of truth for all tag conventions, vocabulary, and management workflows in the Alternef Digital Garden. This skill provides indexing, analysis, optimization, and suggestion tools for the garden's tag system.

DgTags is the authority on tags. Other skills (DgNotes, DgBlog) defer here for tag rules. Do not define tag conventions in those skills.

Workflow Routing

Trigger	Workflow
Index tags only (no analysis)	Workflows/IndexTags.md
Index + full report / "make a report" / "analyze tags"	Workflows/IndexTags.md → Workflows/AnalyzeTags.md (chained, always both)
Fix tags in bulk (format, aliases, empty)	Workflows/OptimizeTags.md
Suggest tags for a specific note	Workflows/SuggestTags.md

Chaining rule: Any request containing "report", "analyze", "quality", or "issues" MUST chain IndexTags → AnalyzeTags and write STATE/analysis-report.md. IndexTags alone is only correct when the user explicitly asks only to scan or build the frequency table.

Context files: TagVocabulary.md · Workflows/IndexTags.md · Workflows/AnalyzeTags.md · Workflows/OptimizeTags.md · Workflows/SuggestTags.md

State files (generated, gitignored): STATE/tag-index.json · STATE/tag-frequencies.json · STATE/empty-files.json · STATE/format-issues.json · STATE/last-indexed.txt · STATE/analysis-report.md

Tag Conventions (Summary)

Full rules live in TagVocabulary.md. Summary:

• Format: YAML array — tags: ["tag1", "tag2"]
• Case: Lowercase kebab-case always
• Order: Domain tag first, then specific to general
• Count: 3-7 tags per note
• Blog exception: blog is always the first tag for blog posts
• Aliases: Do not use short forms. artificial-intelligence not ai. See alias table in TagVocabulary.md.

Integration with Other Skills

DgNotes: Load DgTags after drafting a note to get tag suggestions via SuggestTags. Tag rules live here, not in DgNotes.

DgBlog: Load DgTags after drafting a blog post and run SuggestTags — blog will be prepended automatically. Tag rules live here, not in DgBlog (except the blog-first exception, which stays in DgBlog).

DgQuartzDev: Tag rendering and TagPage generation belong to DgQuartzDev. Tag content management belongs here.

Garden MCP Tools — MANDATORY FIRST

BLOCKING RULE: For any single-note or quick tag lookup, call an MCP tool before reading TagVocabulary.md or running shell commands.

Operation	Primary Tool	When to Use IndexTags.ts Instead
List all tags with note counts	mcp__garden__garden_tag_list	Never for quick checks
Find all notes carrying a given tag	mcp__garden__garden_tags	Never for quick checks
Full tag index + analysis report	Tools/IndexTags.ts	Always for IndexTags/AnalyzeTags/OptimizeTags workflows

Index freshness protocol:

• Before any garden_tag_list or garden_tags call, if a bulk tag edit (OptimizeTags) just ran: call mcp__garden__garden_status first and verify the index has processed all recent writes.
• IndexTags.ts writes to STATE/ files but does NOT modify content files — it does not affect the garden MCP index.
• After OptimizeTags rewrites frontmatter tags across many files: the file watcher will process each write within ~1s. For 50+ files, wait ~30s and confirm via garden_status before trusting garden_tag_list counts.
• Still stale after 30s? Run /dg:index sync to force a full rebuild.

garden_tag_list reads from the live index and is suitable for quick lookups. Use IndexTags.ts whenever running the full workflow chains (IndexTags → AnalyzeTags → OptimizeTags).

Tools

Tools/IndexTags.ts — TypeScript CLI scanner. Scans all content/**/*.md, parses frontmatter (handles both YAML array and YAML list formats), writes state files.

# From project root:
bun .claude/skills/DgTags/Tools/IndexTags.ts --output markdown
bun .claude/skills/DgTags/Tools/IndexTags.ts --filter-empty
bun .claude/skills/DgTags/Tools/IndexTags.ts --output json --min-count 5

Examples

Example 1: Index the entire garden's tags and make a report

User: "Index all the tags in the garden" / "make a report" / "analyze tags"
→ Load DgTags skill
→ Run IndexTags workflow: bun .claude/skills/DgTags/Tools/IndexTags.ts --output markdown
→ (state files written: tag-index.json, tag-frequencies.json, empty-files.json, format-issues.json)
→ Immediately chain to AnalyzeTags workflow (load TagVocabulary.md, check aliases, orphans, non-vocab tags)
→ Write STATE/analysis-report.md with full structured output from both workflows
→ Present condensed summary to user
→ Offer to run OptimizeTags next

Example 2: Suggest tags for a newly created note

User: "Suggest tags for content/knowledge/tools-and-technology/holochain/hdk.md"
→ Load DgTags skill
→ Run SuggestTags workflow
→ Read note: path is in tools-and-technology → domain tag is `programming`
→ Detect: note is about HDK, Rust, Holochain architecture
→ Output: tags: ["programming", "holochain", "rust", "distributed-systems"]
→ Offer to write tags to frontmatter

Example 3: Clean up tag quality issues

User: "Fix the tag quality issues in the garden"
→ Load DgTags skill
→ Run IndexTags workflow (or use fresh state)
→ Run AnalyzeTags workflow → find 316 empty files, 12 alias uses, 8 format issues
→ Run OptimizeTags workflow
→ Step 2: normalize 8 YAML-list files to array format (with confirmation)
→ Step 3: merge `ai` → `artificial-intelligence` in 4 files (with confirmation)
→ Step 4: suggest tags for empty files one at a time (with per-note confirmation)