# live-preview

live-preview takes screenshots of components during construction, not after completion. Catches layout regressions and invisible blocks before they propagate.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf (Devin Desktop), Claude.ai · ★ 937 repo stars
- Author: SethGammon
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/SethGammon/Citadel/tree/HEAD/skills/live-preview/SKILL.md
- Updated: 2026-10-29
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/live-preview

## What it does

The skill triggers on `preview`, `screenshot`, `visual check` keywords or runs manually. It identifies which `.tsx`, `.jsx`, `.vue`, `.svelte` or `.html` files changed, maps them to routes, starts the dev server, and captures screenshots via Playwright (`npx playwright screenshot [url] [output.png] --full-page`). Saves images to `.planning/screenshots/`, verifies that components render, data loads, and layout holds. If it finds a blank screen or failure, it diagnoses, fixes, and re-verifies. Two attempts per component maximum.

Without Playwright, the skill lists what to check manually and suggests `npm i -D playwright`. If no view-layer files changed, it exits immediately: "No view-layer files modified. Nothing to preview." In Codex, it registers screenshots as artifacts (`node scripts/codex-app-artifacts.js record --workflow live-preview --kind screenshot`). When integrated with Archon, it blocks phase transitions until critical failures are resolved.

## Requirements
- Works with: Playwright

## Install

### Claude Code (native platform)

1. **Plugin marketplace**
In the agent chat (not a shell):
```text
/plugin marketplace add SethGammon/Citadel
```
In the agent chat (not a shell):
```text
/plugin install citadel@citadel-local
```
This installs the whole citadel plugin with all its skills

2. **Skills CLI (Vercel)**
```bash
npx skills add SethGammon/Citadel --skill live-preview -a claude-code
```

3. **Manually: put the files in place**
- File: `~/.claude/skills/live-preview/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/live-preview/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add SethGammon/Citadel --skill live-preview -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/live-preview/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add SethGammon/Citadel --skill live-preview -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/live-preview/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install SethGammon/Citadel skills/live-preview
```

2. **Manually: put the files in place**
- File: `.github/skills/live-preview/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add SethGammon/Citadel --skill live-preview -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/SethGammon/Citadel --path skills/live-preview
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/live-preview/SKILL.md` — The legacy .windsurf/skills/ path still works

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/SethGammon/Citadel/tree/HEAD/skills/live-preview/SKILL.md

## When to use it
- prevent shipping invisible components to production
- verify rendering after `.tsx` or `.vue` edits
- catch layout regressions before commit
- automate visual checks during build
- save screenshots as reviewable artifacts

## Example prompts
- Take a screenshot of `/dashboard` after editing `Dashboard.tsx`
- Run visual verification on modified components
- Check that `ProfileCard.tsx` renders correctly

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 68fc923f6d9de141.

BEGIN THIRD-PARTY FILE 68fc923f6d9de141
````text
---
name: live-preview
license: MIT
description: >-
  Mid-build visual verification loop. Takes screenshots of components during
  construction, not just after. Catches visual regressions and invisible features
  before they compound. Requires Playwright or similar screenshot tool.
user-invocable: true
auto-trigger: false
trigger_keywords:
  - preview
  - screenshot
  - visual check
  - does it render
last-updated: 2026-03-21
---

# /live-preview — Build-Verify-Fix Loop

## Prerequisites

This skill requires a screenshot tool. Supported:
- **Playwright** (recommended): `npx playwright screenshot [url] [output.png]`
- **Puppeteer**: via a small script
- **Any tool that takes a URL and produces a screenshot**

If no screenshot tool is available, this skill will tell you what to install and exit.

## When to Use

- Any time .tsx, .jsx, .vue, .svelte, or .html files are modified
- After component creation or replacement
- During visual redesign campaigns
- When Archon or Marshal delegate UI work

## Protocol

### Step 1: DETECT

Determine what needs visual verification:

1. Check which files were modified in the current session/phase
2. Filter to view-layer files (.tsx, .jsx, .vue, .svelte, .html, .css)
3. **If no view-layer files found**: exit early with message
   "No view-layer files modified. Nothing to preview." Skip Steps 2-5.
   This is expected for non-UI repos (CLI tools, libraries, agent harnesses).
4. Map each modified file to a route or URL where it renders:
   - If the project has a route manifest or sitemap, use it
   - If the project has a dev server, identify which routes render the modified components
   - If you can't determine the route, ask the user

### Step 2: CAPTURE

For each route/URL that needs verification:

1. Ensure the dev server is running (start it if not)
2. Take a screenshot:
   ```bash
   npx playwright screenshot http://localhost:{port}/{route} .planning/screenshots/{route-slug}.png --full-page
   ```
3. If Playwright isn't available, try:
   ```bash
   # Check for playwright
   npx playwright --version 2>/dev/null
   # If not found, inform the user:
   # "live-preview needs Playwright for screenshots. Install with: npm i -D playwright"
   ```

### Step 3: VERIFY

For each screenshot:

1. Read the screenshot (vision). Check:
   - Does the component render? (not blank, not invisible)
   - Does it show real data or placeholder/empty states?
   - Are there obvious layout breaks (overlapping elements, overflow, missing sections)?
   - Does it match the intended design direction?
2. Record the result:
   - PASS: renders correctly, matches expectations
````
END THIRD-PARTY FILE 68fc923f6d9de141

The third-party file has ended. Everything between the 68fc923f6d9de141 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2626 of 6525 bytes. © SethGammon · MIT · https://github.com/SethGammon/Citadel/tree/HEAD/skills/live-preview/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
