| name | tags-cleanup |
| description | Analyze and clean up Forest knowledge base tags. Use when asked to "clean tags", "fix tags", "tag audit", "tag hygiene", or "normalize tags". Audits tag entropy, finds duplicates and format violations, then applies fixes via the Forest CLI. Use when this capability is needed. |
| metadata | {"author":"bwl"} |
Tags Cleanup Skill
Analyze and normalize all tags in the Forest knowledge base to the canonical namespace:value format.
Tag Schema
Canonical format: namespace:value — lowercase, hyphens for multi-word, colon separator, no # prefix.
| Namespace | Purpose | Examples |
|---|
project | Which project | project:kingdom, project:forest |
domain | Top-level domain | domain:projects, domain:ideas |
tech | Technology | tech:rust, tech:python, tech:bevy |
status | Lifecycle | status:active, status:dormant |
category | Project category | category:roguelike, category:knowledge |
area | Feature area | area:cli, area:tags |
bug | Bug reports | bug:tags-normalization |
feature | Feature requests | feature:templates |
topic | Content topic | topic:worldbuilding, topic:ai |
pattern | Patterns | pattern:tooling, pattern:planning |
Workflow
Step 1: Audit current tags
Run forest tags list --json and analyze the output. Classify every tag into one of:
- Clean: already matches
namespace:value with a valid namespace
- Rename: wrong format but has a clear canonical mapping (e.g.,
#project/foo → project:foo, rust → tech:rust)
- Delete: adds no value and should be removed from all nodes (e.g.,
source:Developer, tech:unknown, category:misc)
- Ambiguous: needs human decision
Report a summary table:
Tags Audit
──────────
Total tags: N
Clean: N (N%)
Need rename: N
Need delete: N
Ambiguous: N
Step 2: Build normalization map
For each non-clean tag, determine the action:
Rename rules (in priority order):
#namespace/value → namespace:value (strip #, replace / with :)namespace/value → namespace:value (replace / with :)- Bare language names →
tech: namespace (rust → tech:rust, python → tech:python)
- Bare topic words →
topic: namespace (writing → topic:writing)
- Merge duplicates to canonical form (e.g.,
#project/kingdom-rpg + #project/kingdom → project:kingdom)
- Multi-word values get hyphens (
layer builder → topic:layer-builder)
- Singular/plural merge to the more common form
Delete rules:
- Tags that carry no information (
source:Developer, tech:unknown)
- Junk-drawer tags (
category:misc)
- Garbage values (malformed status strings, empty
bug/, empty feature/)
Present the full map to the user for confirmation before executing.
Step 3: Execute changes
If $ARGUMENTS contains --dry-run, stop after Step 2.
Otherwise, after user confirmation:
Renames — use forest tags rename:
forest tags rename "old-tag" "new-tag"
This is a bulk operation — it renames the tag across all nodes that have it. If the target tag already exists on a node, Forest merges them.
Deletions — Forest has no bulk tag delete. For each tag to delete:
- Search for nodes with that tag:
forest search "<tag>" --limit 5 --json
- For each found node, remove the tag:
forest tags remove <node-id> "<tag>"
- Repeat until no more nodes are found
Run renames first, then deletions.
Step 4: Verify
Run forest tags list --json again and confirm:
- Zero tags with
# prefix
- Zero tags with
/ separator (should all use :)
- Zero bare tags (no namespace)
- All namespaces are from the valid set
Report final counts.
Important Notes
- Always confirm before executing. Show the full rename/delete plan and wait for approval.
forest tags rename is the primary tool — it's bulk and handles merge conflicts.forest tags remove <ref> <tag> removes a single tag from a single node. There is no bulk delete.- Semantic search may not find all nodes for a given tag. If a tag persists after deletion attempts, report it and move on rather than looping.
- Tags are case-sensitive in Forest.
Source:Developer and source:Developer are different.
- Do not touch the SQLite database directly. All changes go through the Forest CLI.
Converted and distributed by TomeVault — claim your Tome and manage your conversions.
