vc:preview
The `vc:preview` skill provides universal file viewing and visual content generation. Use it to inspect existing files and directories, or generate explanations, slides, diagrams, and HTML recaps in multiple formats including Mermaid diagrams, ASCII art, and interactive browser-based presentations. When complex SVG or PNG artifacts require publication-grade quality, pair it with `tech-graph` for artifact generation, then use `preview` for explanation and review.
git clone --depth 1 https://github.com/withkynam/vibecode-pro-max-kit /tmp/vc-preview && cp -r /tmp/vc-preview/.claude/skills/vc-preview ~/.claude/skills/vc-previewSKILL.md
# Preview
Universal viewer + visual generator. View existing content OR generate new visual explanations.
## Diagram Boundary
Use `preview` as the companion and review surface.
- Use `preview --diagram` or `preview --html --diagram` for explanation-first visuals, Mermaid-oriented flows, and review-friendly diagram pages.
- Use `tech-graph` first when the task needs a durable publish-grade SVG or PNG artifact under `process/general-plans/references/`, `process/general-plans/reports/visuals/`, or the matching feature-scoped equivalents.
- After `tech-graph` generation, `preview` is still the right place for explanation, comparison, HTML framing, or self-review of the generated artifact.
## Default (No Arguments)
If invoked without arguments, use `AskUserQuestion` to present available preview operations:
| Operation | Description |
|-----------|-------------|
| `(view)` | View a file or directory |
| `--explain` | Generate visual explanation |
| `--slides` | Generate presentation slides |
| `--diagram` | Generate architecture diagram |
| `--ascii` | Terminal-friendly diagram |
| `--stop` | Stop preview server |
| `--html --explain` | Self-contained HTML explanation (opens in browser) |
| `--html --diagram` | Self-contained HTML diagram with zoom controls |
| `--html --slides` | Magazine-quality HTML slide deck |
| `--html --diff` | Visual diff review (HTML) |
| `--html --plan-review` | Plan vs codebase comparison (HTML) |
| `--html --recap` | Project context snapshot (HTML) |
Present as options via `AskUserQuestion` with header "Preview Operation", question "What would you like to do?".
## Usage
### View Mode
- `/vc:preview <file.md>` - View markdown file in novel-reader UI
- `/vc:preview <directory/>` - Browse directory contents
- `/vc:preview --stop` - Stop running server
### Generation Mode (Markdown)
- `/vc:preview --explain <topic>` - Generate visual explanation (ASCII + Mermaid + prose)
- `/vc:preview --slides <topic>` - Generate presentation slides (one concept per slide)
- `/vc:preview --diagram <topic>` - Generate focused diagram (ASCII + Mermaid)
- `/vc:preview --ascii <topic>` - Generate ASCII-only diagram (terminal-friendly)
### Generation Mode (HTML)
- `/vc:preview --html --explain <topic>` - Self-contained HTML explanation
- `/vc:preview --html --slides <topic>` - Magazine-quality HTML slide deck
- `/vc:preview --html --diagram <topic>` - HTML diagram with zoom controls
- `/vc:preview --html --diff [ref]` - Visual diff review
- `/vc:preview --html --plan-review [plan-file]` - Plan vs codebase comparison
- `/vc:preview --html --recap [timeframe]` - Project context snapshot
## Argument Resolution
When processing arguments, follow this priority order:
1. **`--stop`** → Stop server (exit)
2. **`--html` flag present** → Set HTML output mode flag (continues to next step)
3. **Generation flags** (`--explain`, `--slides`, `--diagram`, `--ascii`) → Generation mode. Load `references/generation-modes.md`
4. **HTML-only flags** (`--diff`, `--plan-review`, `--recap`) → Auto-set HTML mode, then generation mode. Load `references/generation-modes.md`
5. **Resolve path from argument:**
- If argument is an explicit path → use directly
- If argument is a contextual reference → resolve from recent conversation context
6. **Resolved path exists on filesystem** → View mode. Load `references/view-mode.md`
7. **Path doesn't exist or can't resolve** → Ask user to clarify
**Topic-to-slug conversion:**
- Lowercase the topic
- Replace spaces/special chars with hyphens
- Remove non-alphanumeric except hyphens
- Collapse multiple hyphens → single hyphen
- Trim leading/trailing hyphens
- **Max 80 chars** - truncate at word boundary if longer
**Multiple flags:** If multiple generation flags provided, use first one; remaining treated as topic.
**Placeholder `{topic}`:** Replaced with original user input in title case (not the slug).
## Error Handling
| Error | Action |
|-------|--------|
| Invalid topic (empty) | Ask user to provide a topic |
| Flag without topic | Ask user: "Please provide a topic: `/vc:preview --explain <topic>`" |
| Topic becomes empty after sanitization | Ask for topic with alphanumeric characters |
| File write failure | Report error, suggest checking disk space and permissions |
| Server startup failure | Check if port in use, try `/vc:preview --stop` first |
| No generation flag + unresolvable reference | Ask user to clarify which file they meant |
| Existing file at output path | Overwrite with new content (no prompt) |
| Server already running | Reuse existing server instance, just open new URL |
| Parent output directory missing | Create directories recursively before write |
| `--diff` without git context | Explain: "No git repo detected. Run inside a git repository." |
| `--plan-review` without plan file or active plan | Explain: "Provide a plan file path or run from a session with an active plan." |
| `--recap` without git history | Explain: "No git history found. Run inside a git repository with commits." |
| `--html --ascii` combination | Not supported — `--ascii` is terminal-only by design. Suggest `--html --diagram` instead |
| `--diff` with PR number but `gh` unavailable | Explain: "GitHub CLI (gh) is required for PR diffs. Install from https://cli.github.com/" |
## HTML Output Mode (`--html`)
Adding `--html` to any generation flag switches output from Markdown to a self-contained HTML file.
**Output:** Single `.html` file with all CSS/JS inline. Opens directly in browser — no server needed.
**Location:** If an explicit plan file path is provided, write to its sibling `visuals/` directory. Otherwise write to `process/general-plans/reports/visuals/` or the current feature's `process/features/{feature}/reports/visuals/` when feature scope is explicit.
**Browser open:** `open` (macOS) / `xdg-open` (Linux) / `start` (Windows)
**MANDATORY — Theme Toggle:** Every HTML page MUST include a light/dark theme toggle button. See `html-css-patterns.md` → "ThComprehensive code review with scout-based edge case detection. Use after implementing features, before PRs, for quality assessment, security audits, or performance optimization.
Simplifies and refines code for clarity, consistency, and maintainability while preserving all functionality. Focuses on recently modified code unless instructed otherwise.
Use this agent when you need to investigate issues, analyze system behavior, diagnose performance problems, examine database structures, collect and analyze logs from servers or CI/CD pipelines, run tests for debugging purposes, or optimize system performance. This includes troubleshooting errors, identifying bottlenecks, analyzing failed deployments, investigating test failures, and creating diagnostic reports. Examples:\n\n<example>\nContext: The user needs to investigate why an API endpoint is returning 500 errors.\nuser: "The /api/users endpoint is throwing 500 errors"\nassistant: "I''ll use the debugger agent to investigate this issue"\n<commentary>\nSince this involves investigating an issue, use the Task tool to launch the debugger agent.\n</commentary>\n</example>\n\n<example>\nContext: The user wants to analyze why the CI/CD pipeline is failing.\nuser: "The GitHub Actions workflow keeps failing on the test step"\nassistant: "Let me use the debugger agent to analyze the CI/CD pipeline logs and identify the issue"\n<commentary>\nThis requires analyzing CI/CD logs and test failures, so use the debugger agent.\n</commentary>\n</example>\n\n<example>\nContext: The user notices performance degradation in the application.\nuser: "The application response times have increased by 300% since yesterday"\nassistant: "I''ll launch the debugger agent to analyze system behavior and identify performance bottlenecks"\n<commentary>\nPerformance analysis and bottleneck identification requires the debugger agent.\n</commentary>\n</example>
EXECUTE MODE - Implementing EXACTLY what was planned. Full tool access. Can only be invoked after explicit user confirmation. Use after plan is approved.
FAST MODE - Execute compressed RIPER-5 workflow (RESEARCH + INNOVATE + PLAN) in one session, then pause for EXECUTE confirmation. Use when you want quick end-to-end solution.
Stage, commit, and push code changes with conventional commits. Use when user says "commit", "push", or finishes a feature/fix.
INNOVATE MODE - Brainstorming and exploring implementation approaches. Discusses possibilities without making decisions. Use after research is complete.
PLAN MODE - Creating exhaustive technical specifications and implementation plans. Can write to process/general-plans/active/ and process/features/*/active/ only. Use after approach is decided.