Skip to main content
skill CX Codex

live-preview — Claude Code skill: what it does, how to install

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

MIT ★ 937 updated 2026-10-29

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add SethGammon/Citadel
/plugin install citadel@citadel-local
Open on GitHub

What live-preview 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.

What it helps with

  • 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 for the agent

  • Take a screenshot of /dashboard after editing Dashboard.tsx
  • Run visual verification on modified components
  • Check that ProfileCard.tsx renders correctly

How to install live-preview

1Plugin marketplace

/plugin marketplace add SethGammon/Citadel
/plugin install citadel@citadel-local

This installs the whole citadel plugin with all its skills

2Skills CLI (Vercel)

npx skills add SethGammon/Citadel --skill live-preview -a claude-code

3Manually: put the files in place

~/.claude/skills/live-preview/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/live-preview/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about live-preview

How to install live-preview in Claude Code?

First /plugin marketplace add SethGammon/Citadel, then /plugin install citadel@citadel-local. For manual install: npx skills add SethGammon/Citadel --skill live-preview -a claude-code, file ends up in ~/.claude/skills/live-preview/SKILL.md.

What does live-preview do?

It captures screenshots of components during build, checks that they render without blank screens or layout breaks, and fixes critical errors before moving to the next task.

What does live-preview require?

Playwright for screenshots (npm i -D playwright recommended), a running dev server, and modified view-layer files. Without Playwright, it outputs a manual checklist instead.

Source text

SKILL.md · MIT
---
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
   - FAIL: describe what's wrong
   - BLANK: nothing rendered (critical failure)

### Step 4: FIX (if failures found)

For each FAIL or BLANK:

1. Diagnose: is it a data issue, a rendering issue, or a missing import?
2. Fix the root cause (not a band-aid)
3. Re-capture and re-verify
4. Maximum 2 fix attempts per component. If still failing, log it and move on.

### Step 5: ARTIFACT

Save verification artifacts:

1. Screenshots go to `.planning/screenshots/{campaign-slug}/` (if in a campaign)
   or `.planning/screenshots/` (if standalone)
2. In Codex, also register screenshots for the app artifact/browser workflow:
   ```bash
   node scripts/codex-app-artifacts.js record --workflow live-preview --kind screenshot --path ".planning/screenshots/{route-slug}.png" --status pass
   ```
3. Verify registered artifacts:
   ```bash
   node scripts/codex-app-artifacts.js verify --require-artifacts
   ```
4. Write a verification summary:
   ```markdown
   ## Visual Verification: {date}

   | Route | File Modified | Result | Notes |
   |-------|--------------|--------|-------|
   | /dashboard | Dashboard.tsx | PASS | Renders correctly |
   | /settings | SettingsPanel.tsx | FAIL → PASS | Fixed missing import, re-verified |
   | /profile | ProfileCard.tsx | BLANK → PASS | Component wasn't mounted, fixed export |
   ```

## Integration with Archon

When Archon delegates a build phase that modifies view files:

1. After the sub-agent completes, Archon invokes /live-preview on the modified routes
2. If any route is BLANK or FAIL, the phase is NOT marked complete
3. The fix cycle runs before proceeding to the next phase
4. This is part of Archon's Step 4 (Self-Correction) quality spot-check

## What This Prevents

- **Invisible features** (postmortem #17) — compiles but renders nothing
- **Layout regressions** — change in one component breaks another's layout
- **Empty states shipped as features** — data not connected, UI renders skeleton
- **"Works on my machine"** — screenshots are artifacts anyone can review

## Fringe Cases

- **Dev server is not running**: Offer to start it. Output: "Dev server not detected on localhost:{port}. Start it with `npm run dev` or equivalent, then re-run /live-preview." Do not attempt screenshots against a dead server.
- **Port is not 3000**: Check common alternatives (3001, 5173, 4173, 8080) before asking. Read `package.json` scripts for a `--port` flag or `PORT` env variable.
- **Screenshot tool unavailable** (Playwright not installed): Output what to check manually — list the modified routes, describe what each should render, and suggest installing Playwright: `npm i -D playwright`. Exit gracefully without crashing.
- **`.planning/screenshots/` does not exist**: Create the directory before writing artifacts. Never error on a missing output directory.
- **No view-layer files modified**: Exit immediately with "No view-layer files modified. Nothing to preview." This is expected and correct for non-UI repos.

## Contextual Gates

**Disclosure:** "Taking screenshots for visual verification. Images saved to `.planning/screenshots/`."
**Reversibility:** green — screenshots only; saves to `.planning/screenshots/`. No source files modified.
**Trust gates:**
- Any: full screenshot capture, verify, and fix workflow.

## Quality Gates

- Every modified view file must have a corresponding screenshot
- BLANK results are critical failures (never acceptable)
- Screenshots must be saved as artifacts (not just checked and discarded)
- Fix attempts capped at 2 per component (prevent infinite loops)

## Exit Protocol

```
---HANDOFF---
- Live Preview: {N} routes verified
- Results: {pass}/{total} passed
- Failures: {list of routes that failed and what was wrong}
- Screenshots: .planning/screenshots/{path}
- Reversibility: green — delete .planning/screenshots/ to remove artifacts; no source files modified
---
```

© SethGammon · MIT · SethGammon/Citadel

Similar skills

All skills for Frontend and UI →

From the same set55

The whole set →
loop loop — a skill for Claude Code and Codex that runs an action repeatedly and checks the result each time, stopping when verification passes or attempts run out. Useful for fixing lint errors or test failures in an active session. CX Codex +1 ★ 937repo stars marshal The marshal skill for Claude Code parses a task, gathers context from code and project memory, and chains skills. It runs in one session and asks only if it cannot continue. CX Codex +1 ★ 937repo stars test-gen test-gen is a Claude Code skill that generates and runs unit tests matching a project's existing framework, covering happy paths, edge cases, and failures. CX Codex +1 ★ 937repo stars design This skill builds a design manifest from a project’s styles or your preferences. A post-edit hook flags mismatches in edited files. CX Codex +1 ★ 937repo stars architect architect turns a PRD or task outline into an implementation plan with file trees, data models, and phased build steps. CX Codex +1 ★ 937repo stars cost See token usage and costs for sessions, campaigns, and time periods. Use it to check where spend is going and how quickly it is rising. CX Codex +1 ★ 937repo stars merge-review merge-review scans the fleet worktree merge queue, flags files touched by more than one branch, and suggests a merge order before anything lands in main. CX Codex +1 ★ 937repo stars deploy-steward deploy-steward serializes PR merges into main, tracks CI gates, triggers deploys, and files repair tasks when checks fail. CX Codex +1 ★ 937repo stars

Project sponsors

Companies that keep this analytics open