Imported from vincentxuu/quidproquo (.claude/skills/glossary-maintenance/SKILL.md). Install upstream with npx skills add vincentxuu/quidproquo --skill glossary-maintenance. Copyright stays with the author.

Glossary Maintenance

維護文章術語提示，讓讀者查過、容易卡住的詞回流成可點開的 glossary 解釋。

何時使用

• 每月內容維護時，回顧 glossary_lookup_stats。
• 新增或大改 3–5 篇文章後，檢查 glossary coverage。
• 使用者問「哪些詞該補 glossary」、「讀者常查哪些詞」、「要補全站詞彙還是文章詞彙」。

維護節奏

判斷規則

• 累積查詢 5 次以上：檢查是否需要補 glossary。
• 同一詞出現在多篇文章，或是通用概念：補到 src/lib/glossary/terms.ts 的 DEFAULT_GLOSSARY_TERMS。
• 只集中在單篇文章、專案代號、特定脈絡：補到該篇文章 frontmatter 的 glossary。
• 不補所有專有名詞，只補「不解釋會影響理解」的詞。

查詢方式

glossary_lookup_stats 是讀者點查 glossary 時累積的 D1 統計，不是每次寫文章都要查。

常用查詢：

SELECT term, SUM(lookup_count) AS total, COUNT(DISTINCT slug) AS post_count
FROM glossary_lookup_stats
GROUP BY term
HAVING total >= 5
ORDER BY total DESC, post_count DESC;

判斷某個詞集中在哪些文章：

SELECT term, slug, SUM(lookup_count) AS total
FROM glossary_lookup_stats
WHERE term = ?
GROUP BY term, slug
ORDER BY total DESC;

執行步驟

1. 跑 coverage 檢查或查 lookup stats。
2. 列出候選詞：term、total lookup、post_count、主要 slug。
3. 逐詞判斷：全站詞彙、文章詞彙、暫不處理。
4. 修改 DEFAULT_GLOSSARY_TERMS 或文章 frontmatter glossary。
5. 跑 pnpm check:post-quality <file> 與 pnpm check:references <file>；若改了全站詞彙，再抽樣打開文章確認 glossary popover 正常。

常見錯誤

• 把 glossary_lookup_stats 當成發文前必跑：錯，它適合發布後或內容維護時看。
• 看到技術名詞就全補：錯，只補會阻礙理解的詞。
• 單篇特有詞放進全站：錯，先放該篇 frontmatter，除非多篇文章都會用到。