Skip to content

Rain/chore/sync xmind file 0.2.2 #6

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Rain-xmind merged 2 commits into from
Jul 21, 2026
Merged

Rain/chore/sync xmind file 0.2.2 #6

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b406cd5
docs(skill): sync xmind-file 0.2.2
Rain-xmind Jul 21, 2026
08dd5ec
docs: improve public CLI guidance
Rain-xmind Jul 21, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
152 changes: 105 additions & 47 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,53 +7,94 @@
[![npm version](https://img.shields.io/npm/v/@xmindltd/xmind-cli.svg)](https://www.npmjs.com/package/@xmindltd/xmind-cli)
[![license: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

**Create local Xmind mind maps with AI agents.**
**Turn complex information into clear, native, and fully editable Xmind files with AI agents.**

`xmind-cli` gives agents a reliable local-file workflow for `.xmind` maps:
generate structured maps, inspect and validate files, apply edits, attach
images, and report Xmind credits used by premium features.
Xmind CLI gives agents the core capabilities to work with local `.xmind` files. The official Xmind Skill teaches them how to organize content, choose the right structure, design the visual hierarchy, and check the result.

## Install
## Getting Started

Give this repository to an agent that supports Skills and terminal commands, then ask:

> Install Xmind Skill & CLI and verify that it is ready to use.

The agent can handle the setup. If sign-in is required, approve the browser authorization when prompted; the CLI stores the session locally.

### Instructions for the installing agent

Install both the CLI and the Skill:

```bash
npm install -g @xmindltd/xmind-cli
npx skills add xmindltd/xmind-cli -y
```

The skill install command adds the `xmind-file` skill to supported agent skill
directories. Verify the CLI and available guidance:
Verify the CLI and authentication status:

```bash
xmind skill list
xmind --version
xmind auth status
```

If needed, sign in once:
If sign-in is required:

```bash
xmind auth login
```

## Quick Start
Ask the user to complete authorization in the browser, then run `xmind auth status`
again. Once authenticated, verify the available guidance:

```bash
xmind skill list
```

Do not ask the user to run the installation commands manually unless the
environment prevents you from doing so.

### Create your first map

Once setup is complete, ask your agent:

> Create an editable Xmind map from this document and save it as `overview.xmind`.

Ask your agent:
You can also provide a topic, webpage, PDF, set of notes, or other source material available to your agent.

> Create a local Xmind mind map about Apollo 11.
## Xmind Skill and CLI

The agent uses the `xmind-file` skill to choose a recipe, draft the map, build a
generate spec, run `xmind generate`, validate the `.xmind`, and summarize the
result.
Xmind is more than a way to arrange text in a tree. It is a visual thinking system for presenting hierarchy, sequence, comparison, time, cause and effect, and actionable work.

## What It Can Do
| | Role |
|---|---|
| **Xmind CLI** | Creates, reads, edits, enriches, and validates native `.xmind` files. |
| **Xmind Skill** | Guides the agent in content organization, structure selection, visual design, and quality review. |

- Generate rich local `.xmind` files from semantic specs.
> **The CLI lets an agent use Xmind. The Skill teaches it to use Xmind well.**

## What You Can Create

You do not need to organize everything first. If your agent can access them, local files, PDFs, images, webpages, and connected sources can all become source material.

| Give your agent | Get an editable Xmind |
|---|---|
| An article, webpage, report, or PDF | **A clear overview** of the main ideas, conclusions, and structure |
| Papers, books, course material, notes, and research sources | **A knowledge map** connecting concepts, evidence, claims, and sources |
| Meeting notes, task lists, plans, and project material | **An execution map** showing decisions, priorities, risks, and next steps |
| Product information, spreadsheets, designs, and user feedback | **A comparison or decision map** built around consistent criteria and trade-offs |
| Source code, repositories, issues, pull requests, documentation, and logs | **A system map** showing module boundaries, runtime flow, and change impact |

## Core Capabilities

- Generate rich local `.xmind` files from semantic specifications.
- Create quick maps from Markdown.
- Read, describe, and validate existing `.xmind` files.
- Edit maps with add/update/delete/theme/layout/marker/label/batch commands.
- Read and describe existing maps so they can become context for further work.
- Add, update, delete, and batch-edit topics.
- Apply structures, themes, layouts, markers, labels, links, and other visual elements.
- Attach local images, stable public raster image URLs, or Wikipedia images.
- Report actual billing as Xmind credits when premium features are used.
- Check generation specifications and validate completed `.xmind` files.
- Report the selected route, applied visual enhancements, fallback behavior, and Xmind credits used.

Core commands:
<details>
<summary>Command reference</summary>

```bash
xmind generate --spec generate.json -o output.xmind
Expand All @@ -62,51 +103,68 @@ xmind create --from-markdown draft.md -o output.xmind
xmind read output.xmind
xmind describe output.xmind
xmind validate output.xmind --quiet
xmind batch output.xmind
xmind batch output.xmind --input operations.json
xmind image output.xmind --topic "Topic" --wiki "Apollo 11"
```

## How Generation Works
</details>

## How It Works

The agent provides semantic judgment; the CLI provides reliable execution.

1. The agent understands the goal, audience, and source material.
2. The Skill helps it choose an appropriate content method, structure, theme, and visual strategy.
3. The agent prepares the content and generation specification.
4. The CLI builds the native `.xmind`, applies visual enhancements and images, and validates the file.
5. The agent reviews the result, makes any necessary edits, and delivers the finished file.

This is not a one-shot conversion. The same map can be read, refined, and updated as the work develops.

<details>
<summary>Execution details</summary>

CLI JSON output records execution facts such as `route.skeletonReason`, `route.colorReason`, `anchors.applied`, `billing.consumed`, `billing.balance`, `billing.unit`, and `downgraded`.

</details>

## Beyond One-Shot Mind Map Generation

| | One-shot generation workflow | Xmind Skill & CLI |
|---|---|---|
| **Xmind capabilities** | Produces a topic hierarchy with initial styling | Works with native Xmind structures, styling, editing, images, links, and validation |
| **Structure and visual design** | Applies structure and styling during the initial generation | Selects structures and visual treatments according to the content and task |
| **Workflow** | Produces an initial result | Supports generation, inspection, validation, editing, and continued refinement |
| **Deliverable** | May require conversion or recreation for continued editing | A native local `.xmind` file ready for further editing and delivery |

The agent supplies semantic judgment. The CLI handles mechanical execution.
## Current Scope

1. The agent chooses a recipe for the user goal.
2. The agent drafts Markdown with titles, hierarchy, and notes.
3. The agent writes a generate spec with route intent, visual anchors, and image
targets.
4. `xmind generate` selects the final structure/color, applies anchors and
images, validates the file, and returns JSON.
5. The agent reports the output path, validation result, key design choices, and
any Xmind credits consumed.
The currently published `xmind-file` Skill focuses on local-file workflows:

The JSON output includes execution facts such as `route.skeletonReason`,
`route.colorReason`, `anchors.applied`, `billing.consumed`, `billing.balance`,
`billing.unit`, and `downgraded`.
- It creates and edits local `.xmind` files; it does not provide real-time cloud collaboration.
- It can attach existing local or web images, but it does not generate AI images within this Skill.
- It requires an agent environment that can install Skills and run local commands.

## Billing
## Xmind Credits

Some premium structures, themes, or recipe skills may consume Xmind credits.
The CLI reports billing in JSON. Treat `billing.unit` as authoritative; these
are **Xmind credits**, not OpenAI, Codex, model, or token credits.
Some premium structures, themes, or recipe skills may consume Xmind credits. The CLI reports actual usage and the remaining balance. These are **Xmind credits**, not OpenAI, Codex, model, or token credits.

If credits are unavailable, the CLI may downgrade to a free fallback unless the
agent uses `--no-downgrade`.
If credits are unavailable, the CLI may use a free fallback unless `--no-downgrade` is set.

## This Repo

This repository distributes the public agent skill entry point:
This public repository distributes the agent Skill entry point:

- [`skills/xmind-file/SKILL.md`](skills/xmind-file/SKILL.md)
- [`.claude-plugin/marketplace.json`](.claude-plugin/marketplace.json)

The CLI binary ships separately on npm as
[`@xmindltd/xmind-cli`](https://www.npmjs.com/package/@xmindltd/xmind-cli).
The CLI is published separately on npm as [`@xmindltd/xmind-cli`](https://www.npmjs.com/package/@xmindltd/xmind-cli).

## Links

- [Xmind](https://xmind.com) — apps that read `.xmind` files
- [`@xmindltd/xmind-cli`](https://www.npmjs.com/package/@xmindltd/xmind-cli)
- [Agent Skills spec](https://github.com/anthropics/skills)
- [Xmind](https://xmind.com) — open and continue editing `.xmind` files
- [`@xmindltd/xmind-cli`](https://www.npmjs.com/package/@xmindltd/xmind-cli) — install the CLI
- [Agent Skills specification](https://github.com/anthropics/skills)

## License

Expand Down
91 changes: 47 additions & 44 deletions skills/xmind-file/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,19 +42,18 @@ File commands require login.

## Recipe Choice

Choose recipe before drafting.
Run `xmind skill list` before drafting and treat its recipe catalog and triggers
as the source of truth. Do not maintain a recipe inventory in this skill.

Ask the user to choose before creating a new map when the request is broad and
two or more recipes would produce meaningfully different artifacts. Offer 2-4
domain-specific choices, for example:
Choose directly when the user names a recipe or you have high confidence that
one recipe best fits the requested artifact. Otherwise, recommend the best
match, present 2-4 relevant catalog choices with a short description of how each
would shape the artifact, and wait for the user to choose before drafting. When
confidence is not high, bias toward user choice.

- Quick overview: compact, `recipe/quick-map`, free-first.
- Timeline narrative: sequence/history, `recipe/timeline-narrative`.
- Deep knowledge map: concepts/tradeoffs, `recipe/default`.
- Focused analysis: `recipe/swot`, `recipe/comparison-decision`, or
`recipe/process-playbook` only when the topic naturally matches.

Do not use `quick-map` as an implicit fallback only because it is fast or free.
This does not override CLI/server fallback. If `xmind skill show` returns
`effective: "quick-map"` because premium recipe access or Xmind credits are not
available, follow the effective recipe and explain the fallback plainly.

## Context Loading

Expand Down Expand Up @@ -117,17 +116,8 @@ For rich generation, write a semantic spec and let the CLI compile it.
}
```

Anchor families:

- `layout`: local relation layouts on `###` or deeper nodes.
- `group`: `boundary` / `summary` over sibling groups.
- `focus`: `emphasis`, `callout`, `numbering`, or `relation`.
- `image`: local file, stable raster URL, or Wikipedia image. Generate attaches
images last.

Use `"auto"` baseline unless the user gave an override or you have a recorded
reason. The Agent decides anchors semantically; do not invent decorative anchors
only to satisfy a checklist.
Follow Visual for baseline selection, anchor-family semantics, target selection,
and its anchor quality gate.

## Semantic Quality Gate

Expand Down Expand Up @@ -158,21 +148,10 @@ validation cannot detect a shallow or semantically fake map.

Follow recipe density, shape, semantic signals, notes posture, and self-check.
First draft the visible heading skeleton, then add selective notes and anchor
candidates. For `recipe/default`, density is normally `deep`. Write pure
CommonMark to `/tmp/xmind-draft-<id>.md`.

3. Write `/tmp/xmind-generate-<id>.json`.

The route fields are semantic declarations:
candidates. Write pure CommonMark to `/tmp/xmind-draft-<id>.md`.

- `structuralType`: root relation family.
- `structureCommitment`: how strongly that root relation is required.
- `toneTag`: palette character.
- `density`: recipe density, not a skeleton choice.

For default maps, normally provide at least one real target in `layout`,
`group`, `focus`, and `image`, unless the user asked for text-only/no-images
or the subject has no useful concrete image anchor.
3. Write `/tmp/xmind-generate-<id>.json` using the route and baseline semantics
defined by Visual.

4. Preflight and optionally dry-run:

Expand Down Expand Up @@ -214,15 +193,9 @@ Use when the chosen recipe is `quick-map`.
xmind skill show markdown-grammar recipe/quick-map --json
```

2. Draft compact markdown, usually `light` or `standard`.

3. Pick a free baseline directly:
2. Draft compact markdown according to the effective recipe.

- overview/resource: `MindMap-1`
- triage/checklist: `Matrix-1`
- quick-plan/simple-process: `LogicChart-1`
- simple-timeline: `Timeline-1` or `Timeline-3`
- hierarchy: `OrgChart-1` or `TreeChart-1`
3. Choose the mode and free skeleton from the effective recipe's mode table.

4. Create and validate:

Expand All @@ -234,6 +207,12 @@ Use when the chosen recipe is `quick-map`.
Run `read`/`describe` only if validation fails, the user asks, or a small
repair is clearly needed.

5. Communicate the boundary.

Tell the user this is a quick overview, not the full rich-map path. Offer to
regenerate with a fuller recipe if they want deeper titles/notes, visual
anchors, images, or premium-capable structure.

## Flow B: Edit Existing Map

1. Load `edit/guide`; load `visual` only if the edit changes visual treatment.
Expand Down Expand Up @@ -268,6 +247,27 @@ xmind image <file>.xmind --topic "<topic title>" --url "<https-image-url>"
xmind image <file>.xmind --topic "<topic title>" --wiki "<Wikipedia page title>"
```

## Links

Use `link` for a single topic. Local paths are resolved to absolute `file:///`
URIs and URL-encoded in the same form written by Xmind Desktop:

```bash
xmind link <map>.xmind --topic "Reference" --url "https://example.com"
xmind link <map>.xmind --topic "Local map" --file "../maps/example.xmind"
xmind link <map>.xmind --topic "Reference" --remove
```

For batch edits, `href` accepts either `href` or `file` (exactly one):

```json
{"op":"href","topic":"Local map","file":"../maps/example.xmind"}
```

Local file links point to the original file; they do not embed or copy it into
the `.xmind` archive. They work only on machines where that absolute path
exists. Use an `https` URL when the map must be portable.

## Delivery Gate

For Flow A:
Expand Down Expand Up @@ -308,3 +308,6 @@ validation/inspection.

Final response: give the file path, validation result, and one or two important
design choices. Do not dump the full outline unless asked.

If the file was already open in Xmind, later CLI edits may not appear immediately;
tell the user to close and reopen it in Xmind to refresh.