# Web Studio

> One art-directed design studio in a box — an art-director agent commits direction, Claude builds, an image CLI renders media, a second model gates cost and reviews mechanically, then deploy + receipt. A 9-stage pipeline that turns a brief into a deployed, on-brand, non-slop website. Use when the user wants a new marketing/product/launch website built end-to-end, not for small edits to an existing site.

- Skill: `youkistudios/web-studio` (Agent Skill)
- Install (CLI): `npx skillmds@latest add youkistudios/web-studio`
- Raw SKILL.md: https://api.skillmd.com/api/skills/youkistudios/web-studio/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Marketing & Growth
- Author: youkistudios (https://skillmd.com/u/youkistudios)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/youkistudios/web-studio

---


# web-studio

Orchestration only — this skill does not itself design or write code. It asks
the questions in order, dispatches each stage to the right tool, and enforces
the gates. The creative judgment lives in the `the-designer` agent; the build
lives in Claude; validation lives in a second model.

## Setup check (once per environment — confirm, don't assume)

1. **The Designer**: confirm `the-designer` is a registered subagent (new
   files in `~/.claude/agents/` register at session start, not mid-session).
2. **Second model** (stages 4/6 — optional): if the OpenAI Codex CLI is
   installed, verify with
   `codex exec --skip-git-repo-check "reply OK" < /dev/null`.
   Any other model CLI works if it can take a prompt and return text
   synchronously. **If none is available: run those checks yourself,
   mechanically, and say so in the receipt** — don't skip them, don't
   pretend a second model ran.
3. **Image generation** (stage 3 — optional): any CLI/MCP that can generate
   an image from a text prompt. If it offers a cost-estimate command, always
   estimate before creating. If none is available, the site ships with
   CSS/SVG art direction instead of generated media — note it in the receipt.
4. **Fonts**: check the project's font choices against your font guide's
   license notes before shipping. Never ship a personal-use-only font on a
   commercial site.
5. **Studio Memory** (see docs/MEMORY.md): ensure `~/.web-studio/`
   exists with TASTE.md, PATTERNS.md, FAILURES.md, JOB-LOG.md; create empty
   files on first run and note the cold start in the run log. Never block
   on memory — but never skip the read/write contract either.
6. **The Library**: ensure `~/.web-studio/library/<project-slug>/` exists
   for this project (`brand/`, `images/`, `video/`, `source/`,
   `MANIFEST.md`) — the canonical home for every asset this run makes or
   receives. Supplied assets (logos, fonts, references) are copied into
   `brand/`/`source/` with a MANIFEST.md provenance line before anything
   else uses them.

## The questionnaire (ask one at a time, in order — do not batch)

1. **Mode** — best-quality (frontier model everywhere, no cost ceiling —
   the default) or **tiered**? Tiered means: the frontier model keeps the
   director and judge seats (stages 1, 2, 7), a cheaper model does the
   mechanical build (stage 5) with `DESIGN.md` + the signed direction as
   its complete brief, and the second model gates/reviews (stages 4, 6).
   Community benchmarks of this split report ~96% of all-frontier quality
   at roughly half the cost — the catch is discipline: the build model
   makes zero design decisions not already written in `DESIGN.md`.
2. **Site type** — product launch, brand/portfolio, dashboard,
   editorial/story-scroll, other?
3. **The one-line success test** — "When someone leaves this page, what's
   the single most important thing they should feel or do?" This is the
   pass/fail bar stage 7 scores against — not decoration.
4. **Design direction** — open-ended ("bold and vibrant") or "let the
   Designer pick."
5. **Brand input mode** — one of three:
   (a) **pure imagination** — no assets; the Designer invents the system.
   (b) **extract from a live reference** — the user names a live site whose
   standard they want matched: open it in a browser and *measure* it
   (computed palette, real font stacks, spacing rhythm) rather than
   describing it from memory; the extraction feeds stage 2's DESIGN.md.
   Match the standard, don't clone the site.
   (c) **reference contract** — the user has screenshots/URLs/taste notes:
   before any direction is committed, sort every reference into
   **Keep / Change / Do-not-copy** and record the sorting as a short
   contract in the project. References contribute structure and standards;
   identity stays original.
   In every mode, supplied fonts get a license check before use.
6. **The product description** — free text, the actual brief.
7. **Concepts** — 1 (recommended: get the first prompt right rather than
   paying for parallel iterations) or up to 3 for comparison.
8. **Media/audio** — generated media defaults to no audio (the single
   biggest render-cost lever). Confirm.
9. **Receipt destination** — on the site, in chat, or both (default both).

## The 9-stage run

Log every stage transition to `runs/<run_id>.jsonl` (schema in
`runs/README.md`). **A run with no log file didn't happen.**

1. **Spar** — first, initialize the project-scoped gate:
   `node ~/.claude/hooks/direction-gate.js --init <project_dir>` — from this
   moment, all Write/Edit into the project directory is machine-blocked.
   Then invoke `the-designer` with the questionnaire answers as the brief.
   It commits a one-sentence Direction Declaration and signs:
   `node ~/.claude/hooks/direction-gate.js --sign <project_dir> "<direction>"`
   (project-scoped — no session ids involved, so subagents can sign).
   **Halt if unsigned** — nothing downstream runs on an uncommitted
   direction. Persist the output as `DIRECTION-BRIEF.md` in the project.
2. **Brand shot** — same agent writes the project's `DESIGN.md`
   (templates/DESIGN-md-template.md — the official Google design.md spec
   shape: YAML token front matter + prose rationale) plus a complete
   art-direction brief for each media asset: subject, material, light,
   mood, crop, color story (hex-anchored), explicitly text-free. A bare
   noun prompt is never dispatched. Because the template is spec-shaped,
   **any conforming community design.md drops in as an alternative input**
   (see the template header) — but The Designer still signs a direction
   against it; a borrowed system never bypasses the gate. Input modes (b)
   and (c) from question 5 feed this stage.
3. **Render** — estimate cost first if the tool supports it; then generate.
   Audio off unless the questionnaire said otherwise. Log actual spend.
   **Save canonical-first:** the full-quality output lands in
   `~/.web-studio/library/<project>/images/` (or `video/`) with a
   MANIFEST.md line (prompt, model, credits, date) — the site folder gets
   a web-optimized derivative, never the only copy. **Check the shelf
   before spending:** if the library already holds a usable asset for this
   brief (earlier run, earlier concept), reuse it — never re-generate what
   exists. **If render succeeds and a later stage fails, never silently
   re-render** — report spend and ask before spending more.
4. **Gate** — second model audits the render plan + running spend. Prompt it
   to reply in exactly: `FLAGS: <none|list> | BUDGET_OK: <yes|no> | NOTE:
   <one line>`. Zero design opinions — discard any aesthetic suggestion.
5. **Build** — the site is built per `DESIGN.md`: its palette verbatim,
   its type pairing, its signature moves, its taste rules. Self-hosted
   fonts, semantic HTML, responsive by default, `prefers-reduced-motion`
   respected. In tiered mode (question 1), the cheaper model builds here
   from `DESIGN.md` alone — if it needs a design decision the file doesn't
   answer, that's a stage-2 gap: route the question to The Designer, don't
   let the build model improvise. **Commit a checkpoint.**
6. **Review** — three passes, in order — *measure before you judge*:
   (a) **programmatic checks** — serve the site over HTTP (never `file://`
   — stale-snapshot risk) and run `scripts/visual-checks.js` in the page
   console at mobile (375px) and desktop (1280px) widths: viewport
   overflow, whole-page horizontal scroll, broken images, sub-40px tap
   targets. Collect console errors via your tool. Findings feed the
   review; they don't replace it.
   (b) second model checks links, receipt math, brief consistency — plus
   the programmatic findings — same no-design-opinions rule;
   (c) **actually look at the rendered page** at desktop AND mobile widths.
   Fix what's broken, re-check from (a), **commit a checkpoint.**
7. **Verify** — mechanical pre-flight first, judgment second. The Designer
   loads the Studio Memory at stage 1 and writes back here: on PASS ≥7.5,
   pattern → `~/.web-studio/PATTERNS.md`, case study →
   `~/.web-studio/JOB-LOG.md` (plus the project's own job log) — **paths
   stated in the output or the write-back didn't happen.** Mechanics:
   run a checkable sweep before invoking The Designer — default-palette
   tells (the stock purple/indigo-gradient family on dark, unmodified
   template blues), centered-stack layouts where the direction called for
   asymmetry, CTA contrast below WCAG AA, more than one competing CTA
   intent per viewport, motion breaking the DESIGN.md motion policy
   (non-transform/opacity animation, entries over 300ms, missing
   reduced-motion fallback). Checkable failures never spend judgment time.
   Then `the-designer` in QA mode: craft rubric, its named
   anti-patterns, a polish pass, PASS/FLAG with a numeric score. On PASS
   ≥7.5/10, append the case study to the project's job log and **state the
   file path in the output** — a verify step with no named log path didn't
   happen. Below 7.5 or hard FLAG: report the specific flags, don't
   silently patch and re-ship.
8. **Deploy** — ship it (any host; if your image tool has its own site
   hosting, that works too). Localhost is not done. Custom domain is a
   question, not an assumption.
9. **Receipt** — write `COST-RECEIPT.md` (templates/COST-RECEIPT-template.md):
   models used, actual credits/tokens spent per the run log (never an
   estimate), audio decision + why, deploy URL, total. Deliver per the
   questionnaire's answer.

## Iteration rule

If the user rejects the output ("bland", "not it"), that's a stage 5–7 loop,
not a restart: the Direction Declaration and `DESIGN.md` survive unless the
user rejects the *direction itself*. Ask which it is if unclear. **Log the
rejection to `~/.web-studio/TASTE.md` immediately** — one calibration line
(what was rejected, in what register, what to start with next time), plus a
FAILURES.md entry when the rejected move is specific. Rejections are the
highest-value taste data the studio ever receives; a rejection without a
taste line will be repeated on the next build.

## Non-goals

- Small edits to an existing site — invoke `the-designer` directly, skip
  the 9-question intake.
- This skill never makes a design decision itself. Every aesthetic call
  routes to the Designer.
- Never ship a font whose license you haven't checked.