glossary-management

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Glossary Management

词汇表管理

Overview

概述

Manage the global terminology glossary (

~/.claude/docs/GLOSSARY.md

) and its Vale integration. The glossary is the Single Source of Truth (SSoT) for terminology across all projects.

管理全局术语词汇表（

~/.claude/docs/GLOSSARY.md

）及其与Vale的集成。该词汇表是所有项目中术语的单一可信来源（SSoT）。

When to Use This Skill

何时使用该技能

Use when:

Manually syncing glossary to Vale vocabulary files
Validating glossary format and structure
Checking for duplicate or conflicting terms across projects
Adding new terms programmatically
Troubleshooting Vale terminology warnings

适用于以下场景：

手动将词汇表同步到Vale词汇文件
验证词汇表的格式和结构
检查跨项目的重复或冲突术语
以编程方式添加新术语
排查Vale术语警告问题

Quick Commands

快速命令

bash

undefined

bash

undefined

Manual sync to Vale

bun ~/.claude/tools/bin/glossary-sync.ts

Check for duplicates/conflicts across projects (invokes terminology-sync hook)

bun ~/eon/cc-skills/plugins/itp-hooks/hooks/posttooluse-terminology-sync.ts <<< '{"tool_name":"Edit","tool_input":{"file_path":"/tmp/test-CLAUDE.md"}}'

undefined

bun ~/eon/cc-skills/plugins/itp-hooks/hooks/posttooluse-terminology-sync.ts <<< '{"tool_name":"Edit","tool_input":{"file_path":"/tmp/test-CLAUDE.md"}}'

undefined

Architecture

架构

┌─────────────────────────────────────────────────────────────────┐
│                    GLOSSARY.md (SSoT)                           │
│                ~/.claude/docs/GLOSSARY.md                       │
└─────────────────────────┬───────────────────────────────────────┘
                          │
          ┌───────────────┼───────────────┐
          │               │               │
          ▼               ▼               ▼
┌─────────────────┐ ┌───────────┐ ┌────────────────────┐
│ accept.txt      │ │ Term.yml  │ │ Project CLAUDE.md  │
│ (Vale vocab)    │ │ (subs)    │ │ (bidirectional)    │
└─────────────────┘ └───────────┘ └────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│                    GLOSSARY.md (SSoT)                           │
│                ~/.claude/docs/GLOSSARY.md                       │
└─────────────────────────┬───────────────────────────────────────┘
                          │
          ┌───────────────┼───────────────┐
          │               │               │
          ▼               ▼               ▼
┌─────────────────┐ ┌───────────┐ ┌────────────────────┐
│ accept.txt      │ │ Term.yml  │ │ Project CLAUDE.md  │
│ (Vale vocab)    │ │ (subs)    │ │ (bidirectional)    │
└─────────────────┘ └───────────┘ └────────────────────┘

SCAN_PATHS Configuration

SCAN_PATHS 配置

The terminology sync hook uses

SCAN_PATHS

to discover project CLAUDE.md files. This is configured via an HTML comment in GLOSSARY.md:

markdown

<!-- SCAN_PATHS:
- ~/eon/*/CLAUDE.md
- ~/eon/*/*/CLAUDE.md
- ~/.claude/docs/GLOSSARY.md
-->

Format rules:

Must be an HTML comment starting with
```
<!-- SCAN_PATHS:
```
Each path on its own line with
```
-
```
prefix
Supports glob patterns (
```
*
```
,
```
**
```
)
Paths are relative to home directory (
```
~
```
)

Default paths (if not specified):

```
~/eon/*/CLAUDE.md
```
- Top-level project CLAUDE.md files
```
~/eon/*/*/CLAUDE.md
```
- Package-level CLAUDE.md files

术语同步钩子使用

SCAN_PATHS

来发现项目CLAUDE.md文件。该配置通过GLOSSARY.md中的HTML注释进行设置：

markdown

<!-- SCAN_PATHS:
- ~/eon/*/CLAUDE.md
- ~/eon/*/*/CLAUDE.md
- ~/.claude/docs/GLOSSARY.md
-->

