dmccreary/claude-skills/glossary-generator

Glossary Generator

Version: 1.0

Generate a comprehensive glossary of terms from a learning graph's concept list with ISO 11179-compliant definitions.

TOKEN EFFICIENCY WARNING

This skill generates large files (2,000+ lines). Token cost matters far more than wall-clock time for teacher users on limited budgets.

Default approach: ONE serial Task agent that writes all definitions directly to a temp file. This is the most token-efficient method because:

• System prompt / tool description overhead is paid only once (~12K tokens)
• No coordination or assembly overhead
• Proven to complete a 350-term glossary in ~31K tokens (2026-03-14 benchmark)

Measured Token Economics (350-term benchmark, 2026-03-14)

Tokens per term: ~88 total, ~54 marginal (after subtracting one-time overhead).

The marginal cost is calculated as: (30,788 − 12,000) / 350 = ~54 tokens/term. Use this to estimate costs for glossaries of any size:

Why Parallel Execution Should NEVER Be Used

Each parallel agent pays the full ~12K system prompt overhead independently. For glossary generation, the definitions are completely independent — there is no speedup benefit that justifies the cost. The serial agent writes all terms in a single Write call and finishes in ~6 minutes, which is perfectly acceptable.

Parallel execution more than doubles the token cost for zero quality benefit. For teachers on the Claude Pro plan (~200K token five-hour budget), the serial approach uses ~16% of their budget vs. 34% (parallel) or 100%+ (manual assembly).

NEVER use parallel agents for glossary generation. The token waste is not justified.

Always use the serial approach. Do not offer parallel as an option.

The assembly step (sorting and writing the final file) MUST always use a Python script — NEVER manually emit glossary content through Edit/Write tool calls. See logs/glossary-generation-very-inefficient.md for the full post-mortem.

Purpose

This skill automates glossary creation for intelligent textbooks by converting concept labels from a learning graph into properly formatted glossary definitions. Each definition follows ISO 11179 metadata registry standards: precise, concise, distinct, non-circular, and free of business rules. The skill ensures consistency across terminology, validates cross-references, and produces alphabetically ordered entries with relevant examples.

Following a short definition you may provide a discussion of why the term is important in the textbook and an example of how the term is used.

When to Use This Skill

Use this skill after the Learning Graph skill has completed and the concept list has been finalized. All markdown content in the /docs area can also be scanned looking for words or phases that might not be clear to the average high-school student.

The glossary relies on having a complete, reviewed list of concepts from the learning graph's concept enumeration phase. Specifically, trigger this skill when:

• A concept list file exists (typically docs/learning-graph/02-concept-list-v1.md)
• The concept list has been reviewed and approved
• The course description exists with clear learning outcomes
• Ready to create or update the textbook's glossary

Workflow

Step 1: Validate Input Quality

Before generating definitions, assess the quality of the concept list:

1. Read the concept list file (typically docs/learning-graph/02-concept-list-v1.md)
2. Check for duplicate concept labels (target: 100% unique)
3. Verify Title Case formatting (target: 95%+ compliance)
4. Validate length constraints (target: 98% under 32 characters)
5. Assess concept clarity (no ambiguous terms)

Calculate a quality score (1-100 scale):

• 90-100: All concepts unique, properly formatted, appropriate length
• 70-89: Most concepts meet standards, minor formatting issues
• 50-69: Some duplicate concepts or formatting inconsistencies
• Below 50: Significant issues requiring manual review

User Dialog Triggers:

• If score < 70: Ask "The concept list has quality issues. Would you like to review and clean it before generating the glossary?"
• If duplicates found: Ask "Found [N] duplicate concepts. Should I remove duplicates automatically or would you like to review?"
• If formatting issues: Ask "Found [N] concepts with formatting issues. Auto-fix?"

Step 2: Read Course Context

Read the course description file (docs/course-description.md) and any other markdonw files in /docs/**/*.md to understand:

• Target audience (for appropriate example complexity)
• Course objectives (for terminology alignment)
• Prerequisites (for background knowledge assumptions)
• Learning outcomes (for context on concept usage)

Step 3: Generate Definitions Using a Single Serial Agent

Default approach (most token-efficient): Launch ONE Task agent that generates all definitions and writes them directly to a single temp file.

Task agent prompt:
"Generate ISO 11179-compliant glossary definitions for the following [N] terms.
Write ALL entries as markdown (#### headers with definitions, examples, and
discussion) to the file /tmp/glossary-raw.md using the Write tool.
Each entry uses #### for the term header. Do not return the content in your
response — just confirm the file was written and report the term count.
 
[Paste the full term list here]
 
[Paste course description context here for audience level]"

The single agent writes all definitions to one file. This pays system-prompt overhead only once (~12K tokens) and avoids all coordination costs. Proven at ~31K tokens for a 350-term glossary (~88 tokens/term total, ~54 tokens/term marginal).

