Skill files

Skill files are the core of the build package. Each one is a focused instruction document that teaches your AI exactly how to implement one domain of your app — from data models to edge cases to the specific libraries to use.

What is a skill file?

A skill file is a markdown document placed in /skills/. Your AI IDE reads all of them before writing any code. Think of each file as a senior engineer's handoff note for one part of the system.

Unlike a generic README or documentation, skill files are generated specifically for your app — they reference your data models, your user persona from the validation, and the decisions made in project.md.

What's in each file

Every skill file follows the same structure:

• Overview — what this domain does in this app
• Stack decisions — which libraries/services to use and why
• Data models — tables, types, and relationships relevant to this domain
• Implementation patterns — how to structure the code for this domain
• Edge cases — gotchas, error states, and things to handle explicitly
• What NOT to do — anti-patterns to avoid

The skill files generated for your app

skill-core-app.md

Always included. Covers the main app shell — Next.js app router structure, shared layouts, navigation, loading states, error boundaries, and global conventions like naming, file organization, and component patterns.

skill-auth.md

Supabase auth setup, session management, protected routes, middleware, the sign-in/sign-up flow, email confirmation, password reset, and OAuth providers. Includes the user profile table pattern.

skill-billing.md

Stripe integration, subscription plans, usage gating, webhook handling, the customer portal, and how to gate features behind plan level. Includes the Supabase subscription sync pattern.

Domain-specific skills (2–4 files)

The platform generates additional skill files based on what your specific app needs. Examples:

• skill-notifications.md — email/push delivery, queuing, preferences
• skill-search.md — full-text search, filters, pagination patterns
• skill-ai-integration.md — prompt patterns, streaming responses, cost controls
• skill-file-uploads.md — Supabase Storage, size limits, type validation
• skill-analytics.md — event tracking, dashboards, retention metrics
• skill-api.md — public API design, rate limiting, key management

Adding your own skill files

Drop any skill-*.md file into the /skills/ folder. As long as CLAUDE.md instructs the AI to read everything in /skills/, it will pick it up automatically in the next session.

Use this to add context the generator didn't know about — a third-party API you're integrating, a specific design system, company coding conventions, or a domain the AI keeps getting wrong.

# skill-my-integration.md

## Overview
This app integrates with the Acme API for X.

## Auth
Use API key stored in ACME_API_KEY env var.
Never expose this client-side.

## Key endpoints
- POST /jobs — create a processing job
- GET /jobs/:id — poll for completion

## Error handling
Acme returns 429 on rate limit. Implement
exponential backoff with max 3 retries.

## What NOT to do
Do not use the webhook endpoint — it requires
a paid plan we don't have yet.