App builder
A repeatable way to take an idea to a deployed, tested, secure web app, on any stack. It was distilled
from building a real project end to end (an AI debate arena: Next.js, Drizzle, Better Auth, Vercel,
Turso, QStash, Vitest, Playwright), including every mistake made on the way. The core (this file,
profiles/, reference/) is stack-independent; what's specific to one product or framework lives
in stacks/ and is read only by projects that use it. Follow it; don't improvise the process.
Start here (every session)
- Find the project's state. If
docs/plan.mdexists, read it first: it records the profile, the decisions made and the current milestone. Continue from there; don't re-ask settled questions. - Pick the profile (new projects only). Ask once, in plain words:
"Do you want to be involved in technical choices (code, hosting, databases), or should I handle
those and only ask you about what the app does and how it looks?"
- Involved → read
profiles/technical.md - Hands-off → read
profiles/guided.mdRecord the answer indocs/plan.mdunder "How we work". The profile decides how you ask and explain; the process and the quality bar below are the same for both.
- Involved → read
- Read the stack notes the project uses (see "Stack notes" below).
- Read
reference/process.mdand follow its phases in order. Load the other references when a phase points to them, not all up front.
Stack notes
stacks/ holds one file per technology: setup steps, gotchas and fixes learned on real projects.
- Which to read: the plan's "How we work" section lists them ("Stack notes: nextjs, vercel, …").
Read exactly those at the start of each session. Also glance at the project's manifests
(
package.json,vercel.json,docker-compose.yml…) and the user's OS: if they use something with a note that the plan doesn't list, read it and add it to the list. New projects pick their notes when the stack is settled (process phase 2). - Make it unmissable: the project instructions file (
CLAUDE.mdorAGENTS.md, loaded in every session) says to readdocs/plan.mdand its stack notes at the start of each session, whatever the request. Otherwise a session that never triggers this skill never sees the list. The skill lives outside the repo, so word it to degrade gracefully: the plan is self-contained; the stack notes are read only "if the app-builder skill is installed". - Before adopting a new service or library, check whether a note exists.
- Where a new lesson goes: if it holds only when using a product, it goes in that product's note
(create one if there's none:
stacks/<product>.md, starting with "Load when…"). If it holds anywhere, it goes inreference/in generic terms, with the product as an example and a pointer to its note. Example: "retry once when a remote service drops an idle connection" is inreference/lessons.md; the libSQL fetch wrapper that does it is instacks/turso-libsql.md. - Notes record dated facts (limits, model lists, prices) as of when they were learned: re-check them.
Auditing an existing project
When asked to apply this skill to a project that already exists (or after a big change), don't restart the process; audit and report:
- Compare
docs/plan.mdwithtemplates/plan.mdand list missing sections. - Walk
reference/quality-gates.mdsection by section (security, resilience, performance with real measurements and Lighthouse, UI checklist, accessibility in both themes, operations and quotas). - Search the code for the anti-patterns in
reference/lessons.mdand the project's stack notes. - Ask the kickoff questions the project never answered (e.g. account lifecycle, quota abuse).
- Report gaps ranked (real gaps, plan gaps, low priority, what's already good), with fixes. Gaps the owner declines go into the plan's "Accepted risks" table. Change nothing until the owner agrees.
Non-negotiables (both profiles)
- Phases and milestones: work through the phases in
reference/process.md, building in small milestones that each end runnable, tested, demonstrated and committed before the next starts. Agree the milestone list with the user at kickoff and keep it current indocs/plan.md. - The app works as intended: every milestone ends runnable, demonstrated in a real browser, with the result shown to the user.
- Resilience: every external dependency and long-running process has a planned answer to "what if it fails?" (down, slow, rate-limited, crashed mid-way, delivered twice), recorded in the plan's failure-modes table, handled in code, visible to users in plain words, and tested.
- Performance: agreed targets (e.g. pages respond within a second near the audience), measured after deploy; no obviously wasteful work (unindexed queries, needless polling, oversized payloads).
- Quality: each milestone passes the gates in
reference/quality-gates.md(lint, types, unit tests, end-to-end tests, build, CI, the UI review checklist). No known major defect is left open. - Security: the security checklist in
reference/quality-gates.mdholds at every milestone, not as a final pass. - Maintainable design: business rules live in plain, framework-free modules with unit tests; external services sit behind small seams (one file to swap); the plan and README stay current.
- Tests at the right level: unit tests for rules, end-to-end browser tests for user flows, a scripted fake for any paid or slow external service (AI models, payments).
- Cost under control: the user's budget is explicit in the plan; anything that can cost money has a cap, a free tier with no card attached, or the user's own key.
- Secrets never pass through the chat: the user puts secrets into
.env.localand the hosting dashboard themselves, or a marketplace integration injects them (seereference/third-party-setup.md). - Verify it yourself first: after a change or deploy, check the result yourself (the browser, the hosting platform's logs and deploy status through its CLI, a probe script) before reporting or asking the user to look. Ask the user only for what needs them: signing in, secrets, money, approvals. Checking production yourself is how hidden bugs surface.
- Honest reporting: say what was verified and how, what wasn't, and what failed. Never claim a check you didn't run.
- Verify facts that change: prices, free-tier limits, library APIs and versions are checked
against current sources (docs in
node_modules, official pages) before relying on them, and the sources are cited.
Files in this skill
| File | Use it for |
|---|---|
profiles/technical.md | How to work with a technical owner: what to ask, what to decide and announce |
profiles/guided.md | How to work with a non-technical owner: language, choices, click-by-click instructions |
reference/process.md | The phases, from kickoff to handover, with what each must produce |
reference/quality-gates.md | Definition of done, testing strategy, resilience, performance, security and UI review checklists |
reference/stack-defaults.md | Default stack and architecture, budget tiers, when to deviate |
reference/environment.md | Pre-flight check and permission settings that remove most interruptions |
reference/third-party-setup.md | Accounts, secrets and configuring hosting/database/queue with minimal manual work |
reference/lessons.md | Concrete pitfalls already hit once, and their fixes, in stack-independent terms. Skim before each milestone |
templates/plan.md | Skeleton for the project's docs/plan.md |
Stack notes (read only when the project uses them):
| File | Covers |
|---|---|
stacks/nextjs.md | Next.js App Router, Cache Components, proxy, route handlers, server actions, React 19 forms, dev server |
stacks/vercel.md | Vercel hosting: regions, env vars and redeploys, CLI, logs, build-time setup |
stacks/turso-libsql.md | SQLite/libSQL with Drizzle, Turso: setup, migrations, remote fetch, dead idle connections |
stacks/better-auth.md | Better Auth: email confirmation, password reset, account linking, session gotchas |
stacks/upstash-qstash.md | Upstash QStash: local dev server, signatures, delays, schedules, quota |
stacks/ai-providers.md | Vercel AI SDK, Groq, Google AI Studio, OpenRouter (connect flow, free models), Ollama |
stacks/gmail-smtp.md | Sending account emails through Gmail without a domain |
stacks/playwright.md | Playwright end-to-end tests: selectors, hidden pages, local fakes |
stacks/github.md | GitHub repo, Actions CI, GitHub sign-in |
stacks/google-oauth.md | Google sign-in: Cloud project, consent screen, branding, one client for local and production |
stacks/windows.md | Developing on Windows: Smart App Control, PowerShell, Docker, CLIs |