SvelteKit Webapp Skill

Scaffold production-ready SvelteKit PWAs with opinionated defaults and guided execution.

Quick Start

1. 1. Describe your app — Tell me what you want to build
2. Review the PRD — I'll generate a plan with user stories
3. Approve — I build, test, and deploy with your oversight
4. Done — Get a live URL + admin documentation

"Build me a task tracker with due dates and priority labels"

That's all I need to start. I'll ask follow-up questions if needed.

Prerequisites

These CLIs must be available (the skill will verify during preflight):

CLI	Purpose	Install
INLINECODE0	SvelteKit scaffolding	INLINECODE1 (or use via pnpx)
INLINECODE3

Package manager | npm i -g pnpm |
| gh | GitHub repo creation | cli.github.com |
| vercel | Deployment | npm i -g vercel |

Optional (if features require):

• - turso — Turso database CLI

Opinionated Defaults

This skill ships with sensible defaults that work well together. All defaults can be overridden via SKILL-CONFIG.json:

• - Component library: Skeleton (Svelte 5 native) + Bits UI fallback
• Package manager: pnpm
• Deployment: Vercel
• Add-ons: ESLint, Prettier, Vitest, Playwright, mdsvex, MCP
• State: Svelte 5 runes ($state, $derived, $effect)

See User Configuration for override details.

---

User Configuration

Check ~/.openclaw/workspace/SKILL-CONFIG.json for user-specific defaults before using skill defaults. User config overrides skill defaults for:

• - Deployment provider (e.g., vercel, cloudflare, netlify)
• Package manager (pnpm, npm, yarn)
• Add-ons to always include
• MCP IDE configuration
• Component library preferences

Workflow Overview

1. 1. Gather: Freeform description + design references + targeted follow-ups
2. Plan: Generate complete PRD (scaffold, configure, features, tests as stories)
3. Iterate: Refine PRD with user until confirmed
4. Preflight: Verify all required auths and credentials
5. Execute: Guided build-deploy-verify cycle with user checkpoints (development → staging → production)

---

Phase 1: Gather Project Description

A conversational, iterative approach to understanding what the user wants.

1a. Freeform Opening

Start with an open question:

• - "What do you want to build?"
• "Describe the webapp you have in mind"

Let the user lead with what matters to them.

1b. Design References

Ask for inspiration:
CODEBLOCK0

"Show me what you like" communicates more than paragraphs of description.

1c. Visual Identity (Optional)

If design references suggest custom branding, ask:
CODEBLOCK1

1d. Targeted Follow-ups

Based on gaps in the description, ask specifically:

Gap	Question
Users unclear	"Who's the primary user? (role, context)"
Core action unclear

"What's the ONE thing they must be able to do?" |
| Content unknown | "Any existing content/assets to incorporate?" |
| Scale unknown | "How many users do you expect? (ballpark)" |
| Timeline | "Any deadline driving this?" |

Only ask what's missing—don't interrogate.

1e. Structured Summary

Before proceeding, confirm understanding:

CODEBLOCK2

Iterate until the user confirms.

---

Phase 2: Plan (Generate PRD)

Generate a complete PRD with technical stack, user stories, and mock data strategy.

Technical Stack

Always Included:
CODEBLOCK3

Why Skeleton + Bits UI?

• - Skeleton: Full-featured component library built for Svelte 5, accessible by default
• Bits UI: Headless primitives when you need more control or custom styling
• Both play well together — Skeleton for speed, Bits for flexibility

Inferred from Description:
CODEBLOCK4

State Management

