Back to Details

taxonomy-manager

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Taxonomy Manager Skill

分类法管理器技能

Operator Context

操作上下文

This skill operates as an operator for taxonomy management workflows on Hugo-based blogs, configuring Claude's behavior for consistent, SEO-friendly categorization. It implements the Scan-Analyze-Report-Act architectural pattern with preview-first safety and build verification gates.
本技能作为基于Hugo的博客分类法管理工作流的操作器，配置Claude的行为以实现一致、SEO友好的分类。它采用扫描-分析-报告-执行的架构模式，并带有预览优先的安全机制和构建验证环节。

Hardcoded Behaviors (Always Apply)

硬编码行为（始终适用）

  • CLAUDE.md Compliance: Read and follow repository CLAUDE.md before execution
  • Over-Engineering Prevention: Fix actionable taxonomy issues only; no elaborate classification redesigns without explicit request
  • Preview-First Workflow: Always show current state and proposed changes before modifying any files
  • Case Normalization: Hugo taxonomies are case-sensitive; standardize all terms to 
    lowercase-with-hyphens
  • Non-Destructive Operations: Never delete or rename taxonomy terms without explicit user confirmation
  • Build Verification: Run 
    hugo --quiet
    after every batch of changes to confirm site still builds
  • CLAUDE.md 合规性：执行前阅读并遵循仓库中的CLAUDE.md
  • 防止过度设计：仅修复可操作的分类法问题；无明确请求时，不得进行复杂的分类重构
  • 预览优先工作流：修改任何文件前，始终展示当前状态和拟议变更
  • 大小写标准化：Hugo分类法区分大小写；将所有术语标准化为
    lowercase-with-hyphens
    格式
  • 非破坏性操作：未经用户明确确认，不得删除或重命名分类法术语
  • 构建验证：每完成一批变更后，运行
    hugo --quiet
    以确认站点仍可正常构建

Default Behaviors (ON unless disabled)

默认行为（默认开启，可关闭）

  • Complete Output: Show full taxonomy audit with visual charts, never summarize
  • Similarity Detection: Flag potentially duplicate tags (case variations, plurals, synonyms)
  • Orphan Detection: Identify tags used only once or categories with no posts
  • Confirmation Required: Require explicit confirmation before modifying any content files
  • One Operation at a Time: Apply merge/rename/add/remove operations individually, verify between each
  • 完整输出：展示包含可视化图表的完整分类法审计报告，不得简化
  • 相似性检测：标记潜在重复标签（大小写变体、复数形式、同义词）
  • 孤立项检测：识别仅使用一次的标签或无文章的分类
  • 需确认操作：修改任何内容文件前需获得明确确认
  • 单次单操作：单独应用合并/重命名/添加/删除操作，每次操作后进行验证

Optional Behaviors (OFF unless enabled)

可选行为（默认关闭，可开启）

  • Auto-Apply: Apply suggested changes without per-file confirmation
  • Batch Mode: Process all detected issues in a single pass
  • Aggressive Merge: Merge all similar tags automatically (requires explicit opt-in)
  • 自动应用：无需逐文件确认即可应用建议的变更
  • 批量模式：一次性处理所有检测到的问题
  • 激进合并：自动合并所有相似标签（需明确选择启用）

What This Skill CAN Do

本技能可执行操作

  • Audit all categories and tags across a Hugo site's content directory
  • Count posts per taxonomy term and generate visual usage statistics
  • Detect orphan tags (single-use), empty categories, case variations, and synonym pairs
  • Suggest and execute merge, rename, add, and remove operations on taxonomy terms
  • Show before/after diffs for every proposed change
  • Verify Hugo build integrity after modifications
  • 审计Hugo站点内容目录下的所有分类和标签
  • 统计每个分类法术语的文章数量并生成可视化使用统计
  • 检测孤立标签（仅使用一次）、空分类、大小写变体和同义词对
  • 建议并执行分类法术语的合并、重命名、添加和删除操作
  • 展示每项拟议变更的前后差异
  • 修改后验证Hugo构建完整性

What This Skill CANNOT Do

