View or explain a project visually with ak:preview

Use ak:preview to open an existing file or directory in a reader, or turn a topic and current project evidence into a saved visual artifact. The Skill supports concise Markdown visuals, single-file HTML pages, slide decks, diagrams, diff reviews, plan reviews, and recent-project recaps.

Choose ak:preview when a visual improves understanding

Use ak:preview when

• You want to browse an existing Markdown file or directory in a reader.
• A code path, architecture, or data flow is easier to understand visually.
• You need an ASCII or Mermaid diagram for a technical discussion.
• You explicitly want an HTML explanation or slide deck.
• You want a visual review of a diff, implementation plan, or recent project context.

Choose another workflow when

• Plain prose or a short table already explains the relationship clearly.
• You need a non-templated, publish-grade SVG or PNG architecture diagram. Use ak:tech-graph.
• You need to update durable project documentation after creating a visual. Use ak:docs update.
• You need code review findings without a visual artifact. Use ak:code-review.

Prepare the project and runtime

Before you start:

• Complete Onboarding, and confirm Engineer Kit is installed for the runtime and scope you are using.
• Provide an existing path for view mode or a specific topic for generation.
• Open the relevant project when the visual depends on source, Git history, a diff, or an implementation plan.
• Review the active plan location because generated artifacts are saved inside its visuals/ directory when one exists.
• Decide whether opening a browser, starting a local network listener, reading a broad diff, or loading CDN resources is acceptable.

Run the Skill

/ak:preview --html --diagram "Request flow from API gateway through authentication, rate limiting, and the order service"

/ak:preview --html --diagram "Request flow from API gateway through authentication, rate limiting, and the order service"

$ak:preview --html --diagram "Request flow from API gateway through authentication, rate limiting, and the order service"

With no argument, the Skill presents a preview-operation chooser. Argument resolution gives --stop highest priority, then HTML and generation flags, then an explicit or conversation-resolved path.

Choose a mode deliberately

HTML-only flags imply --html. If several generation flags are supplied, the first selects the mode and the rest become part of the topic. HTML composition activates ak:frontend-design first, then ak:diagram when installed; otherwise it uses a semantic inline SVG/CSS fallback.

HTML modes enable an editorial visual layer by default when the intent matches: AntV Infographic for data-heavy panels and diagram-design for intentional architecture, concept, quadrant, timeline, and related layouts. Disable both for one run with --no-editorial-visuals, or disable one with --no-antv or --no-diagram-design. The Skill otherwise resolves visual.antv.enabled and visual.diagram_design.enabled from project then user configuration; there is no environment-variable tier.

Opt in to the AK Render HTML route

--ak-render implies --html and applies to --explain, --diff, --plan-review, and --recap HTML; --slides and --diagram stay on the default route. Instead of hand-writing the page, the Skill writes <slug>.page.yaml beside the output HTML and compiles it with the pinned npx -y @bestagentkits/render@0.2.0 compiler, which needs Node 20.11 or later. A project that has an .ak-render/ directory of AK Render theme presets selects this route automatically, without a per-run opt-out.

• The hand-written HTML route stays the default. AK Render remains opt-in because a measured comparison with the default route did not pass its quality gate.
• The page keeps the same required sections as the default route.
• The legacy CDN-based guidance applies only to the default route, which must disclose that network dependency in its report.
• The compiled page opens over file:// with zero network requests. The first npx run downloads the pinned package from the npm registry; later runs use the cache.
• To change the page, edit the spec and recompile. Do not patch the compiled HTML.
• Diagram panels compile through the ak:diagram page wrapper, which embeds the real SVG.
• If Node, npx, or the package is unavailable, or the spec is still invalid after three repairs, the Skill uses the default route and states the reason in its report.

Understand output locations and file effects

Generated Markdown and HTML use a topic slug of at most 80 characters:

• With an active plan: The output goes to <plan-directory>/visuals/<topic-slug>.md or .html.
• Without an active plan: The output goes to plans/visuals/<topic-slug>.md or .html.
• Missing directories: The Skill creates the required visuals/ path.
• Existing output: The Skill overwrites the same output path without an additional prompt.

