Ship Full-Stack Apps with AI Guidance

This is a template project-specific skill, based on a real production app (Zenith, an AI-powered customer discovery platform), showing the shape a project skill should take: architecture overview, file structure, code patterns, testing requirements, and deployment workflow, all specific to one codebase rather than generic advice.

Reference a skill like this when working on the specific project it's designed for - project skills exist to capture a codebase's actual stack, structure, patterns, and rules rather than general best practices. Use this example as a template for writing an equivalent skill for your own project, not as generic guidance for an unrelated codebase.

The example project's stack: Next.js 15 (App Router) + TypeScript + React frontend, FastAPI (Python)/Pydantic backend, Supabase (PostgreSQL) database, Claude API with tool calling and structured output, deployed to Google Cloud Run, tested with Playwright (E2E), pytest (backend), and React Testing Library. The architecture diagram shows the frontend calling the backend, which in turn talks to Supabase, the Claude API, and a Redis cache. File structure separates frontend/src (app router pages, components, hooks, lib, types, config) from backend (routers, models.py, main.py, auth_system.py, database.py, services, tests), alongside top-level deploy/, docs/, and scripts/ directories.

Named code patterns include a generic ApiResponse[T] Pydantic model with .ok()/.fail() constructors on the backend and a matching TypeScript fetchApi<T>() helper on the frontend, a Claude structured-output call using client.messages.create() with a tool_choice forcing a provide_analysis tool call validated against a Pydantic schema, and a useApi<T>() React hook wrapping loading/error state around any fetch function. Testing runs via poetry run pytest tests/ (backend) and npm run test / npm run test:e2e (frontend). Deployment follows a pre-deployment checklist (tests passing, npm run build succeeds, no hardcoded secrets, documented env vars, migrations ready) then deploys both services with:

cd frontend && npm run build
gcloud run deploy frontend --source .

cd backend
gcloud run deploy backend --source .

Eight critical rules apply throughout: no emojis in code/comments/docs, immutability (never mutate objects or arrays), TDD (tests before implementation), 80% minimum coverage, many small files (200-400 lines typical, 800 max), no console.log in production code, proper try/catch error handling, and input validation via Pydantic/Zod.

Teams who want a concrete template for writing their own project-specific skill - capturing a real stack, file layout, code patterns, test commands, and deployment steps - rather than starting from a blank page or relying on generic coding-standards advice.