Skip to content

About

Agent Skills: LaTeX notes to an offline dependency map, handwritten lecture PDFs to LaTeX, behind fail-closed gates.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

math-notes-agent-skills

CI License: MIT Live demo

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-mindmap turns 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-latex is 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).

The thesis mind map: the Quantum neural networks chapter opened, the spectral theorem selected, and its statement, labelled reconstructed proof outline, trap and dependency reasons in the reading pane

Why the work is split

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
Loading

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
Loading

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.

A page in the house style: coloured boxes per result type, explicit numbering, title block without a legend

Results

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-thesis and 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:test cases, run in CI with the fixture pipeline (no model needed): numbering rules (starred sections, chapters, \numberwithin, explicit 1.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-latex are read directly by latex-mindmap's inventory (tested against the house-style preamble).

Reading view: the cheat sheet with pre-rendered formulas

Install

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

handwritten-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/*.skill

Then ask, for example: "Make a mind map of notes.tex" or "Type up lecture3.pdf, my GoodNotes export, as LaTeX".

Run it locally (no model needed)

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

Repository layout

skills/
  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/

Limitations

  • 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.py is regex-based: environments must start on their own line, split documents must be flattened first, macros defined in .sty files 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-mindmap needs the npm registry once, for npm 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-latex depends 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.

Credits and license

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.

Denys Shkola · GitHub · LinkedIn

About

Agent Skills: LaTeX notes to an offline dependency map, handwritten lecture PDFs to LaTeX, behind fail-closed gates.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages