Skip to content

rgglez/rgglez-dev-skills / plugins/quiz-from-glossary/skills/quiz-from-glossary

quiz-from-glossary

Verified

Use when asked to create a quiz, test, assessment, or practice questions from a glossary, term list, or vocabulary of definitions, with output as JSON or TypeScript QuizQuestion data (single choice, multiple choice, true/false).

Quiz from glossary

Generate a quiz whose questions, correct answers, distractors, and explanations come from the glossary alone. The glossary is the only source of truth: the quiz tests what the glossary says, not what the agent knows about the topic.

1. Settle the inputs

  • Glossary: a file or pasted text. Accept any layout (Markdown list or table, definition list, headings, CSV, JSON, YAML).
  • Output format: json or ts. If the request does not state it, ask the user before generating. Do not pick one silently.
  • Number of questions: use the requested count. Otherwise use 10, or the number of glossary terms if smaller.
  • Destination: use the requested path. Otherwise, when the glossary is a file, write <glossary-basename>.quiz.json or .quiz.ts beside it; when it was pasted, return the quiz in the reply.

2. Parse the glossary into entries

Build a list of entries { term, definition, section, related }:

  • section: the heading or category under which the term appears. If the glossary has no sections, use its title; if it has no title, a short topic name written in the glossary's language.
  • related: terms the glossary itself links to the entry ("see also", "compare", "opposite of", "not to be confused with", synonyms).

Detect the quiz language from the definitions (term names are often English loanwords). Write every human-readable value in that language: section, prompt, option text, explanation, and the true/false labels. Keep JSON keys, kind values, and ids in English as the schema defines them.

3. Rules for content

  • Only glossary terms. Every question targets one glossary term. Every term that appears in a prompt, option, or explanation is a glossary term.
  • Answers strictly from the glossary. An option's text is a term name or a definition copied from the glossary. Allowed edits: drop a trailing period, shorten a definition to its defining clause, and mask the target term where it appears inside its own definition (replace it with ___). Never add facts, examples, numbers, or qualifications the glossary does not state.
  • Plausible distractors. Wrong options are other glossary entries close to the target, ranked in this order:
    1. If a retrieval tool is available (RAG, vector store, semantic search, an embeddings index over the glossary or its source material), query it with the target's definition and take the most similar glossary terms. Retrieval only ranks candidates; distractor text still comes from the glossary.
    2. Terms listed in the target's related.
    3. Terms in the same section.
    4. Terms whose definitions share key words or the same category ("a technique", "a phenomenon", "a protocol").
    5. Neighbors in glossary order.
  • Distractors are unambiguously wrong. Exclude synonyms and aliases of the target, and any entry whose definition would also satisfy the prompt. Never use invented, absurd, joke, or off-topic options, and never "all/none of the above".

4. Question kinds and patterns

Mix the three kinds at random, roughly evenly unless the user asks for a distribution. If you can run code, use a random generator to choose each question's kind and to shuffle option order; otherwise vary the position of the correct option so it follows no pattern. Target each term at most once until every term has been used.

kindPatternOptions
singleDefinition → term: "Which term matches this definition: «…»?"4 term names, 1 correct
singleTerm → definition: "What is «term»?"4 definitions, 1 correct
multi"Select the pairs that match the glossary."4–5 term: definition pairs, 2+ correct, 1+ swapped
multiWhen a definition enumerates several properties, parts, or examples: "Which of these belong to «term»?"listed items of the target (correct) plus items listed in adjacent entries (wrong)
boolean"True or false: «term» is ."exactly 2: true and false, 1 correct

Build a false boolean statement or a wrong multi pair by pairing a term with an adjacent term's definition. Do not negate, exaggerate, or rewrite a definition to make it false: a swapped definition is still glossary text.

Small glossaries: single needs 3+ entries, multi 4+. With fewer, use the kinds the glossary supports and say so in the report.

