From b406cd54128f1c6a7bb02f3e461c8c4ee0886847 Mon Sep 17 00:00:00 2001 From: rain Date: Tue, 21 Jul 2026 17:04:02 +0800 Subject: [PATCH 1/2] docs(skill): sync xmind-file 0.2.2 --- skills/xmind-file/SKILL.md | 91 ++++++++++++++++++++------------------ 1 file changed, 47 insertions(+), 44 deletions(-) diff --git a/skills/xmind-file/SKILL.md b/skills/xmind-file/SKILL.md index 6518efa..efa2704 100644 --- a/skills/xmind-file/SKILL.md +++ b/skills/xmind-file/SKILL.md @@ -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 @@ -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 @@ -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-.md`. - -3. Write `/tmp/xmind-generate-.json`. - - The route fields are semantic declarations: + candidates. Write pure CommonMark to `/tmp/xmind-draft-.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-.json` using the route and baseline semantics + defined by Visual. 4. Preflight and optionally dry-run: @@ -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: @@ -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. @@ -268,6 +247,27 @@ xmind image .xmind --topic "" --url "" xmind image .xmind --topic "" --wiki "" ``` +## 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 .xmind --topic "Reference" --url "https://example.com" +xmind link .xmind --topic "Local map" --file "../maps/example.xmind" +xmind link .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: @@ -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. From 08dd5ec416d2a44190a0f4b20f549a6bb9aa5da0 Mon Sep 17 00:00:00 2001 From: rain Date: Tue, 21 Jul 2026 17:20:22 +0800 Subject: [PATCH 2/2] docs: improve public CLI guidance --- README.md | 152 +++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 105 insertions(+), 47 deletions(-) diff --git a/README.md b/README.md index 00db935..5f8608e 100644 --- a/README.md +++ b/README.md @@ -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: +
+Command reference ```bash xmind generate --spec generate.json -o output.xmind @@ -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 +
+ +## 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. + +
+Execution details + +CLI JSON output records execution facts such as `route.skeletonReason`, `route.colorReason`, `anchors.applied`, `billing.consumed`, `billing.balance`, `billing.unit`, and `downgraded`. + +
+ +## 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