AI & Harness

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.

mermaid-cliMAC (keyed)keyedMAC gone, no errormermaid-cli["MAC (keyed)"]MAC (keyed)as written

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.

Markdown
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)"].

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