本技能不可执行操作

  • Create new categories without explicit instruction (taxonomy design is intentional)
  • Auto-merge tags without review (similar tags may have distinct meanings)
  • Modify post content beyond front matter (preserves author's voice)
  • Guarantee SEO improvements (taxonomy is one factor among many)
  • Skip confirmation or build verification gates
  • 无明确指令时创建新分类（分类法设计需有意为之）
  • 未经审核自动合并标签（相似标签可能具有不同含义）
  • 修改文章正文内容（保留作者的表达风格）
  • 保证SEO效果提升（分类法只是众多影响因素之一）
  • 跳过确认或构建验证环节

Instructions

操作说明

Phase 1: SCAN - Collect Taxonomy Data

阶段1：扫描 - 收集分类法数据

Goal: Build a complete index of all taxonomy terms and their usage.
Step 1: Identify all content files
Locate every Markdown file in the Hugo content directory.
bash
find /path/to/content -name "*.md" -type f | sort
Step 2: Extract front matter from each post
For each file, parse the YAML front matter and extract:
  • title
    (for reference in reports)
  • categories
    (list)
  • tags
    (list)
Step 3: Build taxonomy index
Construct an in-memory mapping of every taxonomy term to its list of posts:
CATEGORIES:
  technical-notes: [post1.md, post2.md, post3.md]
  tutorials: [post4.md, post5.md]

TAGS:
  hugo: [post1.md, post2.md, post4.md]
  debugging: [post1.md, post3.md]
Step 4: Check Hugo taxonomy configuration
Read 
hugo.toml
(or 
config.toml
) for any custom taxonomy definitions or overrides.
Gate: Taxonomy index is complete with all terms mapped to their posts. Proceed only when gate passes.
目标：构建所有分类法术语及其使用情况的完整索引。
步骤1：识别所有内容文件
定位Hugo内容目录中的所有Markdown文件。
bash
find /path/to/content -name "*.md" -type f | sort
步骤2：提取每篇文章的前置元数据
对每个文件，解析YAML前置元数据并提取：
  • title
    （用于报告参考）
  • categories
    （列表）
  • tags
    （列表）
步骤3：构建分类法索引
构建内存映射，将每个分类法术语映射到其对应的文章列表：
分类:
  technical-notes: [post1.md, post2.md, post3.md]
  tutorials: [post4.md, post5.md]

标签:
  hugo: [post1.md, post2.md, post4.md]
  debugging: [post1.md, post3.md]
步骤4：检查Hugo分类法配置
读取
hugo.toml
（或
config.toml
）中的自定义分类法定义或覆盖配置。
检查点：分类法索引已完整包含所有术语及其对应文章。仅当检查点通过后才可继续。

Phase 2: ANALYZE - Detect Issues

阶段2：分析 - 检测问题

Goal: Identify all taxonomy health problems from the index.
Step 1: Calculate usage statistics
For each taxonomy term compute: post count, percentage of total, and staleness (months since last use).
Step 2: Detect issues
Run these checks against the index:
CheckCriteriaSeverity
Orphan tagsUsed in only 1 postLow
Empty categoriesDefined in config but 0 postsMedium
Case variationsSame word, different casing (
Hugo
vs 
hugo
)		High
Plural variations
template
vs 
templates
Medium
Synonym pairs
debugging
vs 
troubleshooting
Medium
Abbreviation pairs
cicd
vs 
ci-cd
Low
Hierarchical overlap
git-submodules
under broader 
git
Medium
Step 3: Assess health metrics
MetricHealthyWarning
Total categories3-7<3 or >10
Total active tags10-30<5 or >50
Tags per post (avg)3-5<2 or >7
Categories per post (avg)1-20 or >3
Orphan tag ratio<20%>30%
Gate: All issues catalogued with severity. Health metrics computed. Proceed only when gate passes.
目标：从索引中识别所有分类法健康问题。
步骤1：计算使用统计
为每个分类法术语计算：文章数量、占总数的百分比、陈旧度（上次使用至今的月数）。
步骤2：检测问题
对索引执行以下检查：
检查项判定标准严重程度
孤立标签仅在1篇文章中使用低
空分类配置中已定义但无文章中
大小写变体同一单词的不同大小写（
Hugo
vs 
hugo
）		高
复数变体
template
vs 
templates
中
同义词对
debugging
vs 
troubleshooting
中
缩写对
cicd
vs 
ci-cd
低
层级重叠
git-submodules
属于更宽泛的 
git
分类		中
步骤3：评估健康指标
指标健康状态警告状态
总分类数3-7<3 或 >10
活跃标签总数10-30<5 或 >50
单篇文章平均标签数3-5<2 或 >7
单篇文章平均分类数1-20 或 >3
孤立标签占比<20%>30%
检查点：所有问题已按严重程度分类，健康指标已计算完成。仅当检查点通过后才可继续。

Phase 3: REPORT - Generate Audit Output

阶段3：报告 - 生成审计输出

Goal: Present findings in a structured, actionable report.
Generate the visual audit report following the format in 
references/audit-report-format.md
. The report must include:
  1. Category usage with bar charts
  2. Tag usage with bar charts
  3. Health metrics dashboard
  4. Issues found (orphans, duplicates, similar terms, empty categories)
  5. Prioritized recommendations ordered by impact (High > Medium > Low)
Present the report to the user. If no issues are found, state the taxonomy is healthy.
Gate: Report presented. User has reviewed findings. Proceed to Phase 4 only if user requests changes.
目标：以结构化、可执行的格式呈现发现的问题。
按照
references/audit-report-format.md
中的格式生成可视化审计报告。报告必须包含：
  1. 分类使用情况条形图
  2. 标签使用情况条形图
  3. 健康指标仪表盘
  4. 发现的问题（孤立项、重复项、相似术语、空分类）
  5. 按影响优先级排序的建议（高 > 中 > 低）
将报告呈现给用户。如果未发现问题，说明分类法处于健康状态。
检查点：报告已呈现，用户已审阅发现的问题。仅当用户请求变更时才可进入阶段4。

Phase 4: ACT - Apply Changes

阶段4：执行 - 应用变更

Goal: Execute approved taxonomy modifications safely.
Step 1: Preview every change
Before any file modification, show:
File: content/posts/example.md
  Current tags: ["Hugo", "debugging", "templates"]
  New tags:     ["hugo", "debugging", "templates"]
  Change: Standardize "Hugo" -> "hugo"
Step 2: Get confirmation
Wait for explicit user approval before proceeding.
Step 3: Apply operations
Execute the approved operation (merge, rename, add, or remove). See 
references/consolidation-rules.md
for operation semantics:
  • Merge: Replace source tag(s) with target in all posts; skip if post already has target
  • Rename: Replace old name with new in all posts
  • Add: Add tag to matching posts (skip if already present)
  • Remove: Remove term from front matter or config (only if unused)
Step 4: Verify build
bash
hugo --quiet
If build fails, immediately roll back:
bash
git checkout content/
Step 5: Show diff
bash
git diff content/
Gate: All changes applied, build verified, diff reviewed. Operation complete.
目标：安全执行已批准的分类法修改。
步骤1：预览所有变更
修改任何文件前，展示：
文件: content/posts/example.md
  当前标签: ["Hugo", "debugging", "templates"]
  新标签:     ["hugo", "debugging", "templates"]
  变更: 将 "Hugo" 标准化为 "hugo"
步骤2：获取确认
等待用户明确批准后再继续。
步骤3：执行操作
执行已批准的操作（合并、重命名、添加或删除）。有关操作语义，请参阅
references/consolidation-rules.md
：
  • 合并：在所有文章中将源标签替换为目标标签；如果文章已包含目标标签则跳过
  • 重命名：在所有文章中将旧名称替换为新名称
  • 添加：为匹配的文章添加标签（已存在则跳过）
  • 删除：从前置元数据或配置中删除术语（仅当未使用时）
步骤4：验证构建
bash
hugo --quiet
如果构建失败，立即回滚：
bash
git checkout content/
步骤5：展示差异
bash
git diff content/
检查点：所有变更已应用，构建已验证，差异已审阅。操作完成。

Examples

示例

Example 1: Routine Taxonomy Audit

示例1：常规分类法审计

User says: "Audit my blog tags" Actions:
  1. Scan all content files and build taxonomy index (SCAN)
  2. Detect case variations, orphan tags, empty categories (ANALYZE)
  3. Generate visual report with health metrics and recommendations (REPORT)
  4. User reviews report; no changes requested Result: Clean audit report, user informed of taxonomy health
用户说：「审计我的博客标签」 操作：
  1. 扫描所有内容文件并构建分类法索引（扫描阶段）
  2. 检测大小写变体、孤立标签、空分类（分析阶段）
  3. 生成包含健康指标和建议的可视化报告（报告阶段）
  4. 用户审阅报告；未请求变更 结果：生成清晰的审计报告，告知用户分类法健康状况

Example 2: Tag Consolidation

示例2：标签合并

User says: "I have Hugo, hugo, and HUGO as separate tags, fix it" Actions:
  1. Scan content to find all posts using each variant (SCAN)
  2. Confirm these are case variations of the same term (ANALYZE)
  3. Report: 3 variants found across N posts, recommend standardizing to 
    hugo
    (REPORT)
  4. Preview per-file changes, get confirmation, apply, verify build (ACT) Result: All posts use 
    hugo
    , single tag page shows all related content
用户说：「我有Hugo、hugo和HUGO三个独立标签，修复它」 操作：
  1. 扫描内容以找到使用每个变体的所有文章（扫描阶段）
  2. 确认这些是同一术语的大小写变体（分析阶段）
  3. 报告：发现3种变体分布在N篇文章中，建议标准化为
    hugo
    （报告阶段）
  4. 预览逐文件变更，获取确认，应用变更，验证构建（执行阶段） 结果：所有文章使用
    hugo
    标签，单个标签页面展示所有相关内容

Example 3: Post-Publication Cleanup

示例3：发布后清理

User says: "I just published 10 new posts, clean up the taxonomy" Actions:
  1. Scan all content including new posts (SCAN)
  2. Detect new orphan tags, inconsistencies introduced by recent posts (ANALYZE)
  3. Report new issues separately from pre-existing ones (REPORT)
  4. Apply approved merges and renames, verify build after each batch (ACT) Result: New posts integrated into existing taxonomy structure
用户说：「我刚发布了10篇新文章，清理分类法」 操作：
  1. 扫描所有内容包括新文章（扫描阶段）
  2. 检测新的孤立标签和近期文章引入的不一致（分析阶段）
  3. 单独报告新问题与原有问题（报告阶段）
  4. 应用已批准的合并和重命名，每批操作后验证构建（执行阶段） 结果：新文章已整合到现有分类法结构中

Error Handling

错误处理

Error: "No Content Files Found"

错误：「未找到内容文件」

Cause: Content directory missing, empty, or wrong path Solution:
  1. Verify the content directory path exists
  2. Check for nested content structures (e.g., 
    content/posts/
    vs 
    content/
    )
  3. Confirm files use 
    .md
    extension
原因：内容目录缺失、为空或路径错误 解决方案：
  1. 验证内容目录路径是否存在
  2. 检查是否有嵌套内容结构（例如
    content/posts/
    vs 
    content/
    ）
  3. 确认文件使用
    .md
    扩展名

Error: "Invalid Front Matter in {file}"

错误：「{file} 中的前置元数据无效」

Cause: Malformed YAML in a content file Solution:
  1. Check for missing closing 
    ---
    delimiter
  2. Look for tabs (YAML requires spaces)
  3. Check for unquoted special characters (colons, brackets)
  4. Skip the file with a warning and continue processing remaining files
原因：内容文件中的YAML格式错误 解决方案：
  1. 检查是否缺少闭合的
    ---
    分隔符
  2. 查找制表符（YAML要求使用空格）
  3. 检查未加引号的特殊字符（冒号、括号）
  4. 跳过该文件并发出警告，继续处理剩余文件

Error: "Hugo Build Failed After Changes"

错误：「变更后Hugo构建失败」

Cause: Taxonomy modifications broke the site build Solution:
  1. Roll back immediately: 
    git checkout content/
  2. Read the Hugo error output to identify the specific failure
  3. Re-apply changes one file at a time to isolate the problem
  4. Fix the problematic file before retrying the batch
原因：分类法修改导致站点构建失败 解决方案：
  1. 立即回滚：
    git checkout content/
  2. 读取Hugo错误输出以确定具体失败原因
  3. 逐文件重新应用变更以隔离问题
  4. 修复有问题的文件后再重试批量操作

Error: "Tag Not Found: {tag}"

错误：「未找到标签：{tag}」

Cause: User requested merge/rename of a tag that does not exist in any post Solution:
  1. List all existing tags that are similar (fuzzy match)
  2. Suggest closest match: 
    Did you mean "{similar_tag}"?
  3. If no close match exists, report that the tag is absent and list available tags
原因：用户请求合并/重命名的标签未在任何文章中使用 解决方案：
  1. 列出所有相似的现有标签（模糊匹配）
  2. 建议最接近的匹配项：「您是否指 "{similar_tag}"?」
  3. 如果没有接近的匹配项，报告该标签不存在并列出可用标签

Anti-Patterns

反模式

Anti-Pattern 1: Tag Explosion

反模式1：标签爆炸

What it looks like: Creating 
hugo-themes
, 
hugo-templates
, 
hugo-debugging
, 
hugo-config
instead of using 
hugo
+ 
themes
Why wrong: Fragments the taxonomy; users browsing "hugo" miss related posts scattered across subtags Do instead: Use broader tags in combination (
hugo
+ 
debugging
) and let post content provide specificity
表现：创建
hugo-themes
、
hugo-templates
、
hugo-debugging
、
hugo-config
等标签，而非使用
hugo
+ 
themes
问题所在：拆分分类法；浏览「hugo」的用户会错过分散在子标签中的相关文章 正确做法：使用更宽泛的标签组合（
hugo
+ 
debugging
），让文章内容提供具体细节

Anti-Pattern 2: Case Inconsistency

反模式2：大小写不一致

What it looks like: 
Hugo
in one post, 
hugo
in another, 
HUGO
in a third Why wrong: Hugo treats these as separate tags, creating three different tag pages each showing a fraction of the posts Do instead: Standardize all terms to 
lowercase-with-hyphens
; run this skill regularly to catch drift
表现：一篇文章用
Hugo
，另一篇用
hugo
，第三篇用
HUGO
问题所在：Hugo将这些视为独立标签，创建三个不同的标签页面，每个页面仅显示部分相关文章 正确做法：将所有术语标准化为
lowercase-with-hyphens
格式；定期运行此技能以发现偏差

Anti-Pattern 3: Single-Use Tags as Description

反模式3：用标签作为描述

What it looks like: 
fixing-hugo-template-rendering-issues
as a tag on a post titled "Fixing Hugo Template Rendering Issues" Why wrong: The tag duplicates the title, will never be reused, and provides zero navigation value Do instead: Use generic, reusable tags: 
hugo
, 
templates
, 
debugging
表现：在标题为「修复Hugo模板渲染问题」的文章中使用
fixing-hugo-template-rendering-issues
作为标签 问题所在：标签重复了标题内容，永远不会被重复使用，无法提供导航价值 正确做法：使用通用、可复用的标签：
hugo
、
templates
、
debugging

Anti-Pattern 4: Merging Without Understanding

反模式4：无理解合并

What it looks like: Automatically merging 
debugging
and 
troubleshooting
because they seem similar Why wrong: Near-synonyms may carry distinct connotations in context; aggressive merging can lose meaningful distinctions Do instead: Present similar terms to the user with usage context; let them decide which to keep
表现：因为
debugging
和
troubleshooting
看起来相似就自动合并 问题所在：近同义词在上下文中可能具有不同含义；激进合并会丢失有意义的区分 正确做法：向用户展示相似术语及其使用上下文；让用户决定保留哪些

References

参考资料

This skill uses these shared patterns:
  • Anti-Rationalization - Prevents shortcut rationalizations
  • Verification Checklist - Pre-completion checks
本技能使用以下共享模式：
  • 反合理化 - 防止捷径式合理化
  • 验证清单 - 完成前检查

Domain-Specific Anti-Rationalization

领域特定反合理化

RationalizationWhy It's WrongRequired Action
"These tags are obviously the same"Similar does not mean identical; context mattersShow usage examples, let user decide
"Just a quick rename, no need to preview"Renames can break Hugo taxonomy pagesAlways preview, always verify build
"One orphan tag doesn't matter"Orphans accumulate into taxonomy debtAddress during audit or document exception
"The build passed, taxonomy must be fine"Build success does not validate semantic correctnessReview the diff, confirm navigation works
合理化借口问题所在要求操作
「这些标签显然是同一个」相似不等于相同；上下文很重要展示使用示例，让用户决定
「只是快速重命名，无需预览」重命名可能破坏Hugo分类页面始终预览，始终验证构建
「一个孤立标签无关紧要」孤立标签会累积成分类法债务在审计时处理或记录例外情况
「构建通过了，分类法肯定没问题」构建成功不代表语义正确审阅差异，确认导航正常工作

Reference Files

参考文件

  • ${CLAUDE_SKILL_DIR}/references/taxonomy-guidelines.md
    : Naming conventions, category/tag best practices, maintenance cadence
  • ${CLAUDE_SKILL_DIR}/references/consolidation-rules.md
    : When and how to merge, rename, add, or remove terms with priority matrix
  • ${CLAUDE_SKILL_DIR}/references/examples.md
    : Good vs bad taxonomy examples, before/after comparisons, audit output samples
  • ${CLAUDE_SKILL_DIR}/references/audit-report-format.md
    : Visual report template and bar chart generation rules
  • ${CLAUDE_SKILL_DIR}/references/taxonomy-guidelines.md
    ：命名规范、分类/标签最佳实践、维护周期
  • ${CLAUDE_SKILL_DIR}/references/consolidation-rules.md
    ：合并、重命名、添加或删除术语的时机与方法，含优先级矩阵
  • ${CLAUDE_SKILL_DIR}/references/examples.md
    ：分类法优劣示例、前后对比、审计输出样本
  • ${CLAUDE_SKILL_DIR}/references/audit-report-format.md
    ：可视化报告模板和条形图生成规则