convez.ai
SkillEscrita & ConteúdoIntermediário
agiacalone

Lecture Materials Assistant

agiacalone/lecture-materials-assistant

Gera materiais educacionais completos a partir de uma fonte Markdown única

Ver no GitHub
InicialPluginScore · de 0 a 100

Skill do Claude Code que transforma uma única fonte Markdown em um conjunto completo de materiais de aula prontos para produção: notas de aula, handouts Cornell, quizzes, slides Slidev, questionários e guias de estudo. Mantém um único documento como fonte de verdade e regenera todos os artefatos automaticamente.

Instalação

$npx convez-ai agiacalone/lecture-materials-assistant

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 6 dias
Versão
—
Issues abertas
5
Contribuidores
1

Casos de uso

  • Preparar materiais de cursos universitários de Ciência da Computação
  • Manter conteúdo educacional atualizado de forma consistente entre múltiplos formatos
  • Automatizar geração de handouts, slides, quizzes e guias de estudo para disciplinas

Veredito

Ferramenta especializada e bem-arquitetada para educadores que lecionam CS em universidades. Resolve um problema real — manter múltiplos artefatos educacionais sincronizados — com abordagem de source-of-truth; requer fluxo Node.js e LaTeX para saída completa.

README

A tradução para o português deste README ainda está na fila.

lecture-materials-assistant

A Claude Code skill and a standalone Node.js generator toolchain that turns one tagged-Markdown lecture source into a full set of production-ready course materials for university CS courses — lecture notes, a student Cornell handout, study questions, a pop quiz, a question bank, a slide deck, a GitHub Classroom assignment README, and reading-list study guides.

Everything is 100% open formats, end to end: Markdown in; Markdown, LaTeX→PDF, and Slidev decks out. No proprietary or binary "source" formats anywhere in the pipeline.

Companion project: lectern is the course-operations counterpart (term lifecycle, gradebook, exam build/verify with per-student serials, GitHub-Actions autograding). This repo produces content; lectern runs the course.


The idea in one minute

You maintain a single source of truth per lecture — <topic>_lecture_main.md — a plain Markdown file with YAML frontmatter and lightweight inline tags. Every other artifact is a projection of that file. Change the source, re-run the generator, and the whole set regenerates consistently.

Two design principles drive the output:

  • Living notes — kept vs. disposable. The _lecture_main.md and the append-only _question_bank.md are kept (you edit them, they persist across semesters). Everything else — handouts, slides, quizzes, study guides — is disposable and regenerated fresh from the source each term. You never hand-edit a PDF.
  • Student materials are intentionally partial. Handouts carry roughly 40% of the slide content and leave key elements blank, so the handout complements attending lecture instead of replacing it. Printed materials use color as a functional navigation cue (each section kind gets its own banner/cue tint), so a page is easy to scan at a glance during a live lecture.

What it generates

Run against the bundled sample (examples/file_systems_abstraction_lecture_main.md):

Artifact--artifactOutputNeeds LaTeX?
Instructor lecture noteslecture-notes.tex → .pdfyes
Cornell student handoutcornell.tex → .pdfyes
Pop quiz + answer keyquiz.tex → .pdf (×2)yes
Study questionsstudy-questions.mdno
Question bank (append-only)bank.mdno
Slide deckslides.md (Slidev)no
GitHub Classroom READMEreadme.mdno
Reading-list companionreading-list.mdno
Consistency auditauditconsole reportno

Printed artifacts (lecture-notes, cornell, quiz) compile to PDF with pdflatex. Pass --no-pdf to emit the .tex and skip compilation if you don't have a LaTeX toolchain installed. The slide deck is Slidev Markdown — preview it live with npm run slides:dev or export with npm run slides:build.

Exams are not generated here. Exams are controlled documents built by lectern's reg-exam-build (per-student serials, register, verify). This toolchain produces the question bank that exam assembly draws from. See the Exam reading-list section for the per-exam study guide, which this repo does produce.


Quick start

git clone https://github.com/agiacalone/lecture-materials-assistant.git
cd lecture-materials-assistant
npm install

# Compile the full set from the bundled sample, skipping PDF compilation:
node generate.js --main examples/file_systems_abstraction_lecture_main.md --no-pdf --out ./out

# Or one artifact at a time:
node generate.js --main examples/file_systems_abstraction_lecture_main.md --artifact slides --out ./out
node generate.js --main examples/file_systems_abstraction_lecture_main.md --artifact cornell --out ./out

See examples/README.md for the per-artifact walkthrough.


The source file: <topic>_lecture_main.md

This is the only file you author. It's ordinary Markdown with three layers of structure that the parser reads:

1. YAML frontmatter — course context the generators need:

---
title: File Systems — Abstraction and Naming
course: CECS 326
topic-slug: file_systems_abstraction
term: sp26
adversarial-thinking: false   # set true for Security courses → adds attacker-mindset questions
---

2. Obsidian-style tags on list items and headings — these mark what each piece is, so the right generator can pick it up:

TagMeaning
#objectivea learning objective
#vocaba vocabulary term (term + definition)
#concepta core idea
#blanka fill-in target on the student handout — must carry [slide:: N]
#slidea slide in the deck — carries a [layout:: …] from the layout enum
#questiona bank/quiz question — typed #type/mc, #type/sa, etc. and #difficulty/1..3
#self-quiza self-check question for the reading-list/study guide

