---
name: supastack
description: Build, configure, extend, test, and deploy AI SaaS applications across web (Next.js), mobile (Expo), and desktop (Tauri) with supastack. Use when working with a supastack repository or querying supastack documentation.
license: Commercial
compatibility: Requires Node.js >=22 and Corepack (pnpm). Supports Docker or Podman for local Postgres.
metadata:
  author: supastack
  version: "1.0"
---

# supastack skill

> [llms.txt](https://supastack.dev/llms.txt) · [llms-full.txt](https://supastack.dev/llms-full.txt)

Use this skill when a user asks to set up, configure, customize, test, or deploy a product built on supastack, or when querying supastack documentation.

## Discover content

- Documentation index: [https://supastack.dev/llms.txt](https://supastack.dev/llms.txt)
- Full corpus: [https://supastack.dev/llms-full.txt](https://supastack.dev/llms-full.txt)
- Skills discovery manifest: [https://supastack.dev/.well-known/agent-skills/index.json](https://supastack.dev/.well-known/agent-skills/index.json)
- Authentication and permissions: [https://supastack.dev/auth.md](https://supastack.dev/auth.md)
- Pricing: [https://supastack.dev/pricing.md](https://supastack.dev/pricing.md)
- OpenAPI document: [https://supastack.dev/openapi.json](https://supastack.dev/openapi.json)
- Docs MCP server: [https://supastack.dev/api/mcp](https://supastack.dev/api/mcp) (card: [https://supastack.dev/.well-known/mcp.json](https://supastack.dev/.well-known/mcp.json))
- Storefront MCP server: [https://supastack.dev/api/mcp/storefront](https://supastack.dev/api/mcp/storefront) (card: [https://supastack.dev/.well-known/mcp/storefront.json](https://supastack.dev/.well-known/mcp/storefront.json))
- Any guide as Markdown: append `.md` to its URL (for example [https://supastack.dev/docs/web/ship-in-5-minutes.md](https://supastack.dev/docs/web/ship-in-5-minutes.md)) or send `Accept: text/markdown`.

## Core workflows

- [Ship in 5 minutes (Web)](https://supastack.dev/docs/web/ship-in-5-minutes.md): Clone, bootstrap env, and launch the Next.js app locally.
- [Let an agent set it up](https://supastack.dev/docs/web/agent-setup.md): Unattended local and deployment runbook via `prompts/agent-setup.md`.
- [Build with a coding agent](https://supastack.dev/docs/web/agents.md): Context stack (`llms.txt`, `AGENTS.md`, `.ai/PROJECT_CONTEXT.md`), prompt library, and verification rules.
- [Agent skills](https://supastack.dev/docs/skills/overview.md): How `.agents/skills/` and `.claude/skills/` work inside the kit repository.
- [Set up external accounts](https://supastack.dev/docs/web/external-accounts.md): Step-by-step provider credentials for database, auth, billing, email, AI, jobs, and storage.

## In-repository Agent Skills (`.agents/skills/`)

Every supastack repository includes task-specific `SKILL.md` files under `.agents/skills/` (and `.claude/skills/`):

### Setup & environment

- **Local environment setup** (`local-environment-setup`) — use when bootstrapping or repairing the local environment: first clone, a missing or broken .env, Postgres, migrations or ports.
- **Deploy and env vars** (`deploy-and-env-vars`) — use when deploying, choosing a hosting target, or adding or changing an environment variable.
- **Adding a dependency** (`adding-a-dependency`) — use when adding, upgrading, moving or removing an npm dependency, or when CI fails the license or audit check.
- **Upgrading from upstream** (`upgrading-from-upstream`) — use when pulling a newer supastack release into a product built on it.

### Building features

- **Add a web feature** (`add-a-web-feature`) — use when adding a product page or section with its own data, server actions, navigation and tests.
- **Add an API endpoint** (`add-an-api-endpoint`) — use when adding or changing a public /api/v1 endpoint, its OpenAPI documentation or API-key scopes.
- **Add a UI component** (`add-a-ui-component`) — use when building a section, block, form control or reusable component that follows the kit's styling rules.
- **Change the theme or style** (`change-the-theme-or-style`) — use when changing how the product looks: a design style, color pack, density, radius, font or layout.
- **Add a marketing page or blog post** (`add-a-marketing-page-or-blog-post`) — use when adding or editing a public page, pricing page, legal page, blog post or docs guide.
- **Add a mobile screen** (`add-a-mobile-screen`) — use when adding or changing a screen in the Expo mobile app.
- **Add a desktop capability** (`add-a-desktop-capability`) — use when changing the Tauri desktop app: window, tray, global shortcut or auto-updates.
- **Add a notification** (`add-a-notification`) — use when adding an in-app notification, push notification or digest item.

### Auth & payments

- **Add an auth method** (`add-an-auth-method`) — use when changing sign-in: social providers, magic links, email codes, passkeys or two-factor.
- **Add a payment provider** (`add-a-payment-provider`) — use when activating a billing provider or writing a new billing adapter with checkout, customer portal and webhooks.
- **Change plans and pricing** (`change-plans-and-pricing`) — use when adding, renaming or repricing a plan: prices, trials, seats, entitlements, usage limits or credits.

### Data & integrations

- **Database schema change** (`database-schema-change`) — use when adding or changing a table, column, index or relation and generating the migration.
- **Add an AI feature** (`add-an-ai-feature`) — use when adding a model call, chat or agent tool, a durable AI task, budgets or bring-your-own-key.
- **Add a background job** (`add-a-background-job`) — use when adding work that runs after a request, on a timer or per workspace.
- **Add or edit an email** (`add-or-edit-an-email`) — use when adding or changing a transactional email or switching the provider that delivers it.
- **Use file storage** (`use-file-storage`) — use when adding uploads or stored files such as avatars, logos or attachments.
- **Add translations** (`add-translations`) — use when adding or changing user-facing text, translating it or adding a locale.

### Quality & shipping

- **Writing unit tests** (`writing-unit-tests`) — use when writing or fixing Vitest unit or integration tests.
- **Writing e2e tests** (`writing-e2e-tests`) — use when adding or fixing Playwright end-to-end tests, locally or in CI.
- **Verify changes** (`verify-changes`) — use before handing off, committing or opening a pull request to pick and run the right checks.
- **Debugging a failing CI run** (`debugging-a-failing-ci-run`) — use when a GitHub Actions run fails and you need to find and fix the cause.
- **Reviewing a PR** (`reviewing-a-pr`) — use when reviewing a pull request or diff for correctness, workspace isolation and conventions.

## Constraints

- Scope every user-owned database query and storage key by `workspaceId`.
- Keep provider secrets server-only (`packages/config`); never prefix secrets with `NEXT_PUBLIC_` or `EXPO_PUBLIC_` and never commit `.env*` files.
- Read `.ai/PROJECT_CONTEXT.md` and matching `.ai/` file mirrors before modifying code, and keep mirrors synced after changes.
- Run `corepack pnpm check` (lint, typecheck, unit tests, format check) to verify changes before handing off.