miao-vision

Use when a user asks an agent such as Codex or Claude to turn an article URL, Markdown file, or long-form text into an infographic artifact with Miao Vision, or to visualize a local CSV, TSV, XLSX, or JSON data file, inspect data fields, generate an HTML chart/report, validate a visualization spec, choose charts from natural language, or produce a browser-presentable slide deck from data.

Use Miao Vision as a local-first infographic and visualization workflow for agent environments that can run local shell commands.

Agent Self-Install

If you are reading this file via URL, not from a local skill installation, run the following to install this skill permanently:

bash

# 1. Install the CLI
npm install -g @miao-vision/cli

# 2. Install the skill
SKILL_VERSION=$(npm show @miao-vision/cli version)
mkdir -p ~/.claude/skills
curl -fsSL "https://github.com/miaoshou-dev/miao-vision/releases/download/skill-v${SKILL_VERSION}/miao-vision-skill.zip" \
  -o /tmp/miao-vision-skill.zip
unzip -o /tmp/miao-vision-skill.zip -d ~/.claude/skills/
rm /tmp/miao-vision-skill.zip

After installation, the skill is available at ~/.claude/skills/miao-vision-skill/SKILL.md.

Requirement

The miao-viz CLI must be installed and available on PATH.

Check:

bash

miao-viz catalog

To get a machine-readable list of chart types with their rules, encodings, and anti-patterns:

bash

miao-viz catalog --for-llm

If the command is missing, tell the user to install:

bash

npm install -g @miao-vision/cli

Route The Request

Read only the reference needed for the user's task.

User intent	Required reference
Article URL, Markdown article, pasted long-form text, or "turn this into an infographic"	references/article-infographic.md and references/composition-playbook.md — Use the atomic bundle path as default for non-trivial articles. Auto-extract is for quick drafts only.
Local CSV/TSV/XLSX/JSON data report, analysis, dashboard, chart, visualization, or detailed findings	references/data-report.md
Slides, presentation, PPT, deck, 演示, 演示文稿, 汇报, 给老板看, meeting brief, or executive briefing	references/browser-deck.md

If the request mixes report and presentation, prefer the explicitly named output format. If the output format is ambiguous, ask one concise clarification question before running CLI commands.

Global Rules

• Default output is HTML.
• Default working directory for generated specs/artifacts is /tmp/miao-vision.
• Keep all work local. Do not upload user data.
• Do not call an LLM from the CLI. The agent may reason and write specs; the CLI validates and renders.
• Do not edit generated output as source.
• Keep URL fetching in the agent workflow. Do not require the CLI to fetch URLs directly.
• For article workflows, normalize URL or pasted content to local Markdown/text before rendering.
• For data reports, validate before render.
• For decks, use miao-viz deck; DeckSpec validation happens inside the deck command.
• Use supported chart and section types unless the user explicitly asks for an unsupported/experimental output.

Source Of Truth

The source skill lives in packages/miao-vision-skill/.

Packaged or copied skill files, including apps/web/public/SKILL.md, apps/web/dist/SKILL.md, and skills/miao-vision/SKILL.md, are not the primary source of truth. Update this source skill and use the existing build/pack flow to refresh generated copies when needed.

Shared References

• Read references/vizspec.md before writing report or deck specs, or when chart/transform syntax is unclear.
• Read references/examples.md when the request is ambiguous or close to an existing example.
• Use miao-viz catalog --for-llm only when the compact workflow context does not explain a chart rule clearly enough.