mk-preview
Generate visual artifacts: explanations, diagrams, slides, diff views. NOT publish-grade diagrams (mk:tech-graph), live media gen (mk:multimodal), or browser QA (mk:qa).
- License 许可
- MIT
- 最近更新
- 2026-11-15
- Stars
- ★ 16
- Forks
- 3
01 前言 Front Matter
- name
- mk-preview
- description
- Generate visual artifacts: explanations, diagrams, slides, diff views. NOT publish-grade diagrams (mk:tech-graph), live media gen (mk:multimodal), or browser QA (mk:qa).
02 资源文件 8
- 资产文件assets/architecture.html7.6 KB
- 资产文件assets/data-table.html7.2 KB
- 资产文件assets/mermaid-flowchart.html7.3 KB
- 资产文件assets/slide-deck.html7.0 KB
- 参考文档references/analytical-modes.md4.6 KB
- 参考文档references/generation-modes.md5.6 KB
- 参考文档references/html-design-rules.md13.3 KB
- 参考文档references/mermaid-essentials.md3.0 KB
03 SKILL.md 正文
mk:preview
Generates visual artifacts — markdown and self-contained HTML — for explaining code, drawing diagrams, building slide decks, and visualizing diffs.
No live server. No Python. Pure markdown + HTML + bash file operations. Output writes to tasks/plans/{active-plan}/visuals/ when an active plan exists; otherwise falls back to tasks/visuals/.
When to Use
- A reader needs to understand an unfamiliar code path, protocol, or architecture
- A diagram (flowchart, sequence, ER) would communicate the topology faster than prose
- Step-by-step content benefits from slides over a single long page
- A pre-PR diff review needs visual KPIs, file map, and change cards
- Stakeholders prefer a self-contained HTML page they can open in a browser without a server
Default (No Arguments)
If invoked with no arguments, present available operations via stop and ask the user in chat. Header: "Preview Operation". Question: "What would you like to do?".
| Operation | Description |
|---|---|
--explain |
Markdown visual explanation (ASCII + Mermaid + prose) |
--diagram |
Markdown diagram (ASCII + Mermaid) |
--slides |
Markdown presentation slides |
--ascii |
Terminal-friendly ASCII diagram only |
--html --explain |
Self-contained HTML explanation, opens in browser |
--html --diagram |
HTML diagram with zoom/pan controls |
--html --slides |
Magazine-quality HTML slide deck |
--html --diff |
HTML diff visualization (KPI grid + file map + cards) |
Recommended default: --explain or --html --explain.
Usage
Markdown Generation
the preview skill --explain <topic>— visual explanation (ASCII + Mermaid + concepts)the preview skill --diagram <topic>— focused diagram (ASCII + Mermaid)the preview skill --slides <topic>— presentation slides (one concept per slide)the preview skill --ascii <topic>— ASCII-only diagram (terminal-friendly)
HTML Generation
the preview skill --html --explain <topic>— self-contained HTML explanationthe preview skill --html --diagram <topic>— HTML diagram with zoom/panthe preview skill --html --slides <topic>— magazine-quality slide deck
Analytical Modes
the preview skill --html --diff [ref]— visualize a git diff. Defaultref=main. Accepts branch, commit, range, PR number.
--ascii does not combine with --html (terminal-only by design).
Argument Resolution
Priority order:
--htmlflag detected → set HTML output mode- Generation flag detected (
--explain,--diagram,--slides,--ascii) → loadreferences/generation-modes.md - HTML-only flag (
--diff) → implies--html; loadreferences/analytical-modes.md - Topic missing → ask user via
stop and ask the user in chat - Topic present → continue
Topic-to-slug:
- Lowercase the topic
- Replace spaces and special chars with hyphens
- Remove non-alphanumeric except hyphens
- Collapse multiple hyphens to single
- Trim leading/trailing hyphens
- Truncate at 80 chars on a word boundary
Title placeholder {topic} uses the original input in title case, not the slug.
Multiple flags: if more than one generation flag is supplied, use the first; the rest become part of the topic string.
Output Path Lifecycle
.meowkit/state/active-plan exists?
yes → value is absolute path?
yes → {value}/visuals/
no → tasks/plans/{value}/visuals/ (treated as slug)
no → tasks/visuals/
Detail and the bash detection snippet live in references/generation-modes.md → "Step 1 — Resolve output path". The fallback path is logged on stderr (warn:) so silent path mismatches surface immediately.
Error Handling
| Error | Action |
|---|---|
| Topic empty after sanitization | Ask user for an alphanumeric topic |
| Flag without topic | Ask user for the topic string |
| File write failure | Report the error; suggest checking disk space and permissions |
| Output path already exists | Overwrite without prompting |
--diff outside a git repo |
Explain: "No git repository detected" |
--diff with PR number, no gh |
Suggest installing gh from https://cli.github.com/ |
--html --ascii combination |
Reject; suggest --html --diagram instead |
| Active-plan path absolute but missing | Log warning; fall back to tasks/visuals/ |
| Active-plan slug with no matching dir | Log warning; fall back to tasks/visuals/ |
Reference Loading
Every mode reads its references BEFORE writing the output file.
| Mode | Always reads | Mode-specific |
|---|---|---|
--explain |
references/generation-modes.md, references/mermaid-essentials.md |
— |
--diagram |
references/generation-modes.md, references/mermaid-essentials.md |
— |
--slides |
references/generation-modes.md, references/mermaid-essentials.md |
— |
--ascii |
references/generation-modes.md |
— |
--html --explain |
references/html-design-rules.md, ../frontend-design/references/anti-slop-directives.md |
template assets/architecture.html |
--html --diagram |
references/html-design-rules.md, references/mermaid-essentials.md, ../frontend-design/references/anti-slop-directives.md |
template assets/mermaid-flowchart.html |
--html --slides |
references/html-design-rules.md, ../frontend-design/references/anti-slop-directives.md |
template assets/slide-deck.html |
--html --diff |
references/html-design-rules.md, references/analytical-modes.md, ../frontend-design/references/anti-slop-directives.md |
template assets/data-table.html, assets/architecture.html |
Templates in assets/ are out-of-band — they are not auto-Read; the agent reads the template only when generating the matching mode.
Composes With
mk:ui-design-system— palette and typography selection (assets/colors.csv160 rows,assets/typography.csv73 rows). HTML modes vary palette per run.mk:frontend-design— anti-slop forbidden patterns. Cited via../frontend-design/references/anti-slop-directives.md, not duplicated.mk:web-to-markdown— for users who want to view a generated markdown file in a browser, no server bundled here.
Gotchas
- Mermaid
.nodeclass collision — Mermaid.js uses.nodeinternally. Page-level.nodeCSS leaks into diagrams. Use.ve-cardor any non-.nodeclass on cards. - Mandatory theme toggle — every HTML artifact MUST include the light/dark toggle button as the first child of
<body>perreferences/html-design-rules.md. Missing toggle = incomplete output. - Mermaid theme is static at load — switching the page theme does not re-skin Mermaid SVG internals; the diagram color palette is read once at init. Document this; do not pretend otherwise.
- Output path falls back silently — when
.meowkit/state/active-planis missing or unreadable, output writes totasks/visuals/. Log the fallback on stderr so users notice; do not raise. - Slug truncation at 80 chars — topics get lowercased, hyphenated, stripped of non-alphanumerics, and truncated at word boundary. Title placeholder uses the original input in title case (not slug). Mismatch silently produces wrong filenames.
- Topic strings are HTML-untrusted — interpolating
--explain "</title><script>alert(1)</script>"MUST render as literal text. HTML-entity-encode< > & " 'in element and attribute contexts. Seereferences/html-design-rules.mdfor context-by-context encoding rules. - Browser auto-open is conditional — headless / SSH / WSL environments cannot open a browser. The shell snippet detects these cases and prints the path instead of invoking
open/xdg-open.
Workflow Position
- Phase: on-demand
- Follows: nothing required
- Precedes: nothing required
- Common pairings: invoked after a researcher report or planner output to communicate findings; invoked before a review meeting to explain a code path or diagram an architecture.
Composes Into
mk:cookmay invoke--explainto communicate a complex implementation phasemk:plan-ceo-reviewCRITIQUES plans; it does not overlap this skill's generic explain/diagram/slides/diff output
04 同仓库更多 Skills
mk-worktree
Manages git worktrees for parallel agent isolation: creates parallel/{name}-{timestamp} branches, merges with conflict detection. NOT for user feature branches (use git worktree directly).
mk-workflow-orchestrator
Auto-invoked 7-phase workflow for complex-feature intent; fasttrack mode for pre-approved specs. NOT for explicit single tasks (mk:cook), green-field builds (mk:autobuild), or simple fixes (mk:fix).
mk-web-to-markdown
Fetch a URL and return clean markdown, for arbitrary external pages (blog, RFC, GitHub issue, vendor doc) not covered by mk:docs-finder. Static-only by default; opt-in JS rendering available.
mk-vulnerability-scanner
Vulnerability analysis: OWASP Top 10, current threat landscape, supply chain security, attack surface mapping, risk prioritization. Use for security audits. NOT for STRIDE/CSO infra audits (mk:cso).
mk-vue
Vue 3 authoring/review: components, composables, reactivity, Pinia, Pinia Colada, file routing, forms. Composition API + script setup. Auto-activates on .vue files. Deep review: mk:vue-best-practices.
mk-vue-testing-best-practices
Vue 3 testing best-practices review: Vitest + Vue Test Utils for components, composables, Pinia, Router, async/Suspense, forms, a11y, plus Playwright E2E strategy. Advisory only.