glossary-management_skill

This skill helps you manage terminology across projects by syncing glossary with Vale, validating structure, and adding terms programmatically.

TypeScript

14

GitHub Stars

1

Bundled Files

2 months ago

Catalog Refreshed

4 months ago

First Indexed

Readme & install

Copy the install command, review bundled files from the catalogue, and read any extended description pulled from the listing source.

Installation

Preview and clipboard use veilstrat where the catalogue uses aiagentskills.

npx veilstrat add skill terrylica/cc-skills --skill glossary-management

SKILL.md9.0 KB

Overview

This skill manages a single source of truth terminology glossary (~/.claude/docs/GLOSSARY.md) and automates its integration with Vale. It provides validation, duplicate/conflict detection, programmatic term additions, and sync tools to keep Vale vocabularies and substitution rules up to date. The goal is consistent terminology across projects and reliable linting results from Vale.

How this skill works

The skill scans a configured set of project CLAUDE.md files (via SCAN_PATHS in the glossary) and merges project terms into the central GLOSSARY.md. It validates the glossary table schema (5 required columns), detects definition/acronym conflicts and collisions, and generates Vale files (accept.txt and Terminology.yml) via a sync script. Hooks run post-edit to auto-sync; manual commands are available for forced sync, validation, and Vale checks.

When to use it

When adding or updating terms and you need them reflected in Vale vocabularies
When validating GLOSSARY.md format or checking for missing columns
When scanning projects for duplicate or conflicting terminology
When Vale shows unexpected warnings or reports 0 files due to glob issues
When programmatically adding terms to keep a consistent SSoT

Best practices

Keep GLOSSARY.md as the Single Source of Truth and edit it directly for canonical changes
Follow the 5-column table schema: Term, Acronym, Definition, Unit/Range, Projects
Configure SCAN_PATHS as an HTML comment at the top of GLOSSARY.md to control discovery
Run the glossary-sync script after edits if automatic hooks fail
Always run Vale from the file’s directory so configured glob patterns match

Example use cases

Force-sync glossary to Vale after bulk edits: run glossary-sync to update accept.txt and Terminology.yml
Validate a new CLAUDE.md contribution across projects to detect acronym collisions before merging
Add a new term programmatically then trigger posttooluse-glossary-sync to propagate it to Vale
Debug Vale reporting 0 files by confirming .vale.ini location and running Vale from the project directory
Scan ~/eon projects to merge local terms into the central glossary and surface definition conflicts

FAQ

Run the glossary-sync script (bun ~/.claude/tools/bin/glossary-sync.ts) to regenerate Vale files and update timestamps.

What causes Vale to report 0 files even though the file exists?

Vale glob patterns are relative to the current working directory; cd into the file’s directory or use matching globs in .vale.ini so files are discovered correctly.