格式规则:

必须是以
```
<!-- SCAN_PATHS:
```
开头的HTML注释
每个路径单独一行，以
```
-
```
作为前缀
支持通配符模式（
```
*
```
,
```
**
```
）
路径相对于主目录（
```
~
```
）

默认路径（未指定时）:

```
~/eon/*/CLAUDE.md
```
- 顶级项目CLAUDE.md文件
```
~/eon/*/*/CLAUDE.md
```
- 包级CLAUDE.md文件

Table Schema (5 Columns)

表格结构（5列）

Every term in GLOSSARY.md follows this 5-column format:

Column	Required	Description	Example
Term	Yes	Bold term name ( `Term` )	`Time-Weighted Sharpe`
Acronym	Yes	Abbreviation (or `-` if none)	`TWSR`
Definition	Yes	Clear, concise definition	`Sharpe ratio for range bars`
Unit/Range	Yes	Measurement unit or valid range	`ratio` , `[0, 1]` , `-`
Projects	Yes	Comma-separated project names	`alpha-forge, trading-fitness`

Example row:

markdown

| **Time-Weighted Sharpe** | TWSR | Sharpe ratio for variable-duration bars using time weights | annualized ratio | alpha-forge |

GLOSSARY.md中的每个术语都遵循以下5列格式：

列名	是否必填	描述	示例
术语	是	加粗的术语名称（ `术语` ）	`Time-Weighted Sharpe`
缩写	是	缩写形式（无则填 `-` ）	`TWSR`
定义	是	清晰、简洁的定义	`Sharpe ratio for range bars`
单位/范围	是	计量单位或有效范围	`ratio` , `[0, 1]` , `-`
项目	是	逗号分隔的项目名称	`alpha-forge, trading-fitness`

示例行:

markdown

| **Time-Weighted Sharpe** | TWSR | Sharpe ratio for range bars | ratio      | alpha-forge |

Automatic Sync (Hooks)

自动同步（钩子）

Two PostToolUse hooks handle automatic sync:

Hook	Trigger	Action
`posttooluse-glossary-sync`	Edit `~/.claude/docs/GLOSSARY.md`	Sync to Vale vocabulary
`posttooluse-terminology-sync`	Edit project `CLAUDE.md`	Merge terms → GLOSSARY.md, detect conflicts

两个PostToolUse钩子负责处理自动同步：

钩子名称	触发条件	操作
`posttooluse-glossary-sync`	编辑 `~/.claude/docs/GLOSSARY.md`	同步到Vale词汇表
`posttooluse-terminology-sync`	编辑项目 `CLAUDE.md`	合并术语到GLOSSARY.md，检测冲突

Manual Operations

手动操作

Sync Glossary to Vale

将词汇表同步到Vale

When automatic sync fails or you need to force a refresh:

bash

bun ~/.claude/tools/bin/glossary-sync.ts

Output:

=== Glossary Bidirectional Sync ===
  Source: /Users/you/.claude/docs/GLOSSARY.md
  Found 25 acronyms, 24 substitutions
  Updated: .vale/styles/config/vocabularies/TradingFitness/accept.txt
  Total terms: 27
  Updated: .vale/styles/TradingFitness/Terminology.yml
  Substitution rules: 24
  Updated timestamp: 2026-01-22T00:00:00Z
=== Sync Complete ===

当自动同步失败或需要强制刷新时：

bash

bun ~/.claude/tools/bin/glossary-sync.ts

输出:

=== Glossary Bidirectional Sync ===
  Source: /Users/you/.claude/docs/GLOSSARY.md
  Found 25 acronyms, 24 substitutions
  Updated: .vale/styles/config/vocabularies/TradingFitness/accept.txt
  Total terms: 27
  Updated: .vale/styles/TradingFitness/Terminology.yml
  Substitution rules: 24
  Updated timestamp: 2026-01-22T00:00:00Z
=== Sync Complete ===

