Mermaid mind maps from slides, and parentheses that eat text
The other study skills in my network security course repo (Study Skills) mostly answer in chat. mind-map is the one that draws. It outputs Mermaid, which renders on GitHub and in VS Code’s Markdown preview (with a Mermaid extension) and diffs as plain text.
Most of the skill is choosing the right diagram. A mindmap is for “what’s in this chapter”. A protocol or an attack, with messages going between sender, receiver and attacker, is almost always a sequenceDiagram. A process or a decision is a flowchart. The map itself is built from the slides: slide titles become the 5 to 8 main branches, each node is a term or a short phrase in the slides’ wording, and nothing goes in that the slides don’t cover unless it’s marked as extra.
What a test render showed
The skill warns that parentheses, quotes and colons in node text break the mindmap parser, and says to wrap such text in ["..."]. The cases went through mermaid-cli 11.12.0 while I was writing this.
Parentheses don’t break the parser. They parse as a node shape, with no error. This renders without an error, and the first node reads “keyed”:
mindmap
root((Hashing))
MAC (keyed)
Note: no key
MAC (keyed) became a rounded node labelled keyed, and the word MAC was gone. The colon in the second node rendered fine. Wrapped, both come out as written:
mindmap
root((Hashing))
a["MAC (keyed)"]
b["Note: no key"]
Square brackets do the same: MAC [keyed] also renders as keyed. The wrapped form works without an id too, as ["MAC (keyed)"]. So the rule holds for parentheses and brackets, for a quieter reason than the skill gives, and colons are fine in this version. Quotes weren’t tested. One of the skill’s output rules covers all of it: if you haven’t rendered it, say the render is unchecked.
Save it as .claude/skills/mind-map/SKILL.md and change the slide path to yours. In the copy below the syntax note is corrected from the test, the render rule asks for an actual render with mmdc, and two small lines are cut.
- name
- mind-map
- description
- Use when the user asks for a mind map, concept map, overview diagram or flow diagram of a lecture, chapter or topic. Produces Mermaid (mindmap, flowchart, sequence) that renders on GitHub and in VS Code, saved as a .md file next to the slides when asked.
Mind maps and diagrams
Mermaid in a fenced block. It renders on GitHub and in VS Code's Markdown preview (with the Mermaid extension), needs no build step, and diffs cleanly.
Pick the diagram type
| What you're showing | Use |
|---|---|
| A chapter or topic broken into parts | mindmap |
| A process, a decision, how data flows | flowchart LR or TD |
| Messages between sender, receiver, attacker | sequenceDiagram |
| How concepts depend on or differ from each other | flowchart with labelled edges |
Protocols and attacks are almost always better as a sequenceDiagram than a mind map. Use a
mind map for "what is in this chapter" and for revision.
Build it from the slides
- Read the slides:
pdftotext -layout Lectures/<chapter>/slides.pdf -. Slide titles are the main branches. - 5 to 8 main branches, 2 to 5 children each, 3 levels deep at most. If it needs more, split into two maps.
- Node text is short: a term or a 2 to 4 word phrase, not a sentence. The explanation goes in chat, not in the node.
- Use the slides' wording for terms so the map matches the exam.
- Don't add a branch the slides don't cover unless it is marked as extra.
Mermaid syntax that works
Mindmap is indentation based. The root is one node. Parentheses and square brackets in node
text parse as node shapes and silently swallow words (MAC (keyed) renders as keyed, no
error), so quote such text: ["MAC (keyed)"].
mindmap
root((Message Authentication))
Goals
Source is who it claims
Not altered
Sequencing
Timeliness
Functions
Message encryption
MAC
Hash function
Digital signature
Adds non-repudiation
Sequence diagram for a protocol:
sequenceDiagram
participant A as Sender
participant B as Receiver
A->>B: M, MAC(K, M)
B->>B: recompute MAC(K, M) and compare
Output
- In chat by default: show the block and a two-line walk-through of how to read it.
- When asked to save:
Lectures/<chapter>/mindmap.mdwith a title line and the block(s). - Render it before saying it renders:
npx -p @mermaid-js/mermaid-cli mmdc -i map.mmd -o map.svg, then read the text in the SVG. If you can't, say the render is unchecked.
Don't
- Make decorative maps with 40 nodes.
- Add colors or styling unless asked.
---
name: mind-map
description: Use when the user asks for a mind map, concept map, overview diagram or flow diagram of a lecture, chapter or topic. Produces Mermaid (mindmap, flowchart, sequence) that renders on GitHub and in VS Code, saved as a .md file next to the slides when asked.
---
# Mind maps and diagrams
Mermaid in a fenced block. It renders on GitHub and in VS Code's Markdown preview (with the
Mermaid extension), needs no build step, and diffs cleanly.
## Pick the diagram type
| What you're showing | Use |
|---|---|
| A chapter or topic broken into parts | `mindmap` |
| A process, a decision, how data flows | `flowchart LR` or `TD` |
| Messages between sender, receiver, attacker | `sequenceDiagram` |
| How concepts depend on or differ from each other | `flowchart` with labelled edges |
Protocols and attacks are almost always better as a `sequenceDiagram` than a mind map. Use a
mind map for "what is in this chapter" and for revision.
## Build it from the slides
1. Read the slides: `pdftotext -layout Lectures/<chapter>/slides.pdf -`. Slide titles are the
main branches.
2. 5 to 8 main branches, 2 to 5 children each, 3 levels deep at most. If it needs more, split
into two maps.
3. Node text is short: a term or a 2 to 4 word phrase, not a sentence. The explanation goes
in chat, not in the node.
4. Use the slides' wording for terms so the map matches the exam.
5. Don't add a branch the slides don't cover unless it is marked as extra.
## Mermaid syntax that works
Mindmap is indentation based. The root is one node. Parentheses and square brackets in node
text parse as node shapes and silently swallow words (`MAC (keyed)` renders as `keyed`, no
error), so quote such text: `["MAC (keyed)"]`.
```mermaid
mindmap
root((Message Authentication))
Goals
Source is who it claims
Not altered
Sequencing
Timeliness
Functions
Message encryption
MAC
Hash function
Digital signature
Adds non-repudiation
```
Sequence diagram for a protocol:
```mermaid
sequenceDiagram
participant A as Sender
participant B as Receiver
A->>B: M, MAC(K, M)
B->>B: recompute MAC(K, M) and compare
```
## Output
- In chat by default: show the block and a two-line walk-through of how to read it.
- When asked to save: `Lectures/<chapter>/mindmap.md` with a title line and the block(s).
- Render it before saying it renders:
`npx -p @mermaid-js/mermaid-cli mmdc -i map.mmd -o map.svg`, then read the text in the SVG.
If you can't, say the render is unchecked.
## Don't
- Make decorative maps with 40 nodes.
- Add colors or styling unless asked.
see also: Study Skills