glossary-generator

What this skill does

# Glossary Generator

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)

| Component | Tokens | Notes |
|-----------|--------|-------|
| Agent overhead (system prompt + tools) | ~12K | Paid once for serial, 4× for parallel |
| Definition generation (350 terms) | ~19K | Unavoidable LLM work |
| Assembly (Python script) | ~700 | Trivial programming task |
| **Total (serial)** | **~31K** | |

**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:

| Glossary size | Estimated total tokens |
|---------------|----------------------|
| 100 terms | ~17K (12K overhead + 5.4K generation) |
| 200 terms | ~23K |
| 350 terms | ~31K (measured) |
| 500 terms | ~39K |

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

| Approach | Agent overhead | Generation | Assembly | Total | Waste |
|----------|---------------|------------|----------|-------|-------|
| **1 serial agent (recommended)** | ~12K (once) | ~19K | ~700 | **~31K** | — |
| 4 parallel agents + script | ~48K (4×) | ~19K | ~700 | **~68K** | +37K (119%) |
| 4 parallel agents + manual Edit | ~48K (4×) | ~19K | ~200K | **~267K** | +236K (761%) |

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":

```markdown
#### Learning Graph

A directed graph of concepts that reflects the order that concepts should be learned to master a new concept.

L