Two Agent Skills for Claude that turn mathematical notes into study material without letting a language model quietly get the bookkeeping wrong. (Agent Skills are folders of instructions and scripts that Claude loads when a task calls for them.)
latex-mindmapturns LaTeX notes, a textbook or a thesis into one offline HTML file: every numbered definition, theorem, lemma and example as a node in a dependency map, each edge carrying a written reason, with statements, board-ready proof outlines and a searchable cheat sheet.handwritten-notes-to-latexis built to transcribe handwritten lecture PDFs (GoodNotes, Notability, scans) into a LaTeX document that matches them one to one — same numbering, titles, statements and proofs — in a fixed house style.
Live demo: a mind map of my BSc thesis
(18 numbered results, built from the sources in examples/bsc-thesis;
the thesis's sources are in its bibliography at the end of thesis.tex).
A model that has read a section can write a precise statement, the key steps of a proof and why one result needs another. It is unreliable at the mechanical parts: matching the numbering of the PDF, covering every item, producing LaTeX that renders, and admitting when a proof is not in the source. Those failures don't crash anything; they produce a document that looks finished and is wrong.
So each skill gives the mechanical work to deterministic scripts and puts fail-closed gates between the model's steps. The model only does the editorial part: reading and writing mathematics.
flowchart LR
classDef llm fill:#efe7fb,stroke:#7a5bc7,color:#2d1f52
classDef gate fill:#fdeceb,stroke:#c0504d,color:#4a1514
classDef det fill:#e8f1fb,stroke:#3b78c2,color:#10294a
classDef data fill:#f4f4f5,stroke:#8b8b93,color:#27272a
F["flatten.py<br/>(split documents)"]:::det --> I["inventory.py<br/>items, PDF numbering, macros"]:::det
I --> P{{"user agrees size<br/>and chapters"}}:::data
P --> X1["extraction agent<br/>chapter 1"]:::llm
P --> X2["extraction agent<br/>chapter 2"]:::llm
P --> X3["… one per chapter,<br/>in parallel"]:::llm
X1 & X2 & X3 --> M["merge.js<br/>validation gate"]:::gate
M -->|graph.json| B["build.js + tex.js + layout.js<br/>render gate"]:::gate
B -->|mindmap.html| A["audit.js<br/>headless smoke test"]:::gate
Blue: deterministic script. Purple: model step. Red: gate that stops the run. Grey: user decision or data.
| Gate | Refuses to continue on |
|---|---|
merge.js |
an item in the notes with no entry, an entry not in the notes, duplicate ids, dangling edges, an edge without a written reason, dependency cycles, unbalanced $ / braces / \left-\right, a bare <, LaTeX or more than 24 characters in a map label |
build.js |
any formula MathJax cannot render, naming the undefined macros and writing no map (MathJax's noerrors/noundefined packages are removed so nothing renders as red text) |
audit.js |
external network references, unresolved glyphs, a result without a bubble, and broken open / hover / select / search / reading-view / reset interactions (jsdom) |
Proof provenance is part of the output: where the source gives no proof, a reconstructed proof or theorem outline is shown under an amber "reconstructed (not in the notes)" label rather than passed off as the source's own. Outlines on definitions, remarks and examples are titled "Board outline", never "Proof outline".
flowchart LR
classDef llm fill:#efe7fb,stroke:#7a5bc7,color:#2d1f52
classDef gate fill:#fdeceb,stroke:#c0504d,color:#4a1514
classDef det fill:#e8f1fb,stroke:#3b78c2,color:#10294a
classDef data fill:#f4f4f5,stroke:#8b8b93,color:#27272a
PG["pages.py<br/>PDF to page tiles"]:::det --> R["read pages<br/>(vision)"]:::llm
R --> L[("ledger.json<br/>one line per item")]:::data
R --> W["write LaTeX<br/>house style"]:::llm
W --> C["re-read the images<br/>against the LaTeX"]:::llm
C --> S["audit.py structure<br/>duplicates, order, gaps,<br/>undeclared environments"]:::gate
L --> V["audit.py coverage<br/>ledger vs .tex"]:::gate
C --> V
S & V --> BS["build.sh<br/>pdflatex + error triage"]:::gate
handwritten-notes-to-latex instructs the model never to read a PDF's OCR
text layer: pages.py renders the pages (tiled for dense "infinite paper"
pages) for a vision model. The instructions also require the lecturer's
numbering verbatim (\begin{thmN}{1.1.4a}), a page ledger kept while reading,
and \warn{} on illegible words instead of a guess; the scripts then audit
the numbering and the ledger coverage.
Everything below is reproducible from this repository.
- Live demo — my BSc thesis (University of Vienna, 2026): 18 numbered
results, 27 dependency edges each with a written reason, 4 chapters, one
0.39 MB HTML file with no external requests; the headless audit passes
all 17 checks. CI rebuilds the page from
examples/bsc-thesisand fails if it differs by a byte from the committed one. The thesis PDF and its code are in qnn-financial-forecasting. - Tests — 46 pytest and 23
node:testcases, run in CI with the fixture pipeline (no model needed): numbering rules (starred sections, chapters,\numberwithin, explicit1.1.4a-style numbers), every refusal of the validation gate, the render gate, provenance labels, HTML escaping, the structure and coverage audits, page tiling and reproducible packaging. - Composable — notes typeset by
handwritten-notes-to-latexare read directly bylatex-mindmap's inventory (tested against the house-style preamble).
Claude Code — copy the skill folders and install the pinned npm packages (Node.js 20.19+, 22.13+ or 24+):
git clone https://github.com/AlphaShk/math-notes-agent-skills.git
cd math-notes-agent-skills
mkdir -p ~/.claude/skills
cp -R skills/* ~/.claude/skills/
npm ci --prefix ~/.claude/skills/latex-mindmap # mathjax-full 3.2.2, jsdom 29.1.1handwritten-notes-to-latex renders pages with pypdfium2 and Pillow, pinned in
its requirements.txt (Python 3.10+). Install them into the Python that runs
the skill's scripts, ideally a virtual environment: Homebrew and Debian Pythons
refuse a global pip install. Without them pages.py falls back to poppler's
pdftoppm. Building the PDF also needs pdflatex with tcolorbox, titlesec,
mathpazo and microtype (any full TeX Live or MiKTeX).
claude.ai — build the archives and upload each .skill file as a custom
skill (every CI run also builds them, as the skills artifact):
python3 -m venv .venv && . .venv/bin/activate && pip install -r requirements-dev.txt # Python 3.10+, includes PyYAML
python tools/package_skills.py # validates both skills, writes dist/*.skillThen ask, for example: "Make a mind map of notes.tex" or "Type up lecture3.pdf, my GoodNotes export, as LaTeX".
From the repository root:
npm ci --prefix skills/latex-mindmap
python3 -m venv .venv && . .venv/bin/activate && pip install -r requirements-dev.txt # Python 3.10+
bash tools/run_fixture.sh # inventory -> merge -> build -> audit on the test fixture
bash tools/build_demo.sh # rebuild docs/demo/index.html from examples/bsc-thesis
bash tools/build_house_style.sh # compile the house-style sample (needs pdflatex)
python -m pytest && node --test tests/*.test.jsskills/
latex-mindmap/ SKILL.md, scripts/ (Python + Node), references/, package.json + lock
handwritten-notes-to-latex/ SKILL.md, scripts/, assets/ (house style), references/, requirements.txt
examples/
bsc-thesis/ flattened thesis + chapters.json + extract/*.json behind the live demo
house-style/ sample document for the LaTeX house style
tests/
fixtures/thesis-mini/ 8-result thesis excerpt with committed extraction (CI fixture)
test_*.py, mindmap.test.js pytest and node:test suites
tools/ fixture runner, demo and sample builders, .skill packager
docs/ GitHub Pages: demo/index.html, img/
- The gates check structure, not mathematics. A statement can be transcribed wrongly or an edge reason can be weak and still pass; reconstructed proofs are labelled, not verified.
inventory.pyis regex-based: environments must start on their own line, split documents must be flattened first, macros defined in.styfiles are not harvested (pass--macros), and[subsection]counters and appendix lettering are not modelled.- MathJax renders most LaTeX maths but not TikZ: diagrams inside a result (the thesis's quantum circuits, for instance) are described in words.
- Maps grow with the number of distinct formulas, because each is pre-rendered to SVG: the 8-result test fixture (65 formulas) is 0.21 MB, the 18-result demo (131 formulas) 0.39 MB, and a full course is many times larger. The layout is computed at build time and the audit cannot judge it visually.
latex-mindmapneeds the npm registry once, fornpm ci. On claude.ai that depends on the network settings for code execution; the Claude API's skills container has no network access, so the map cannot be built there.handwritten-notes-to-latexdepends on the vision model's reading of the handwriting. Its audits catch lost, duplicated and misnumbered items; the re-read pass against the page images is a process step, not a tool. The repository has no public before/after sample of handwriting yet; the house-style image is typeset from the thesis.- The demo is small: a thesis with 18 results and no proofs of its own.
The code is MIT-licensed — see LICENSE. The thesis text in
examples/ and the material built from it (tests/fixtures/thesis-mini/,
docs/demo/, docs/img/) are © 2026 Denys Shkola, included as demo input and
not covered by the MIT licence; the works cited in the thesis remain with their
authors. Maps embed SVG glyphs generated by MathJax
(Apache-2.0); the smoke test uses jsdom
(MIT). Details in THIRD_PARTY_NOTICES.md.


