Visual notes (sketchnote-style cheat sheets)

You write the content as a JSON spec; the bundled renderer produces the look and the PDF. Never hand-write HTML. Your tokens go into the explanation, not the formatting.

Token rules (the skill must stay cheap for free-tier users)

1. This file is enough. Do not open references/ or examples/ unless a block's fields are unclear or the user asks for a variant you have not used (then read only that file, once).
2. Read sources in slices. If the source is already visible in the conversation (uploaded PDF, pasted text), use it as is; never re-read it from disk. If it is only on disk (a file path), run source_outline.py first, then extract only the pages the note needs. Never cat a whole PDF or long file.
3. Write the spec once, with a file tool, and do not repeat its content in chat.
4. Never open a rendered file. Do not view the HTML/PDF/PNG. The renderer's --estimate output and its exit status are the check.
5. One render call, --pdf-only. Multi-page notes are one spec with pages, rendered once.
6. Reply in one or two lines: what the note covers and where it is. The PDF is the deliverable; do not restate it.
7. No helper scripts, no browser. Never write your own measuring, screenshot or PDF scripts, and never drive a browser to check the output: render_note.py already measures, fits, prints and verifies the page count. If it fails, report its error in one line and deliver the HTML it left behind. A long spec (a series of pages) may be generated by a short Python script to avoid typing repeated structure; keep such scripts in <dir>/.work/ and delete that folder before delivering. Deliverables are exactly <name>.pdf and <name>.spec.json.

Workflow

1. Plan (in your head, not in chat): topic type (recipe below), audience level, 8–11 blocks for one page. More than that → pages, never a cramped sheet.
2. Sources on disk only: python3 <skill-dir>/scripts/source_outline.py doc.pdf (outline, ~500 tokens) → --pages a-b or --grep term for the parts you need (--lines a-b for text files).
3. Write <dir>/<name>.spec.json (skeleton and block table below).
4. Render: python3 <skill-dir>/scripts/render_note.py <dir>/<name>.spec.json <dir>/<name>.html --pdf-only Prints estimated page heights; stops on a page that cannot fit one A4 sheet (>1400 px at 800 px wide) and warns above 1300 px or on code lines that will wrap. Fix the spec, re-run. Produces <name>.pdf; the HTML is removed. On a Mac or Windows machine it uses headless Chrome/Edge with a fresh profile (safe while Chrome is open) and measures the real page heights; on Linux it prefers wkhtmltopdf. If neither exists, the HTML is kept and delivered instead. To check without rendering: --estimate.
5. Deliver the PDF, attached the way your environment shares files (e.g. present_files on claude.ai). One or two sentences.

Output location: keep the generated files in a directory named after the requested output name (attention-notes/attention-notes.pdf). When several files or resources are given as input, choose a directory name from the domain topic and keep everything inside it. Never write into the skill folder. <skill-dir> is the folder containing this SKILL.md (the path your agent lists for visual-notes; in Claude Code also ${CLAUDE_SKILL_DIR}).

Spec skeleton

{"title": "PYTHON LISTS", "subtitle": "Ordered, mutable, everything", "variant": "whiteboard", "accent": "purple",
 "rows": [
  {"cols": [[{"type": "bullets", "n": 1, "title": "What it is", "color": "green", "items": ["**Ordered** collection", "==Mutable==: change in place"]}],
            [{"type": "code", "n": 2, "title": "Create", "lang": "python", "color": "blue", "code": "nums = [1, 2, 3]\nnums.append(4)"}]]},
  {"cols": [[{"type": "table", "n": 3, "title": "Operations", "head": ["Op", "Syntax", "Result"], "rows": [["Slice", "`a[1:3]`", "[2, 3]"]]}]]},
  {"cols": [[{"type": "callout", "kind": "warning", "title": "Watch out", "text": "`a = b` copies the reference, not the list."}],
            [{"type": "revision", "title": "Quick revision points", "groups": [["Ordered, mutable"], ["Slices copy; `=` does not"]]}]]}
 ],
 "footer": {"left": "optional", "right": "optional"}}

rows → each row has cols → each column is a list of blocks; one column = full width. Multi-page: top-level pages: [{title, subtitle, rows, page}, ...] sharing variant/accent. Variants: whiteboard (clean, concept notes) or notebook (lined paper, spiral, brand, stickies, title_highlight). Accents: purple, blue, green, pink, orange, teal, navy. Block n is the running number in reading order; color sets the border (green = definitions/checks, blue = mechanisms/code, purple = concepts, pink = comparisons/revision, orange = warnings/tips, red = errors); alternate colors between neighbouring blocks.

Inline markup in any text: **bold**, ==highlight==, `code`, {red:word}, [text](url), -> → arrow.

Block types

Balance the two columns (≈20 px per bullet line, 27 px per table row, 17 px per code line, 45 px per block heading). Code ≤ 50 chars per line in a half column, ≤ 104 full width.

Recipes

• Concept (attention, RAG, backprop): flow → what-it-is bullets + analogy → key terms kv → mechanism numbered + formula → micro-example table → think → confusions compare → questions → revision.
• Syntax / reference (Python lists, kubectl): definition checks → code → operations table → methods chips/kv → indexstrip if indexing → warning → compare → memory → revision.
• Tool / system (Docker, MCP): what & why → concepts kv → architecture flow/stack → commands chips → one real config code → tips → comparison table → revision.
• Roadmap note (the 10-part layout): concept + why it matters | key ideas → table | code → analogy callout | common mistakes → interview questions | resource kv + hands-on key callout → revision.
• Interview prep: 4 questions groups + answer keys kv + a remember sticky.

Content rules

• One idea per line, 13–15 words at most; start with the noun or verb that matters; ==highlight== the one term to remember.
• Every page has one concrete example (code or table), one analogy or memory trick, one thing that goes wrong, and a revision strip.
• Numbers, commands and outputs live in tables or code, never in prose. Interview questions read as an interviewer would ask them.
• Accuracy over decoration: omit uncertain facts; label illustrative numbers "(illus.)". No copied branding.

Files (read only when needed)

• scripts/render_note.py (renderer; Python 3 only; PDF via wkhtmltopdf or headless Chrome/Edge), scripts/source_outline.py (cheap reading of PDFs/text).
• references/spec-schema.md every field with examples; references/style-guide.md the look in detail; references/content-rules.md writing rules and QA list; examples/*.json two finished specs.