Validate Glossary Format

验证词汇表格式

Check that GLOSSARY.md follows the correct table format:

bash

undefined

检查GLOSSARY.md是否遵循正确的表格格式：

bash

undefined

Check required columns

grep -E '^| **[^|]+** |' ~/.claude/docs/GLOSSARY.md | head -5

Verify table structure (should have | Term | Acronym | Definition | Unit/Range | Projects |)

head -25 ~/.claude/docs/GLOSSARY.md


**Expected format**:

```markdown
| Term                     | Acronym | Definition                  | Unit/Range | Projects    |
| ------------------------ | ------- | --------------------------- | ---------- | ----------- |
| **Time-Weighted Sharpe** | TWSR    | Sharpe ratio for range bars | ratio      | alpha-forge |

head -25 ~/.claude/docs/GLOSSARY.md


**预期格式**:

```markdown
| Term                     | Acronym | Definition                  | Unit/Range | Projects    |
| ------------------------ | ------- | --------------------------- | ---------- | ----------- |
| **Time-Weighted Sharpe** | TWSR    | Sharpe ratio for range bars | ratio      | alpha-forge |

Check for Duplicates

检查重复项

Scan all project CLAUDE.md files for terminology conflicts:

bash

undefined

扫描所有项目CLAUDE.md文件以查找术语冲突：

bash

undefined

