Skip to main content
skill CX Codex

glossary-management — Claude Code skill: glossary and setup

glossary-management is a Claude Code skill that maintains a terminology glossary and connects it to Vale. It runs for glossary edits, term additions, validation, and sync requests.

MIT 138 installs ★ 3 updated 2026-10-25

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add terrylica/cc-skills --skill glossary-management -a claude-code
Open on GitHub

What glossary-management does

The skill manages a shared terminology file at ~/.claude/docs/GLOSSARY.md, checks its table structure, and syncs terms with Vale. Each table row has fields for the term, acronym, definition, unit or range, and project names.

A PostToolUse hook syncs Vale vocabulary after edits to the glossary. Another hook watches project CLAUDE.md files, merges their terms into the shared glossary, and detects definition or acronym conflicts. Manual sync runs with bun ~/.claude/tools/bin/glossary-sync.ts, so Bun is needed for that command. Project scan locations go in the glossary’s SCAN_PATHS comment.

What it helps with

  • sync glossary terms to Vale
  • check glossary rows against the required table structure
  • find conflicting definitions or acronyms across projects
  • add a term to the shared glossary

Example prompts for the agent

  • Sync the glossary with Vale.
  • Check project terminology for duplicates and conflicts.
  • Add a new term to the shared glossary.

How to install glossary-management

1Skills CLI (Vercel)

npx skills add terrylica/cc-skills --skill glossary-management -a claude-code

2Manually: put the files in place

~/.claude/skills/glossary-management/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/glossary-management/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about glossary-management

How do I install glossary-management in Claude Code?

Run npx skills add terrylica/cc-skills --skill glossary-management -a claude-code. The skill file is at ~/.claude/skills/glossary-management/SKILL.md.

What does glossary-management do?

It manages the shared glossary at ~/.claude/docs/GLOSSARY.md, syncs terms with Vale, and checks project CLAUDE.md files for terminology conflicts.

How does glossary-management update Vale?

A hook syncs Vale vocabulary when the shared glossary is edited. To run the sync manually, use bun ~/.claude/tools/bin/glossary-sync.ts.

Source text

SKILL.md · MIT
---
name: glossary-management
description: Manage terminology glossary with Vale. TRIGGERS - sync terms, glossary validation, add terms, Vale vocabulary.
allowed-tools: Bash, Read, Edit, Grep
---

# Glossary Management

> **Self-Evolving Skill**: This skill improves through use. If instructions are wrong, parameters drifted, or a workaround was needed — fix this file immediately, don't defer. Only update for real, reproducible issues.

## 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.

## 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

## Quick Commands

```bash
# 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"}}'
```

## Architecture

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

## SCAN_PATHS Configuration

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

## Table Schema (5 Columns)

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   | `research-repo, trading-fitness` |

**Example row**:

```markdown
| **Time-Weighted Sharpe** | TWSR | Sharpe ratio for variable-duration bars using time weights | annualized ratio | research-repo |
```

## 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 |

## Manual Operations

### Sync Glossary to 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 ===
```

### Validate Glossary Format

Check that GLOSSARY.md follows the correct table format:

```bash
# 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      | research-repo |
```

### Check for Duplicates

Scan all project CLAUDE.md files for terminology conflicts:

```bash
# 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

### Add New Term

To add a new term to the glossary:

1. **Edit GLOSSARY.md directly**:

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

2. **Sync will auto-trigger** via `posttooluse-glossary-sync` hook

3. **Verify Vale recognizes it**:

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

## Vale Integration

### 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) |

### Running Vale

```bash
# 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.

## Troubleshooting

### Terms Not Being Recognized

1. **Check sync timestamp**:

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

2. **Force manual sync**:

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

3. **Verify Vale config path**:

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

### Hook Not Triggering

1. **Check hook is registered**:

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

2. **Verify hook file exists**:

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

### Vale Output Shows "0 files" But File Exists

This happens when Vale's glob patterns don't match the file path. The `posttooluse-vale-claude-md.ts` hook handles this by:

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

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

```bash
# Wrong - may show "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
```

### Duplicate Vocabulary Directories

If you see Vale inconsistencies:

```bash
# Check for duplicate vocab dirs (should only have config/vocabularies/)
ls -la ~/.claude/.vale/styles/

# Remove any stale Vocab/ directory
rm -rf ~/.claude/.vale/styles/Vocab/
```

## References

- [Vale Documentation](https://vale.sh/docs/)
- GLOSSARY.md: `~/.claude/docs/GLOSSARY.md` (local file)
- [itp-hooks CLAUDE.md](/plugins/itp-hooks/CLAUDE.md)

## Post-Execution Reflection

After this skill completes, check before closing:

1. **Did the command succeed?** — If not, fix the instruction or error table that caused the failure.
2. **Did parameters or output change?** — If the underlying tool's interface drifted, update Usage examples and Parameters table to match.
3. **Was a workaround needed?** — If you had to improvise (different flags, extra steps), update this SKILL.md so the next invocation doesn't need the same workaround.

Only update if the issue is real and reproducible — not speculative.

© terrylica · MIT · terrylica/cc-skills

Similar skills

All skills for Writing and docs →

From the same set79

The whole set →
adr-code-traceability The adr-code-traceability skill links code to Architecture Decision Records with file headers or inline comments. Use it when an implementation choice needs a clear connection to its decision record. CX Codex +1 144installs mlflow-python mlflow-python is a Claude Code skill for logging backtest parameters and metrics in MLflow, searching experiment runs, and retrieving metric history via the Python API. CX Codex +1 139installs code-clone-assistant code-clone-assistant detects duplicate code using PMD CPD and Semgrep, guides refactoring of DRY violations. Catches both exact clones and similar patterns. CX Codex +1 139installs article-extractor article-extractor downloads technical articles and documentation from mql5.com for reference or training datasets. Useful for collecting MQL5 code examples by URL or author. CX Codex +1 138installs gmail-access The gmail-access skill connects the agent to a Gmail command-line client so it can pull messages, search a mailbox, save what it finds and stage drafts. Handy when the thread you need sits next to the code you are working on. CX Codex +1 137installs skill-architecture skill-architecture guides skill creation and updates, YAML structure checks, and common troubleshooting. Task templates help you choose a workflow before editing files. CX Codex +1 137installs slash-command-factory slash-command-factory generates Claude Code slash command Markdown files with YAML frontmatter through a question workflow or ten presets. CX Codex +1 136installs backtesting-py-oracle backtesting-py-oracle configures backtesting.py to match ClickHouse SQL sweep results on range bars. Fixes trade count mismatches and timing discrepancies in multi-position testing. CX Codex +1 135installs

Project sponsors

Companies that keep this analytics open