/mindmap

name: mindmap
user-invocable: true
description: Generate an interactive Markmap mindmap from a file, a URL, pasted text, or a topic.
allowed-tools: Bash, Read, Write, Glob, WebFetch

Mindmap Skill — Generate an Interactive Markmap

Trigger

`/mindmap <input> [--panel] [--render] [--output <path>]`

`<input>` is one of:

• a **file path** — read the file and map it
• a **URL** (`http://` or `https://`) — fetch the page and map its content
• **pasted text / notes** — map the text directly
• a short **topic** — generate a map from your own knowledge

Flags:

• `--panel` — design the structure with a multi-agent judge panel (token-intensive; best for complex/important sources like papers). See **Step 2 → Judge Panel**.
• `--render` — after writing the `.md`, also produce a standalone interactive `.html`
• `--output <path>` — write the `.md` to this path instead of the default

> **Cross-harness note:** This skill uses Claude Code tool names (`Read`, `Write`, `Glob`, `Bash`, `WebFetch`). On **GitHub Copilot CLI**, use the equivalents (`view`, `create`, `glob`, `bash`, `web_fetch`) — see [`references/copilot-tools.md`](references/copilot-tools.md). The workflow itself is identical on both.

Workflow

Step 1: Resolve the input

Strip the flags, then classify what remains and load the content:

1. If it is a **URL** (starts with `http://` or `https://`), fetch it with **WebFetch** (ask it to return the page's main text content). The fetched content is the content. Check this **first**, before the file/text/topic rules. 2. Else if it is the path of an **existing file**, Read it. That is the content. 3. Else if it is **long or multi-line prose** (roughly > 12 words, or contains line breaks), treat it as **raw text**. That is the content. 4. Else treat it as a **topic**: generate the content from your own knowledge.

Stop and ask the user (never silently guess) when:

• A **URL fetch fails** (network error, blocked, or empty page) → report it and ask: map the page's topic from your own knowledge instead, or try a different URL? Do not invent page content.
• It **looks like a file path** (ends in `.md`/`.txt`, or contains `/` or `\`) but the file **does not exist** → report `no file at <path>` and ask: map it as a topic instead, or fix the path?
• It is **empty or whitespace only** → ask for content or a topic.
• It is genuinely **ambiguous** (a short phrase that could be raw text or a topic) → default to **topic generation** and say so in one line so the user can correct you.

Step 2: Build the structure (hybrid)

Turn the content into a node hierarchy:

• If the content is **already structured** (clear headings / a bullet outline): follow that outline, but **condense each node to a short phrase** (≤ ~8 words). Do not copy sentences verbatim.
• If the content is **unstructured** prose or a **topic**: extract the key concepts and group them into **4–7 main branches**, each with concise sub-points.

Rules:

• **Depth:** aim for 3–4 levels.
• **Phrases, not sentences:** every node is a short label.
• **Legibility over completeness:** for a very large source, map its structure and key points — not every line. Target **4–7 main branches** for unstructured/topic/large sources; when the source is already structured, mirror its own outline instead. Condense aggressively.

Judge Panel (only with `--panel`)

When `--panel` is passed, do not build the structure single-handed. Instead run a multi-agent panel via the **Workflow** tool, using the prompts in [`references/judge-panel.md`](references/judge-panel.md):

1. **Propose** — 3 proposer agents each design a full structure through a different lens (narrative-first, data-first, audience-first), assigning every node a **format** (list/table/code/checkbox/link/bold) and a **tier** (`core` renders everywhere; `rich` = table/code/checkbox, standard-markmap only). 2. **Judge** — 3 judge agents independently score all proposals on the rubric (skill rules + presentation: punchline-first, headline numbers, leaf legibility, visual balance, format fit) and name each proposal's best idea. 3. **Synthesize** — 1 synthesizer agent takes the top-scored proposal as the spine, grafts the judges' flagged ideas, and emits the final Markmap `.md`.

Use the Workflow skeleton and the exact prompts/schemas in the reference file. Cost note: this spawns ~7 agents and is token-intensive — reserve it for complex or high-stakes sources. If all proposers fail, fall back to the normal Step 2 single-pass build and tell the user.

**Render-tier safety:** the synthesizer keeps `rich` formats — they render on the default `.md` path (markmap.js.org / VS Code ext / `--render`). The vertical **poster** path (`scripts/parse-md.mjs`) reads only `##` headings and `-` bullets, so before sending a panel `.md` down the poster path, pass it through `scripts/degrade-rich.mjs` (`node scripts/degrade-rich.mjs <in.md> <out.md>`), which rewrites tables/code/checkboxes as bullets. Content is reshaped, **never silently dropped**.

Step 3: Write the Markmap `.md`

Write a file in the exact shape shown under **Markmap Format** below.

Output path:

• File input `foo.md` → `foo.mindmap.md` (same directory).
• URL input → slug of the page title (or the URL's last path segment) → `<slug>.mindmap.md` in the current directory.
• Raw-text input → slug of the map's H1 title → `<slug>.mindmap.md` in the current directory (same slug rule as topic).
• Topic input → `<topic-slug>.mindmap.md` in the current directory (slug = lowercase, spaces → `-`).
• `--output <path>` overrides the default and is written as given.
• **Before writing, use Glob to check whether the target already exists.** If it does, insert a counter before `.mindmap.md` — `<name>-2.mindmap.md`, then `<name>-3.mindmap.md`, … — and use the first name that is free. The same suffixing applies to an explicit `--output` path. **Never overwrite an existing file silently.**

After writing, tell the user the exact path an