CommunityCoding & Developmentgithub.com

app-builder

Plan, build, test, secure and deploy a small full-stack web app from an idea to a live site, with few interruptions. Use when someone wants to start a new app or project, says "build me an app", "I have an idea for a website", "start a new project", or continues a project created with this skill (its docs/plan.md says so). Has two profiles - technical (asks only about fundamental or budget-dependent decisions) and guided (for non-technical owners - plain language, product decisions only).

What is app-builder?

app-builder is a Claude Code agent skill that plan, build, test, secure and deploy a small full-stack web app from an idea to a live site, with few interruptions. Use when someone wants to start a new app or project, says "build me an app", "I have an idea for a website", "start a new project", or continues a project created with this skill (its docs/plan.md says so). Has two profiles - technical (asks only about fundamental or budget-dependent decisions) and guided (for non-technical owners - plain language, product decisions only).

Works with✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/r-dziewaltowski/app-builder/tree/HEAD/plugins/app-builder/skills/app-builder

Installed? Explore more Coding & Development skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Ask in your favorite AI

Open a new chat with this agent skill pre-loaded.

Documentation

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)

  1. Find the project's state. If docs/plan.md exists, read it first: it records the profile, the decisions made and the current milestone. Continue from there; don't re-ask settled questions.
  2. 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.md Record the answer in docs/plan.md under "How we work". The profile decides how you ask and explain; the process and the quality bar below are the same for both.
  3. Read the stack notes the project uses (see "Stack notes" below).
  4. Read reference/process.md and 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.md or AGENTS.md, loaded in every session) says to read docs/plan.md and 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 in reference/ 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 in reference/lessons.md; the libSQL fetch wrapper that does it is in stacks/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:

  1. Compare docs/plan.md with templates/plan.md and list missing sections.
  2. Walk reference/quality-gates.md section by section (security, resilience, performance with real measurements and Lighthouse, UI checklist, accessibility in both themes, operations and quotas).
  3. Search the code for the anti-patterns in reference/lessons.md and the project's stack notes.
  4. Ask the kickoff questions the project never answered (e.g. account lifecycle, quota abuse).
  5. 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 in docs/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.md holds 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.local and the hosting dashboard themselves, or a marketplace integration injects them (see reference/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

FileUse it for
profiles/technical.mdHow to work with a technical owner: what to ask, what to decide and announce
profiles/guided.mdHow to work with a non-technical owner: language, choices, click-by-click instructions
reference/process.mdThe phases, from kickoff to handover, with what each must produce
reference/quality-gates.mdDefinition of done, testing strategy, resilience, performance, security and UI review checklists
reference/stack-defaults.mdDefault stack and architecture, budget tiers, when to deviate
reference/environment.mdPre-flight check and permission settings that remove most interruptions
reference/third-party-setup.mdAccounts, secrets and configuring hosting/database/queue with minimal manual work
reference/lessons.mdConcrete pitfalls already hit once, and their fixes, in stack-independent terms. Skim before each milestone
templates/plan.mdSkeleton for the project's docs/plan.md

Stack notes (read only when the project uses them):

FileCovers
stacks/nextjs.mdNext.js App Router, Cache Components, proxy, route handlers, server actions, React 19 forms, dev server
stacks/vercel.mdVercel hosting: regions, env vars and redeploys, CLI, logs, build-time setup
stacks/turso-libsql.mdSQLite/libSQL with Drizzle, Turso: setup, migrations, remote fetch, dead idle connections
stacks/better-auth.mdBetter Auth: email confirmation, password reset, account linking, session gotchas
stacks/upstash-qstash.mdUpstash QStash: local dev server, signatures, delays, schedules, quota
stacks/ai-providers.mdVercel AI SDK, Groq, Google AI Studio, OpenRouter (connect flow, free models), Ollama
stacks/gmail-smtp.mdSending account emails through Gmail without a domain
stacks/playwright.mdPlaywright end-to-end tests: selectors, hidden pages, local fakes
stacks/github.mdGitHub repo, Actions CI, GitHub sign-in
stacks/google-oauth.mdGoogle sign-in: Cloud project, consent screen, branding, one client for local and production
stacks/windows.mdDeveloping on Windows: Smart App Control, PowerShell, Docker, CLIs

Related Skills