Markdown generation starts the viewer after writing and reports its full local and network URLs. HTML generation opens the file directly in the platform browser command and does not need that viewer server.

Understand what happens during generation

1. The Skill resolves the operation. It selects view, stop, Markdown generation, or HTML generation from the ordered arguments.
2. The Skill gathers evidence. Topic modes inspect relevant project context; diff, plan-review, and recap modes collect their defined Git, plan, and source evidence.
3. The Skill selects a visual form. Mermaid handles automatic topology; diagram-design handles intentional editorial layouts; AntV Infographic handles multi-panel KPI, comparison, and timeline compositions; tables and Chart.js remain available for data. Complex systems use a hybrid overview and detail layout.
4. The Skill generates the artifact. Markdown uses the mode template. HTML writes one page with its page CSS and JavaScript inline, a light/dark toggle, responsive layout, and mode-appropriate interactions.
5. The Skill validates diagrams. Mermaid syntax is checked. diagram-design runs its vendored advisory validators when python3 is available. Rendered output is then inspected for overlaps, collisions, routing, and readability.
6. The Skill opens the result. Markdown uses the viewer server; HTML opens directly in a browser.
7. The Skill reports evidence. It returns the output path and the full viewer URL or browser-open result.

Understand the review modes

Visual diff review

--html --diff detects a branch, commit, range, HEAD, pull request, or the default comparison with main. It reads diff statistics, status, changed files and surrounding context, public API changes, relevant changelog and README updates, and available decision context.

Plan review

--html --plan-review reads the plan in full, follows its referenced files and dependencies, maps the blast radius, and compares plan assumptions with current code. Its output distinguishes current, planned, concern, and gap states.

Project recap

--html --recap reads project identity, recent Git activity, current status, decision context, and architecture. The default window is two weeks; shorthand such as 30d or 3m changes it.

Keep previews safe

Important boundaries:

• Stop the viewer with --stop when it is no longer needed.
• Keep view and review scopes away from secrets, unrelated private files, and content that should not be reachable through a local network listener.
• A pull-request diff uses GitHub CLI and therefore depends on network access, authentication, and repository permission.
• Generated HTML keeps page code in one file but may load Google Fonts, Mermaid, Chart.js, anime.js, or pinned @antv/infographic@0.2.19 from approved CDNs. Offline rendering can lose those resources. Use --no-antv when that external load is unacceptable.
• The workflow creates local artifacts and opens them. It does not publish, deploy, commit, or push them.
• The source defines no provider charge. Optional specialist Skills and image generation remain separate capability and authority boundaries.

Verify the result

A complete run should provide:

• The exact generated or viewed path.
• The full local and network URL for viewer mode, including its path and query.
• A browser-open confirmation for HTML output.
• A theme toggle and intentional light and dark rendering for every HTML page.
• Responsive content without unintended horizontal overflow.
• Zoom controls and readable labels for Mermaid diagrams.
• A rendered visual review for diagram modes, not only valid syntax.
• A logged Mermaid, Chart.js, or table fallback if AntV cannot load or render, or if a diagram-design result remains invalid after correction.
• Evidence boundaries and missing inputs for diff, plan-review, or recap modes.

Troubleshoot safely

Know the current limits

• The Markdown viewer execution contract is explicitly Claude Code-specific; equivalent Cursor or Codex background-server behavior is not established.
• HTML artifacts are single files but are not necessarily offline-complete when they use CDN fonts or libraries. AntV is enabled only for matching intent and has an explicit fallback; diagram-design itself has no runtime dependency.
• diagram-design validators are advisory and are skipped when python3 is not available; they do not block artifact delivery.
• Diff, plan-review, and recap quality is limited to the repository evidence and history they can read.
• Visual self-review improves layout quality but does not prove architectural or code-review conclusions.
• Cursor slash invocation is user-verified evidence, not proof of browser, server, or specialist-tool parity.