Follow Svelte 5 best practices (see https://svelte.dev/docs/kit/state-management):

• - Use $state() runes for reactive state
• Use $derived() for computed values
• Use Svelte's context API (setContext/getContext) for cross-component state
• Server state flows through load functions → data prop
• Never store user-specific state in module-level variables (shared across requests)

Code Style Preferences

Check SKILL-CONFIG.json for user preferences. Common patterns:

• - Prefer bind: over callbacks — For child→parent data flow, use bind:value instead of onchange callback props. More declarative, less boilerplate.
• Avoid onMount — Use $effect() for side effects. It's reactive and works with SSR.
• Runes everywhere — $state(), $derived(), $effect() over legacy stores and lifecycle hooks.
• Small components — Default soft limit of ~200 lines per component (configurable in SKILL-CONFIG.json). If growing larger, extract sub-components. Small is beautiful. 🤩

Directory Structure

INLINECODE26 generates:
CODEBLOCK5

We add:
CODEBLOCK6

User Stories (prd.json)

Story structure:
CODEBLOCK7

Story sizing rule: Each story must fit in one context window. If it feels big, split it.

Standard story sequence:

1. 1. Scaffold — pnpx sv create, add core add-ons
2. Configure — Skeleton + Bits UI, PWA, directory structure, VSCode workspace, Tailwind theme
3. Mock Data — Set up mock database/fixtures for development
4. Foundation — Root layout, design tokens, home page (INDEX PAGE CHECKPOINT)
5. Features — Core features from gathered requirements
6. Infrastructure — Database schema, migrations, auth (if needed)
7. Polish — PWA manifest, icons
8. Tests — E2E tests for critical flows

Index Page Checkpoint: After the index/home page is built (but before other pages), PAUSE execution and request user review. The index page establishes the visual direction—getting early feedback here avoids wasted work on subsequent pages.

See references/scaffold-stories.md for story templates.

Mock Data Strategy

Development uses mock data; production uses real database.

CODEBLOCK8

When drizzle is selected, include stories for:

• - Initial schema creation
• Drizzle Kit configuration
• First migration

External Dependencies

Identify required credentials:

Feature	Dependency	Required
Any project	GitHub CLI	Yes
Deployment

Vercel CLI or adapter-auto | Yes |
| Database (postgres) | DATABASE_URL | For staging |
| Database (turso) | Turso CLI | For staging |
| OAuth providers | Client ID/Secret | For staging |
| Payments | Stripe API keys | For staging |

Dev uses mocks; staging/production need real credentials.

---

Phase 3: Iterate Until Confirmed

Present the PRD and refine until the user approves.

Present the PRD

CODEBLOCK9

Iteration Loop

Expect refinement. Common adjustments:

• - Add/remove/modify user stories
• Change technical stack choices
• Adjust story priorities
• Split stories that are too large
• Add acceptance criteria

Continue iterating until user explicitly approves.

Confirmation

When user approves:

✅ PRD CONFIRMED

[N] user stories ready for execution.
Proceeding to preflight checks...

---

Phase 4: Preflight

Verify all dependencies. Development can start with mocks; staging needs real credentials.

Run Checks

Verify authentication for required CLIs (GitHub, pnpm, Vercel, and optionally Turso). See references/cli-commands.md for specific commands.

Present Status

CODEBLOCK11

Resolution

• - Development can proceed with mock data
• Staging credentials can be resolved during Stage 1
• Production credentials verified before Stage 3

---

Phase 5: Execute

Guided build-deploy-verify cycle with user checkpoints and live progress updates.

CODEBLOCK12

Live progress updates: Report each completed story:

✅ US-001: Scaffold project
✅ US-002: Configure Skeleton + Bits UI
✅ US-003: Set up mock data
⏳ US-004: Create root layout (in progress)

---

Stage 1: Development

Build everything locally with mock data.

Setup

Initialize a git repository on a dev branch and create a progress.txt tracking file. See references/cli-commands.md for commands.

Execute Stories via Sub-Agents

Use sessions_spawn to execute stories in parallel where dependencies allow.

Wave structure:

• - Wave 1: Scaffold (must complete first)
• Wave 2: Configure (shadcn, PWA, directories) — parallel
• Wave 3: Mock data setup
• Wave 4+: Feature stories — parallel where independent
• Final wave: E2E test stories

Sub-agent task template:
CODEBLOCK14

Handling Blocked Stories

If a story cannot be completed:

1. 1. Mark as blocked: true in prd.json
2. Add explanation to notes field
3. Continue with other parallelizable stories
4. Report blocked stories in final summary

Stage 1 Exit Criteria

All checks must pass before proceeding: TypeScript verification, unit tests, and E2E tests against the local dev server with mocks. See references/cli-commands.md for commands.

---

Stage 2: Staging

Push to main, deploy to preview, switch from mocks to real data.

Verify Staging Credentials

Before proceeding, ensure all staging credentials are set:

• - DATABASE_URL (if using database)
• OAuth client ID/secret (if using auth)
• Other API keys

If missing, pause and request from user.

Deploy via GitHub-Vercel Integration

One-time setup (recommended over CLI deploys):

Create a private GitHub repository, link to a Vercel project, and connect GitHub in the Vercel dashboard (Settings → Git → Connect Git Repository). Set the production branch to main. See references/cli-commands.md for commands.

Benefits of GitHub integration:

• - Push to deploy (no CLI needed after setup)
• Automatic preview URLs for all branches
• Persistent branch URLs: INLINECODE35
• Better CI/CD visibility in both dashboards

Deploy to staging:

Merge the dev branch into main and push. The push triggers Vercel to build and deploy automatically. See references/cli-commands.md for commands.

Dev branch preview URL:
After connecting GitHub, the dev branch gets a persistent preview URL:
INLINECODE39

This URL stays the same across commits—great for sharing with stakeholders.

Fix Environment Issues

Common issues in deployed environments:

• - OAuth callback URLs (must match deployed domain)
• CORS configuration
• Environment variables not set in Vercel
• Database connection strings
• API endpoints using localhost

Smart retry logic:

1. 1. Diagnose error type from stdout/stderr
2. Attempt fix based on error:

- Dependency error → pnpm install
- Type error → analyze pnpm check output
- Test failure → re-run with verbose logging
- Network/timeout → wait 30s, retry

1. 3. Escalate after 3 failed attempts

Stage 2 Exit Criteria

E2E tests must pass against the Vercel preview URL. See references/cli-commands.md for commands.

---

Stage 3: Production

Deploy to production URL and hand off to user.

Deploy Production

With GitHub-Vercel integration, production deploys automatically when you push to main. Custom domains can be configured via the Vercel dashboard (Settings → Domains) or CLI. See references/cli-commands.md for commands.

Final Verification

Run E2E tests against the production URL to confirm everything works. See references/cli-commands.md for commands.

Completion Report

CODEBLOCK15

---

Phase 6: Handoff

Provide lifecycle management documentation.

Generate Admin Manual

Create ADMIN.md in project root:

CODEBLOCK16

Report Handoff

CODEBLOCK17

---

Error Handling

If any stage fails and cannot be automatically resolved:

1. 1. Diagnose: Analyze error output
2. Categorize:

- Dependency → pnpm install - Type error → show specific errors - Test failure → show failing tests - Network → retry with backoff

1. 3. Retry: Up to 3 attempts with appropriate fix
2. Escalate: Report to user with:

- What failed - What was tried - Specific error messages - Suggested manual resolution

Never leave the project broken. If Stage 2/3 fails, dev branch still works.

---

Quick Reference

For all CLI commands and auth checks, see references/cli-commands.md.

Default Adapter

Use adapter-auto — automatically detects:

• - Vercel → adapter-vercel
• Cloudflare → adapter-cloudflare
• Netlify → adapter-netlify
• Otherwise → adapter-node

Database Options (drizzle)

• - postgresql + postgres.js or INLINECODE48
• INLINECODE49 + better-sqlite3 or INLINECODE51
• INLINECODE52 + INLINECODE53