Full duplicate check (scans ~/eon/*/CLAUDE.md)

bun ~/eon/cc-skills/plugins/itp-hooks/hooks/posttooluse-terminology-sync.ts <<< '{"tool_name":"Edit","tool_input":{"file_path":"/tmp/test-CLAUDE.md"}}'


**Conflict types detected**:

- **Definition conflict**: Same term, different definitions
- **Acronym conflict**: Same term, different acronyms
- **Acronym collision**: Same acronym used for different terms

bun ~/eon/cc-skills/plugins/itp-hooks/hooks/posttooluse-terminology-sync.ts <<< '{"tool_name":"Edit","tool_input":{"file_path":"/tmp/test-CLAUDE.md"}}'


**检测到的冲突类型**:

- **定义冲突**: 同一术语，不同定义
- **缩写冲突**: 同一术语，不同缩写
- **缩写碰撞**: 同一缩写用于不同术语

Add New Term

添加新术语

To add a new term to the glossary:

Edit GLOSSARY.md directly:

markdown

| **New Term** | NT | Definition of the new term | - | project-name |

Sync will auto-trigger via
```
posttooluse-glossary-sync
```
hook

Verify Vale recognizes it:

bash

echo "The NT is important" | vale --config=~/.claude/.vale.ini

要向词汇表添加新术语：

直接编辑GLOSSARY.md:

markdown

| **New Term** | NT | Definition of the new term | - | project-name |

同步将自动触发 通过
```
posttooluse-glossary-sync
```
钩子

验证Vale是否识别该术语:

bash

echo "The NT is important" | vale --config=~/.claude/.vale.ini

Vale Integration

Vale 集成

Files Generated

生成的文件

File	Purpose
`~/.claude/.vale/styles/config/vocabularies/TradingFitness/accept.txt`	Accepted terms (won't be flagged)
`~/.claude/.vale/styles/TradingFitness/Terminology.yml`	Substitution rules (suggests canonical form)

文件路径	用途
`~/.claude/.vale/styles/config/vocabularies/TradingFitness/accept.txt`	已接受术语（不会被标记）
`~/.claude/.vale/styles/TradingFitness/Terminology.yml`	替换规则（建议标准形式）

Running Vale

运行Vale

bash

undefined

bash

undefined

Check a single file (run from file's directory for glob patterns to match)

cd ~~/eon/trading-fitness && vale --config=~~/.claude/.vale.ini CLAUDE.md

Check all CLAUDE.md files

find ~~/eon -name "CLAUDE.md" -exec sh -c 'cd "$(dirname "$1")" && vale --config=~~/.claude/.vale.ini "$(basename "$1")"' _ {} ;


**Important**: Vale glob patterns in `.vale.ini` (like `[CLAUDE.md]`) are relative to cwd. Always run Vale from the file's directory or use absolute paths with matching glob patterns.

find ~~/eon -name "CLAUDE.md" -exec sh -c 'cd "$(dirname "$1")" && vale --config=~~/.claude/.vale.ini "$(basename "$1")"' _ {} ;


**重要提示**: `.vale.ini`中的Vale通配符模式（如`[CLAUDE.md]`）是相对于当前工作目录的。请始终从文件所在目录运行Vale，或使用与通配符模式匹配的绝对路径。

Troubleshooting

故障排查

Terms Not Being Recognized

术语未被识别

Check sync timestamp:

bash

grep "Last Sync" ~/.claude/docs/GLOSSARY.md

Force manual sync:

bash

bun ~/.claude/tools/bin/glossary-sync.ts

Verify Vale config path:

bash

cat ~/.claude/.vale.ini | grep StylesPath

检查同步时间戳:

bash

grep "Last Sync" ~/.claude/docs/GLOSSARY.md

强制手动同步:

bash

bun ~/.claude/tools/bin/glossary-sync.ts

验证Vale配置路径:

bash

cat ~/.claude/.vale.ini | grep StylesPath

Hook Not Triggering

钩子未触发

Check hook is registered:

bash

grep "glossary-sync" ~/.claude/settings.json

Verify hook file exists:

bash

ls -la ~/.claude/plugins/marketplaces/cc-skills/plugins/itp-hooks/hooks/posttooluse-glossary-sync.ts

检查钩子是否已注册:

bash

grep "glossary-sync" ~/.claude/settings.json

验证钩子文件是否存在:

bash

ls -la ~/.claude/plugins/marketplaces/cc-skills/plugins/itp-hooks/hooks/posttooluse-glossary-sync.ts

Vale Output Shows "0 files" But File Exists

Vale输出显示“0 files”但文件存在

This happens when Vale's glob patterns don't match the file path. The

posttooluse-vale-claude-md.ts

hook handles this by:

Walking up from the file's directory to find
```
.vale.ini
```
Changing to the file's directory before running Vale
Stripping ANSI escape codes for reliable output parsing

If running Vale manually, ensure you're in the file's directory:

bash

undefined

当Vale的通配符模式与文件路径不匹配时会出现此问题。

posttooluse-vale-claude-md.ts

钩子通过以下方式处理此问题：

从文件目录向上查找
```
.vale.ini
```
运行Vale前切换到文件所在目录
去除ANSI转义码以确保输出解析可靠

如果手动运行Vale，请确保先进入文件所在目录：

bash

undefined

Wrong - may show "0 files"

错误示例 - 可能显示“0 files”

vale --config=/path/to/.vale.ini /absolute/path/to/CLAUDE.md

Correct - cd first

正确示例 - 先切换目录

cd /absolute/path/to && vale --config=/path/to/.vale.ini CLAUDE.md

undefined

cd /absolute/path/to && vale --config=/path/to/.vale.ini CLAUDE.md

undefined

Duplicate Vocabulary Directories

重复的词汇表目录

If you see Vale inconsistencies:

bash

undefined

如果Vale出现不一致问题：

bash

undefined

Check for duplicate vocab dirs (should only have config/vocabularies/)

检查重复的词汇表目录（应仅存在config/vocabularies/）

ls -la ~/.claude/.vale/styles/

Remove any stale Vocab/ directory

删除任何过期的Vocab/目录

rm -rf ~/.claude/.vale/styles/Vocab/

undefined

rm -rf ~/.claude/.vale/styles/Vocab/

undefined

References

参考资料

Vale Documentation
GLOSSARY.md:
```
~/.claude/docs/GLOSSARY.md
```
(local file)
itp-hooks CLAUDE.md

Vale 文档
GLOSSARY.md:
```
~/.claude/docs/GLOSSARY.md
```
（本地文件）
itp-hooks CLAUDE.md