3. Dataview-style inline fields — [key:: value] pairs that attach data to a tagged item, e.g. [slide:: 6] (which slide a blank is answered on), [citation:: Tanenbaum 4.2] (textbook source for a reading list), [answer:: B] (the key for a multiple-choice question), [layout:: two-cols] (slide layout).

The parser validates the source before generating: a #blank without [slide::], a multiple-choice #question without [answer::], an unknown slide layout, or a diagram block missing [alt::] (ADA) all abort with a clear message before any file is written. The full tag taxonomy and validation rules live in references/style-guide.md.


Two ways to use it

As a Claude Code skill (recommended)

Installed as a skill, Claude does the authoring for you: you describe a lecture in plain English, Claude writes or edits the _lecture_main.md to match the style guide, then runs the generator. It does not rewrite the generator code — the checked-in JavaScript is the stable engine; the skill is the interface.

mkdir -p ~/.claude/skills
git clone https://github.com/agiacalone/lecture-materials-assistant.git \
  ~/.claude/skills/lecture-materials-assistant

In your course repo, copy the context template and reference the skill:

cp ~/.claude/skills/lecture-materials-assistant/CLAUDE.md.example ./CLAUDE.md
## Skills
- Use the lecture-materials-assistant skill at
  ~/.claude/skills/lecture-materials-assistant/SKILL.md for all lecture content.

Then just ask:

Generate lecture materials for virtual memory and paging in CECS 326. Cover the virtual address space, page-table translation, the TLB, and thrashing. ~75 minutes.

As a plain CLI

You can author the _lecture_main.md by hand and drive the generator directly — no Claude required. Every artifact is a node generate.js --main <file> --artifact <name> call (see the table above). This is what the Quick start shows.


Generating a question bank

Question banks are topic-wide and append-only — the persistent pool that exam assembly (in lectern) later draws from. The generator reads the existing bank, avoids duplicates, and assigns the next sequence number per question type (m01, m02, … for multiple choice; t01… true/false; s01… short answer; etc.).

node generate.js --main examples/file_systems_abstraction_lecture_main.md --artifact bank --out ./out

Exam reading-list (multi-topic study guide)

A consolidated, per-exam study guide that maps each covered handout's cues to where the answer lives in the assigned reading — the multi-topic companion to the single-topic reading list. Driven by lectern's reg-exam-readinglist, but runnable directly: point it at the _lecture_main.md for every topic the exam covers.

node exam-reading-list-cli.js \
  --exam-name "Midterm 1" --slug midterm_1 \
  --course "CECS 326" --term sp26 \
  --mains examples/file_systems_abstraction_lecture_main.md \
  --out ./out
# → ./out/midterm_1_reading_list.md

Pass several comma-separated --mains to fold multiple topics into one guide (rendered as Part A, Part B, …). Optional --textbook, --citation-key, --note, and --note-title override the source-block defaults (Tanenbaum & Bos for OS courses).


Installing prerequisites

You need Node.js (for all artifacts) and, for the printable PDFs, a LaTeX toolchain with pdflatex on your PATH. The Markdown and Slidev artifacts need neither beyond Node.

PlatformBase toolsLaTeX (for PDFs)
macOSbrew install git nodebrew install --cask mactex-no-gui (or basictex + sudo tlmgr install enumitem listings geometry)
Fedorasudo dnf install -y git nodejs npmsudo dnf install -y texlive-scheme-basic texlive-enumitem texlive-listings texlive-geometry
Ubuntu / Debiansudo apt install -y git nodejs npmsudo apt install -y texlive-latex-base texlive-latex-recommended texlive-latex-extra

On Fedora Atomic (Kinoite/Silverblue), install inside a distrobox container rather than layering onto the immutable host.

Then, once per clone:

npm install

Repository layout

generate.js                 # CLI orchestrator: parse → validate → dispatch → (compile)
exam-reading-list-cli.js    # sub-tool CLI: multi-topic per-exam study guide
parser/
  index.js                  # parse() + validate() entry points
  main-parser.js            # Markdown + tag + inline-field walker
  validators.js             # invariant checks; hard errors block generation
generators/                 # one file per artifact (lecture-notes, cornell-handout,
                            #   study-questions, quiz, question-bank, slides, readme,
                            #   reading-list, exam-reading-list, audit)
lib/                        # shared LaTeX preamble + Cornell palette helpers
themes/                     # Slidev themes (blueprint, terminal)
examples/                   # self-contained sample source + walkthrough
references/
  style-guide.md            # complete style + tag + validation specs — read this
SKILL.md                    # skill metadata + workflow (entry point when used as a skill)
CLAUDE.md.example           # template you copy into your course repo

Tests

npm test           # vitest — parser, validators, and every generator
npm run check      # node --check syntax-validation across the live sources
npm run verify:a11y  # ADA Title II / WCAG contrast audit of the palettes (--level AA|AAA)

Accessibility (ADA Title II / WCAG)

Student-facing materials are built toward WCAG 2.1 AA per the md-monolith design spec. The first stage of the compliance audit chain is live: a palette contrast verifier (lib/a11y/) checks every student/instructor color pair against the WCAG target. generate.js gates on it before emitting any artifact — run npm run verify:a11y standalone, or pass --skip-a11y / --a11y-level AAA to generate.js. The student palette currently passes AA.


License & ownership

MIT.

Materials you generate with this toolchain are yours — they are not required to carry this repository's license unless they copy substantial portions of the repository itself.

Ver o original no GitHub

Bom para

Relacionados