concept-map

Turn a topic string or source text into a legible graph that shows structure at a glance. Default output is Mermaid syntax (renders in GitHub, Notion, Obsidian, and Claude Code with zero install) plus a PNG/SVG when a renderer is available.

When to trigger

Activate on any phrasing that asks to visualize relationships between ideas. Examples:

Student phrasings

• "mind map of the french revolution"
• "concept map for photosynthesis"
• "show me how these ideas relate"
• "visualize this chapter as a graph"
• "map my notes on cell biology"
• "I need a mind map to study for my exam"

Teacher phrasings

• "diagram of this chapter for my 7th graders"
• "prerequisite tree for calculus"
• "cause and effect map of WWI"
• "draw a taxonomy of vertebrates"
• "flowchart the scientific method"
• "timeline of the civil rights movement"
• "markmap of my unit notes"

Anti-triggers — DO NOT invoke

• "write me a summary of X" → plain prose, not a graph.
• "give me a flowchart for this React component" → code-diagramming, out of scope.
• "draw a picture of a cell" → labeled illustration, not a concept graph.

Inputs

• Topic string (required OR source) — "the French Revolution", "photosynthesis", "derivatives".
• Source text (required OR topic) — pasted chapter, notes, or article paragraphs.
• Graph type (optional) — tree, concept-map, flow, timeline, mindmap. Inferred if omitted (see table below).
• Format (optional) — mermaid (default), dot, markmap, or all.
• Grade / level (optional) — K-2, 3-5, 6-8, 9-12, college, grad. Drives node count + vocabulary.
• Max nodes (optional) — integer, default 20, hard cap 50.
• Render (optional, default true) — auto-invoke scripts/render.py to produce PNG/SVG.

Inferring graph type from phrasing (before asking)

Pick the graph type from the user's wording — do NOT ask unless both topic and format are absent.

If both topic AND format are missing, ask ONE clarifying question in this exact shape:

Quick check — what topic, and which flavor? (e.g. mind map of the French Revolution · concept map for photosynthesis · prerequisite tree for calculus · timeline of WWII)

Do not stack questions. Once the user answers, proceed straight to generation.

Grade / level calibration

Vocabulary tracks level: K-2 uses common words, grad uses domain-precise terms.

Workflow

1. Parse the request — extract topic OR source, graph type, format, grade.
2. Infer graph type from the table above if not specified. Default format is Mermaid.
3. Extract 10-30 candidate key concepts. Respect max-nodes.
4. Cluster related concepts; pick the root / central concept.
5. Draft relationships. For concept maps, label every edge with a verb or preposition ("causes", "is-a", "requires", "leads to"). See references/novak-concept-maps.md.
6. Emit syntax — write the chosen format to disk (concept-map.mmd by default).
7. Render — if render: true, invoke scripts/render.py --input concept-map.mmd --output concept-map.png. Script falls back to install hints if the CLI is missing; the syntax file is always preserved.
8. Summarize — return root concept, node count, edge count, and file paths.

Locked defaults

Micro-example

User: "concept map for photosynthesis, 7th grade"

Inferred: grade 7, concept map with labeled edges, Mermaid graph TD, ~10 nodes.

graph TD
  P[Photosynthesis] -->|"needs"| L[Light energy]
  P -->|"needs"| W[Water]
  P -->|"needs"| C[CO₂]
  P -->|"happens in"| CH[Chloroplasts]
  P -->|"produces"| G[Glucose]
  P -->|"produces"| O[Oxygen]
  CH -->|"contain"| CL[Chlorophyll]
  CL -->|"absorbs"| L

6 core nodes + 2 supporting nodes, every edge labeled, root is the central concept. Emit the raw Mermaid above as concept-map.mmd, then run scripts/render.py for a PNG.

Rendering

Run the bundled script from the skill root:

python3 scripts/render.py --input concept-map.mmd --output concept-map.png

Dispatch by file extension:

• .mmd / .mermaid → mmdc (Mermaid CLI)
• .dot / .gv → dot (Graphviz)
• .md → markmap-cli (Markmap)

If the required CLI is missing, render.py exits 0 (non-fatal), prints platform-specific install commands, and points at https://mermaid.live/edit as a zero-install fallback. The syntax file is always preserved.

References (load on demand)

• references/graph-type-guide.md — decision tree for picking tree / concept-map / flow / timeline / mindmap.
• references/mermaid-cheatsheet.md — graph TD, flowchart LR, mindmap, timeline, node shapes, edge labels, subgraphs, styling.
• references/dot-cheatsheet.md — DOT syntax, digraph, rankdir, clusters, dot/neato/fdp layouts.
• references/markmap-syntax.md — Markdown-heading-driven mind maps, frontmatter options.
• references/novak-concept-maps.md — Novak & Cañas theory: propositions (concept-link-concept), focus questions, cross-links, hierarchical layout.
• references/node-labeling.md — label length, noun-nodes / verb-edges, reading-level calibration.

Load a reference only when its topic is active — never preload.

Quality bar

Every generated graph must satisfy:

• Syntax parses in its target renderer (no Mermaid parse errors, valid DOT, valid Markmap).
• Root / central concept is unambiguous and matches the user's topic.
• Node count matches the grade calibration (±20%).
• For concept maps at grades 6+, every edge carries a verb or preposition label.
• Labels are ≤ 3 words where possible; nouns for nodes, verbs for edges.
• No hallucinated concepts when a source text is provided — each node maps to a substring or close paraphrase in the source.
• Rendered image is non-empty OR install hints are surfaced with a zero-install fallback URL.

What NOT to do

• Do not emit a graph with > 50 nodes — cluster lowest-importance concepts into parent groups and report what was collapsed.
• Do not leave edges unlabeled in concept maps for grades 6+.
• Do not silently pick one direction when source text supports both (A causes B and B causes A) — emit both with distinct labels.
• Do not fail hard when renderers are missing — always fall back gracefully and keep the syntax file.
• Do not ask more than one clarifying question.