xmind-skills

A small, self-contained blueprint for authoring XMind mind maps as plain text with an AI assistant (Claude Code), keeping everything version-controlled in git.

The core idea: you never edit .xmind binaries. Each map is a .xmindmark text file (a Markdown-like outline) that compiles to .xmind with one command. Text sources diff cleanly in git, and an AI assistant can read, edit, and regenerate them like normal code.

What's in here

Path	What it is
.claude-plugin/	Marketplace + plugin metadata — this repo installs directly into Claude Code (see below)
skills/xmind-builder/	Claude Code skill: builds a new mind map from a topic or outline (knows the syntax, quality patterns, and verification steps)
.claude/xmindmark-workflow.md	The edit → compile → balance → verify loop Claude follows for changes
scripts/build-map.sh	One-command regen: compile → move to output/ → balance
scripts/balance-xmind.py	Mandatory post-compile step — rewrites the layout so branches alternate left/right of the center topic
examples/trip-planning/	Minimal example: root + branches + nesting
examples/product-launch/	Advanced example: boundaries [B], relationships [N]/[^N], summaries [S]
CLAUDE.md	Project instructions so Claude Code follows the workflow automatically in this repo

Setup on a new laptop

1. Install Node.js (any recent LTS) — needed for the xmindmark CLI.

2. Install the xmindmark CLI (lands in your npm prefix, no sudo):

   npm install -g xmindmark
   xmindmark --version

3. Install Python 3 — needed for scripts/balance-xmind.py (stdlib only, no pip packages). The verification snippets also use unzip, which is preinstalled on most systems (apt install unzip on minimal Linux).

4. Install Claude Code — the AI assistant this blueprint is built around:

   npm install -g @anthropic-ai/claude-code
   claude   # first run walks you through login

5. Install the XMind desktop app (optional) — only needed to view the maps or export PDFs. Compilation and verification work without it. Note: XMind has no CLI/headless export — PDF export is a manual GUI action (File → Export → PDF), and on the free plan it may be watermarked. That's why PDFs are optional, manual artifacts here; the .xmind file is the primary output.

6. Clone this repo and try an example (from the repo root):

   ./scripts/build-map.sh examples/trip-planning

   Open examples/trip-planning/output/trip-planning.xmind in XMind — done. (The script runs compile → move to output/ → balance; the manual equivalent of each step is in .claude/xmindmark-workflow.md.)

Using it with Claude Code

This repo is a Claude Code plugin marketplace hosting one plugin, xmind-builder. Installing the plugin makes the skill (and its bundled scripts) available in every project — one source of truth, no copying files around. Inside Claude Code:

/plugin marketplace add idachev/xmind-skills    # or a local path: /plugin marketplace add /path/to/xmind-skills
/plugin install xmind-builder@xmind-skills

Then in any project, ask things like:

• "Build me a mind map about home renovation planning" → triggers the xmind-builder skill
• "Add a Budget branch to the trip-planning map" → Claude edits the .xmindmark, recompiles, balances, verifies

The plugin ships the whole repo, so the skill always has scripts/balance-xmind.py and scripts/build-map.sh on hand (referenced via ${CLAUDE_PLUGIN_ROOT}) — even in repos that don't carry their own copies.

To adopt the workflow in your own repo, install the plugin as above, then optionally copy .claude/xmindmark-workflow.md and the relevant section of CLAUDE.md into your repo, keeping one directory per map with the source at the top and generated files under output/.

The workflow in one picture

<topic>.xmindmark          ← you (or Claude) edit this text file
      │  xmindmark <topic>.xmindmark          ┐
      ▼                                       │
<topic>.xmind              ← move to output/  ├─ or in one command:
      │  scripts/balance-xmind.py             │  scripts/build-map.sh <topic-dir>
      ▼                                       ┘
output/<topic>.xmind       ← balanced layout; open in XMind
      │  unzip -p ... content.json | python3 ...
      ▼
verified (root title + branches printed, Unicode intact)

Full details, including why the balance step is mandatory and what not to do: .claude/xmindmark-workflow.md.

Syntax cheat sheet

Central Topic                  ← first non-empty line is the root

- Branch 1                     ← "- " or "* ", 4 spaces per nesting level
    * Sub-topic
        - Detail
- Topic A [1]                  ← relationship source
- Topic B [^1](leads to)       ← relationship target, arrow labelled "leads to"
- Parent
    * Item A [B1]              ← boundary: groups consecutive same-level topics
    * Item B [B1]
    [B1]: Group Title
- Item 1 [S1]                  ← summary: wraps consecutive topics
- Item 2 [S1]
[S1]: Combined insight

Full reference (including what xmindmark cannot express — notes, labels, icons, styling): skills/xmind-builder/references/syntax.md.