skillz

Use when implementing background jobs, task queues, scheduled jobs, retries, or any Redis-backed async worker in a Python backend service in this harness. arq is the chosen queue (async-native, Redis-backed). Replaces the old bullmq skill.

Use when creating a new branch, starting new feature work, fixing a bug on a new branch, or any situation where a branch needs to be created. Use when the user asks to "create a branch", "start a new branch", "branch off of X", or "make a branch for this work".

Use when creating CI/CD pipelines for any project. Use when asked to "set up CI/CD", "create a pipeline", "automate deployments", "configure GitHub Actions", "set up Vercel/Render/AWS", or similar. The harness is a polyglot monorepo — a Python (FastAPI + uv) backend in `apps/api/` and a TypeScript (Vite + pnpm) frontend in `apps/web/`. Pipelines run the two stacks as parallel lanes that join at a final gate.

Use when writing, reviewing, or editing a Dockerfile or docker-compose file. Use when asked to "containerize", "dockerize", "add Docker support", or "write a Dockerfile" for any application or service in this harness — FastAPI backend (Python + uv) or Vite frontend (TypeScript + pnpm, served as static assets).

Use when writing, reviewing, or refactoring TypeScript code on the frontend — especially when tempted to use `any`, type assertions, unvalidated casts, or when designing types, generics, utility types, or tsconfig settings. Backend code in this harness is Python, not TypeScript; see `effective-python` / `python-linting` for the backend equivalents.

FastAPI implementation guide. Load whenever building or modifying any backend HTTP service in this harness — defining routes, request/response models, dependencies, middleware, error handlers, lifespan events, or background tasks. Triggers include: APIRouter, Depends, FastAPI app instance, response_model, OpenAPI generation, async endpoint handlers. Use alongside `sqlalchemy`, `pydantic`, and `rest-api-design`.

Use when the developer advocate needs to verify the application can be cloned and run by a new engineer. Triggers include: adding a new application or service, changing docker-compose or Dockerfiles, changing environment variable handling, changing networking between services, adding or modifying Makefile targets / uv / pnpm scripts, changing the Python or Node toolchain pin, changing database schemas or Alembic migrations, or changing README/setup documentation.

Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, artifacts, posters, or applications (examples include websites, landing pages, dashboards, React components, HTML/CSS layouts, or when styling/beautifying any web UI). Generates creative, polished code and UI design that avoids generic AI aesthetics.

Use when setting up ESLint and/or Prettier in the Vite + React + TypeScript frontend, adding linting to an existing frontend codebase, or configuring typescript-eslint, eslint-config-prettier, or related packages. Backend (Python) linting lives in the python-linting skill.

Use when writing any documentation — API references, guides, feature overviews, changelogs, or README files — intended to be read by humans in raw markdown or rendered form.

Use when creating, reading, updating, listing, searching, transitioning, or commenting on issues or tickets. Use when the user references a ticket ID, issue number, or asks to "open an issue", "close a ticket", "add a comment", "list issues", "search for tickets", "transition to in progress", or similar.

Kubernetes manifest authoring guidelines. Load this skill when creating or reviewing Kubernetes manifests for any service. Covers when to use Kubernetes, manifest structure, resource limits, health probes, and provider-agnostic conventions.

Use when laying out a new repo, adding services, wiring up cross-app scripts, or troubleshooting "how do I run X from the root" questions. The harness is a polyglot monorepo with a Python (FastAPI + uv) backend in `apps/api/` and a TypeScript (Vite + React + pnpm) frontend in `apps/web/`. Each side keeps its own toolchain; the root only coordinates.

Use when building or modifying multi-tenant features in a FastAPI + SQLAlchemy backend in this harness — shared database with tenant isolation, per-request tenant context, query scoping, or any code where one deployment serves multiple organizations/tenants. Triggers include tenant_id, organization_id, workspace isolation, tenant-scoped queries, cross-tenant data leak risk, JWT tenant claims.

Observability standards and instrumentation conventions. Load this skill when reviewing code for observability gaps, or when implementing logging, metrics, tracing, or health checks. Covers the four observability signals and stack-specific conventions for each supported language.

Use whenever a backend endpoint is created or modified, or whenever the frontend needs to call an API, or when verifying that the OpenAPI spec matches the running API. Backend services in this harness are FastAPI — the OpenAPI spec is auto-generated from Pydantic models, no codegen runs on the backend. The frontend uses openapi-typescript + openapi-fetch to generate a typed client from the running FastAPI's /openapi.json. Covers the full contract, the service/hook layer, and spec verification.

Use when implementing any feature that requires multiple collaborating modules, services, or classes. Use when a task involves dependencies that do not yet exist. Use alongside the tdd skill.

Use when a PR has been opened and CI/pipeline checks must be monitored before declaring the task complete. Use when asked to "watch the pipeline", "wait for CI", "make sure checks pass", or "don't declare done until CI is green". Apply after every PR is opened.

Use when you need to ask the user clarifying questions, gather requirements, make a decision that requires user input, or confirm anything before proceeding with a task.

Automates browser interactions for web testing, form filling, screenshots, and data extraction. Use when the user needs to navigate websites, interact with web pages, fill forms, take screenshots, test web applications, or extract information from web pages.

