terrylica/cc-skills

glossary-management

Manage terminology glossary with Vale.

소스 보기

사용 방법

  1. 설치 명령을 복사하고 자신의 에이전트 환경에 설치하기 전에 소스 패키지를 확인하세요.
  2. 필요한 도구, 인증 정보, 지원 환경은 원본 문서에서 확인하세요.
  3. 입력과 원하는 산출물을 설명하고 출처와 결과를 대조하세요.
npx skills add https://github.com/terrylica/cc-skills --skill glossary-management

시작 전 확인

  • 설치에는 모델 구독, API 한도, 파일 접근 권한이 포함되지 않습니다.
  • 별점 수와 설치 수는 활동 지표이며 독립적인 품질·보안 검증이 아닙니다.
원본 Skill 문서

원본 저장소의 제목, 예시, 코드, 표, 링크, 이미지를 유지해 표시합니다.

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:

ColumnRequiredDescriptionExample
TermYesBold term name (**Term**)**Time-Weighted Sharpe**
AcronymYesAbbreviation (or - if none)TWSR
DefinitionYesClear, concise definitionSharpe ratio for range bars
Unit/RangeYesMeasurement unit or valid rangeratio, [0, 1], -
ProjectsYesComma-separated project namesresearch-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:

HookTriggerAction
posttooluse-glossary-syncEdit ~/.claude/docs/GLOSSARY.mdSync to Vale vocabulary
posttooluse-terminology-syncEdit project CLAUDE.mdMerge 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 |
  1. Sync will auto-trigger via posttooluse-glossary-sync hook
  1. Verify Vale recognizes it:
bash
   echo "The NT is important" | vale --config=~/.claude/.vale.ini

Vale Integration

Files Generated

FilePurpose
~/.claude/.vale/styles/config/vocabularies/TradingFitness/accept.txtAccepted terms (won't be flagged)
~/.claude/.vale/styles/TradingFitness/Terminology.ymlSubstitution 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
  1. Force manual sync:
bash
   bun ~/.claude/tools/bin/glossary-sync.ts
  1. 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
  1. 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

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.

같은 저장소의 Skills

더 많은 Skills

모든 Skills
terrylica
커뮤니티

academic-pdf-to-gfm

Convert academic PDF papers to GitHub-renderable GFM markdown with math equations. TRIGGERS - PDF, GitHub markdown, math

1시간 설치 수
1
GitHub Stars
2
업데이트
11월 5일
terrylica
커뮤니티

adr-code-traceability

Add ADR references to code for traceability. TRIGGERS - ADR traceability, code reference, document decision in code.

1시간 설치 수
1
GitHub Stars
2
업데이트
11월 5일
terrylica
커뮤니티

arxiv-source-first-paper-ingest

Read an arXiv paper faithfully by fetching the authors' own LaTeX source instead of OCR-ing the PDF. Extracts every display equation with its label, environment and enclosing proposition, renders each to MathML, and proves usability by compiling each formula with a real TeX engine. Use when you need a paper's formulas exactly — to replicate a method, implement a loss function or custom objective, verify a quoted number, or check a claim against what the authors actually wrote. TRIGGERS - read th

1시간 설치 수
1
GitHub Stars
2
업데이트
11월 5일
terrylica
커뮤니티

azure-provision

Bootstrap Azure automation when interactive az login is blocked by a Conditional Access policy (error 530035, "Device state: Unregistered"). Mints a service principal through the Azure Portal session ONCE — using Microsoft Graph over a captured token, not DOM clicking — then provisions resource groups, Cognitive Services / AI Language / Speech resources and their keys entirely via az/REST, writing key AND endpoint together into the SCS vault. Use when az login fails but the portal works, when mo

1시간 설치 수
1
GitHub Stars
2
업데이트
11월 5일