5. Fill the fields

  • id: q1, q2, … unique within the quiz (or the user's prefix).
  • section: the entry's section.
  • prompt: the question, in the glossary's language.
  • options[].id: a, b, c, … unique within the question; for boolean use true and false, with text in the glossary's language ("Verdadero"/"Falso", "Vrai"/"Faux", …).
  • explanation: why the correct answer(s) are correct, citing the glossary definition, and for swapped options which term that definition really belongs to. Glossary content only.

6. Write the output

Always build the quiz as JSON first and validate it (step 7). Then:

  • JSON: a top-level array of objects that each validate against assets/quiz.schema.json. 2-space indent, UTF-8.

  • TypeScript: the same data as a typed array.

    import type { QuizQuestion } from "./types";
    
    export const quiz: QuizQuestion[] = [
      // validated JSON objects
    ];
    

    If the project already defines QuizQuestion (search for it), import from that module. Otherwise copy assets/types.ts beside the output as types.ts. Follow the project's export-name convention if it has one; otherwise use quiz.

7. Validate

  1. Run the validator on the JSON (for TypeScript output, on the intermediate JSON in a temporary location):

    node <skill-dir>/scripts/validate-quiz.mjs quiz.json
    

    It checks the schema plus per-kind rules: single has 3+ options and exactly 1 correct; multi has 4+ options, 2+ correct, and 1+ wrong; boolean has exactly 2 options and 1 correct; ids and option texts are unique. Fix every reported error and rerun. If Node.js is unavailable, check the same rules by hand.

  2. Review each question against the glossary: the correct answer traces to the target's entry; each distractor is a glossary entry, plausible, and wrong; the prompt does not give away the answer; no two questions are duplicates.

Report the destination, the count per kind, and any terms skipped and why.

Example

Glossary (Spanish, section "Aprendizaje automático"):

  • Sobreajuste: Situación en la que un modelo aprende el ruido de los datos de entrenamiento y generaliza mal a datos nuevos.
  • Subajuste: Situación en la que un modelo es demasiado simple para capturar la estructura de los datos de entrenamiento.
  • Regularización: Técnica que penaliza la complejidad de un modelo para reducir el sobreajuste.
  • Validación cruzada: Técnica que estima el rendimiento de un modelo entrenándolo y evaluándolo en particiones distintas de los datos.
[
  {
    "id": "q1",
    "section": "Aprendizaje automático",
    "kind": "single",
    "prompt": "¿Qué término corresponde a esta definición: «Técnica que penaliza la complejidad de un modelo para reducir el sobreajuste»?",
    "options": [
      { "id": "a", "text": "Validación cruzada", "correct": false },
      { "id": "b", "text": "Subajuste", "correct": false },
      { "id": "c", "text": "Regularización", "correct": true },
      { "id": "d", "text": "Sobreajuste", "correct": false }
    ],
    "explanation": "Según el glosario, la regularización es la técnica que penaliza la complejidad de un modelo para reducir el sobreajuste. La validación cruzada también es una técnica, pero estima el rendimiento del modelo."
  },
  {
    "id": "q2",
    "section": "Aprendizaje automático",
    "kind": "multi",
    "prompt": "Selecciona los pares término–definición que coinciden con el glosario.",
    "options": [
      { "id": "a", "text": "Subajuste: técnica que penaliza la complejidad de un modelo para reducir el sobreajuste", "correct": false },
      { "id": "b", "text": "Sobreajuste: situación en la que un modelo aprende el ruido de los datos de entrenamiento y generaliza mal a datos nuevos", "correct": true },
      { "id": "c", "text": "Regularización: situación en la que un modelo es demasiado simple para capturar la estructura de los datos de entrenamiento", "correct": false },
      { "id": "d", "text": "Validación cruzada: técnica que estima el rendimiento de un modelo entrenándolo y evaluándolo en particiones distintas de los datos", "correct": true }
    ],
    "explanation": "Las definiciones de sobreajuste y validación cruzada coinciden con el glosario. La opción a describe la regularización y la opción c describe el subajuste."
  },
  {
    "id": "q3",
    "section": "Aprendizaje automático",
    "kind": "boolean",
    "prompt": "Verdadero o falso: el subajuste es la situación en la que un modelo aprende el ruido de los datos de entrenamiento y generaliza mal a datos nuevos.",
    "options": [
      { "id": "true", "text": "Verdadero", "correct": false },
      { "id": "false", "text": "Falso", "correct": true }
    ],
    "explanation": "Falso. Esa es la definición de sobreajuste. Según el glosario, el subajuste ocurre cuando un modelo es demasiado simple para capturar la estructura de los datos de entrenamiento."
  }
]

Common mistakes

MistakeFix
Distractor from general knowledge ("Gradient descent") not in the glossaryUse the adjacency ranking in step 3
False statement made by negating or inventing a factSwap in an adjacent term's definition
Explanation adds context the glossary lacksCite only the glossary definitions
Prompt or labels in English for a Spanish glossaryWrite all human-readable text in the glossary's language
Correct option always first, or kinds in a fixed rotationRandomize kinds and option order
Synonym of the target used as a distractorExclude aliases and entries whose definition also fits
Output format chosen without askingAsk json or ts when the request does not say
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 198kUpdated Claude CodeCodexVerifiedInstall