Use when writing Playwright e2e tests for scenarios that genuinely require a real browser against a real backend — OAuth flows, cookie/session mechanics, file downloads, drag-and-drop, or a documented critical path where lower-level tests have failed to catch a regression. Do NOT use for form validation, error states, loading states, or any scenario fully coverable with RTL+MSW.

Use when designing or modifying a PostgreSQL database schema, adding tables or columns, creating indexes, writing migrations, or making any structural database change. The data layer in this harness is SQLAlchemy 2.0 async + Alembic. Use alongside the `sqlalchemy` skill (which covers querying, eager loading, transactions).

Use when opening, updating, or listing pull requests. Use when asked to "open a PR", "create a pull request", "submit for review", or "raise a PR". Apply when work on a feature branch is complete and ready for review.

Use when adding or modifying environment variable handling in any Python backend service. Triggers include adding a new env var, replacing direct os.environ / os.getenv access, sharing a settings module across packages, or fixing "missing env var" errors. Replaces the old zod-env approach for the Python backends in this harness.

Pydantic v2 patterns for request/response schemas, validators, and data conversion in FastAPI services. Load when defining BaseModel classes, designing API schemas, writing field validators, or converting between SQLAlchemy models and Pydantic schemas. Use alongside `fastapi` and `pydantic-settings` (the latter handles env vars specifically).

Use when setting up Ruff and mypy in a Python backend service, adding linting/formatting/type-checking to an existing Python codebase, or configuring pyproject.toml for code quality tooling. Backend services in this harness use Ruff (lint + format) and mypy (strict type-check). Frontend linting lives in the frontend-linting skill.

Use when designing, reviewing, or documenting HTTP REST API endpoints, resources, contracts, or schemas.

shadcn/ui component library guide for the Vite + React frontend in this harness. Load whenever building UI from primitive components, adding a new shadcn component, customising one, or composing forms, modals, tables, and dropdowns. Pairs with `tailwind` (the styling system shadcn is built on) and `vite-react` (the project skeleton).

SQLAlchemy 2.0 async ORM implementation guide. Load whenever working with database access, models, queries, transactions, or relationships in any backend service in this harness. Covers the typed Mapped[] API, the async engine and session, eager loading and N+1 avoidance, transactions, soft deletes, pagination, and error handling. Use alongside `postgres-schema-design` for schema decisions and Alembic migrations.

Stripe payments integration guide for the FastAPI + SQLAlchemy + React stack in this harness. Load whenever implementing payments, subscriptions, billing, webhooks, or the customer portal. Covers SDK setup, products/prices, checkout sessions, webhook handling with idempotency, subscription lifecycle, and the customer portal. Backend uses the official `stripe` Python SDK; the frontend redirects to Stripe-hosted Checkout/Portal and never holds card data.

Use when an agent needs to understand how the application behaves before writing tickets, scoping features, or describing current functionality. Use when docs/ domain files exist or need to be bootstrapped from existing issues or stories.

Tailwind CSS conventions for the Vite + React frontend in this harness. Load whenever styling components, configuring tailwind.config.ts, choosing utility classes, deciding when to extract a component, or working with the design-token system. Pairs with `shadcn-ui` (component library) and `vite-react` (frontend skeleton).

TanStack Query (React Query v5) implementation guide. Load whenever fetching, caching, or mutating server data in a React application. Covers setup, query key strategy, useQuery, useMutation, optimistic updates, pagination, and prefetching. Use whenever you see @tanstack/react-query imports or when implementing data fetching that needs caching, loading states, or invalidation.

Use when writing any code — functions, modules, APIs, UI components, scripts, or any other implementation. Use when asked to "implement", "build", "write", "add", "create", or "refactor" anything that involves code. Covers the universal red-green-refactor discipline plus stack-specific testing patterns for the Python (FastAPI + SQLAlchemy) backend and the Vite + React + TypeScript frontend in this harness.

Use when sending a Telegram notification on task completion or when a task is blocked. Defines message format and delegates to the send-telegram tool.

React UI design principles and conventions for the Vite + React + Tailwind + shadcn/ui frontend in this harness. Load when building or modifying any user interface or React components. Covers visual standards, component decomposition, accessibility, responsiveness, state management, data fetching via TanStack Query, and in-app help patterns.

Use whenever creating or modifying a Vite + React + TypeScript frontend in this harness. Covers project skeleton, env vars, react-router-v7, build/dev commands, project structure, and the data-fetching architecture (TanStack Query + openapi-fetch + service layer). Pairs with `tailwind`, `shadcn-ui`, `tanstack-query`, `openapi-codegen`, and `frontend-linting`.

Use when creating a new skill, editing an existing skill, writing a SKILL.md, or verifying a skill works before deployment.

Use when writing, reviewing, or improving software tickets, user stories, or issue descriptions that need clear requirements, acceptance criteria, and scope boundaries.

Step-by-step instructions and templates for scaffolding a new multitenant SaaS project. FastAPI + async PG backend with JWT/RBAC, pnpm frontend monorepo with admin/portal/marketing apps and shared UI library.