Do NOT use parallel agents for glossary generation. See the TOKEN EFFICIENCY WARNING section above for why parallel execution should never be used — it more than doubles the token cost for zero quality benefit.

For each concept in the list, create a definition that follows ISO 11179 standards:

Precision (25 points): Accurately capture the concept's meaning

• Define the concept specifically in the context of the course
• Use terminology appropriate for the target audience
• Ensure the definition matches how the concept is used in the course

Conciseness (25 points): Keep definitions brief (target: 20-50 words)

• Avoid unnecessary words or explanations
• Get to the core meaning quickly
• Use clear, direct language

Distinctiveness (25 points): Make each definition unique and distinguishable

• Avoid copying definitions from other sources
• Ensure no two definitions are too similar
• Highlight what makes this concept different from related concepts

Non-circularity (25 points): Avoid circular dependencies

• Do not reference undefined terms in definitions
• Do not create circular chains (A depends on B, B depends on A)
• Use simpler, more fundamental terms in definitions

Example Format:

For a concept "Learning Graph":

#### Learning Graph
 
A directed graph of concepts that reflects the order that concepts should be learned to master a new concept.
 
Learning graphs are the foundational data structure use for intelligent textbooks.  They are used to guide
intelligent agents and recommend learning paths for students.
 
**Example:** In a programming course, the learning graph shows that "Variables" must be understood before "Functions," which must be understood before "Recursion."

Step 4: Add Examples (60-80% of terms)

For most concepts (target: 60-80%), include a relevant example:

• Start with "Example:" (no newline after colon)
• Provide a concrete illustration from the course domain
• Keep examples brief (1-2 sentences)
• Ensure examples clarify the concept without adding confusion

Step 5: Add Cross-References

Where appropriate, reference related terms:

• Use "See also:" for related concepts
• Use "Contrast with:" for opposing concepts
• Ensure all cross-referenced terms exist in the glossary
• Keep cross-references to 1-3 per term

Step 6: Assemble Glossary File Using a Python Script

CRITICAL: NEVER manually assemble the glossary through Edit/Write tool calls. Alphabetical sorting and file merging is a trivial programming task. Doing it manually through LLM text generation wastes 100,000+ tokens that cost real money.

MANDATORY APPROACH: Write and execute a Python script via the Bash tool that:

1. Reads the agent output file(s) — /tmp/glossary-raw.md (serial) or /tmp/glossary-part-*.md (parallel)
2. Parses entries by splitting on #### headers
3. Sorts entries alphabetically (case-insensitive) using sorted()
4. Writes the final docs/glossary.md in one pass

Reference script (adapt paths as needed):

#!/usr/bin/env python3
"""Merge glossary parts into a single sorted glossary."""
import glob, os, re
entries = {}
# Support both serial (single file) and parallel (multiple files)
if os.path.exists('/tmp/glossary-raw.md'):
    sources = ['/tmp/glossary-raw.md']
else:
    sources = sorted(glob.glob('/tmp/glossary-part-*.md'))
for path in sources:
    with open(path) as f:
        content = f.read()
    for block in re.split(r'\n(?=#### )', content):
        block = block.strip()
        m = re.match(r'#### (.+)', block)
        if m:
            entries[m.group(1).strip()] = block
sorted_terms = sorted(entries.keys(), key=lambda t: t.lower())
with open('docs/glossary.md', 'w') as out:
    out.write('# Glossary of Terms\n\n')
    for term in sorted_terms:
        out.write(entries[term] + '\n\n')
print(f"Wrote {len(sorted_terms)} terms to docs/glossary.md")

Run this script with python3 /tmp/assemble_glossary.py via the Bash tool. Total cost: ~500 tokens for the script + ~200 tokens for output = ~700 tokens (versus 200,000+ tokens if done manually through Edit calls).

NEVER DO ANY OF THE FOLLOWING:

• Write glossary entries directly through the Write or Edit tool
• Copy-paste subagent output into Edit tool old_string/new_string parameters
• Manually sort terms by emitting them in alphabetical order
• Append sections to the glossary file one at a time through Edit calls

Formatting rules for the assembled file:

• ONLY level-4 headers (`####`) are allowed for glossary terms. Do not use ## section headers, ### subheadings, or any other header level inside the glossary. The only # header in the file is the page title (# Glossary of Terms). Everything else is ####.
• Terms must ONLY be sorted alphabetically (case-insensitive). Never group terms by category, domain, or topic. The glossary is a flat alphabetical list — no section dividers, no category headers, no thematic groupings. Alphabetical order is the only organizational principle.
• Do not put any --- strings in the glossary. They are not needed.
• Use "Example:" for examples (bold, with colon)
• Maintain consistent spacing between entries (one blank line between entries)

Step 7: Generate Quality Report

Create docs/learning-graph/glossary-quality-report.md with: