Skill522 repo starsupdated 3d ago

remix

Build and review Remix 3 applications using the `remix` npm package and

Install in Claude Code

Copy

git clone --depth 1 https://github.com/kentcdodds/kody /tmp/remix && cp -r /tmp/remix/.agents/skills/remix ~/.claude/skills/remix

Then start a new Claude Code session; the skill loads automatically.

Definition

SKILL.md

# Build a Remix App

Use this skill for end-to-end Remix app work. It should help the agent choose
the right layer first, reach for the right package, and avoid the most common
Remix-specific mistakes.

## What Remix Is

Remix 3 is a server-first web framework built on Web APIs such as `Request`,
`Response`, `URL`, and `FormData`. All packages ship from a single npm package,
`remix`, and are imported via subpath. There is no top-level `remix` import.

A Remix app has four main pieces:

- **Routes** in `app/routes.ts` define the typed URL contract and power `href()`
generation.
- **Controllers and actions** implement that contract and return `Response`
objects.
- **Middleware** composes request lifecycle behavior and populates typed context
via `context.set(Key, value)`.
- **Components** render UI with `remix/ui`. This is not React. A component
receives a `handle`, reads current props from `handle.props`, and returns a
render function.

## When To Use This Skill

Use this skill for:

- new features or refactors that touch routing, controllers, middleware, data,
auth, sessions, UI, or tests
- reviewing Remix app code for correctness, architecture, or framework usage
- answering "how should this be structured in Remix?" questions
- finding the right package, reference doc, or default pattern for a task

## Load Only The References You Need

Classify the task first, then load the smallest useful reference set. Each
reference file starts with a "What This Covers" section that lists the topics
inside it — read that first to confirm the file is relevant before reading the
rest.

Use the table below to find candidates. Loading more than two or three files at
once is usually a sign that the task hasn't been narrowed enough yet.

| Task involves... | Start with |
| ----------------------------------------------------------------------------- | ------------------------------------------- |
| Defining URLs, writing controllers and actions, returning responses | `references/routing-and-controllers.md` |
| Composing the request lifecycle, ordering middleware, bridging to a server | `references/middleware-and-server.md` |
| Compiling and serving browser modules, asset URL namespaces, preloads | `references/assets-and-browser-modules.md` |
| Parsing input, validating with schemas, defining tables, querying, migrations | `references/data-and-validation.md` |
| Per-browser state, login flows, route protection, identity | `references/auth-and-sessions.md` |
| Component setup, state, lifecycle, updates, `queueTask`, context | `references/component-model.md` |
| Event handlers, styles, refs, click/key behavior, simple animations | `references/mixins-styling-events.md` |
| `clientEntry`, `run`, `<Frame>`, navigation, `<head>` | `references/hydration-frames-navigation.md` |
| Router tests, component tests, test isolation | `references/testing-patterns.md` |
| Spring physics, tweens, layout transitions | `references/animate-elements.md` |
| Authoring custom reusable mixins | `references/create-mixins.md` |

Common bundles:

- **Form or CRUD feature** -> routing, data and validation, testing; add auth if
user-specific
- **Protected area** -> auth and sessions, routing, testing
- **Interactive widget** -> component model, mixins and styling; add hydration
only if it runs in the browser
- **Browser asset pipeline** -> assets and browser modules, hydration,
middleware and server
- **File upload** -> middleware and server, data and validation, testing
- **Navigation or frames** -> hydration, frames, navigation

## Default Workflow

1. **Classify the change.** Decide whether it changes the route contract,
request lifecycle, data model, auth or session behavior, or only UI.
2. **Start from the server contract.** Add or update `app/routes.ts` before
wiring handlers or UI.
3. **Put code in the narrowest owner.** Favor route-local code first, then
promote only when reuse is real.
4. **Make the server path correct before adding browser behavior.** A route
should return the right `Response` via `router.fetch(...)` before you add
`clientEntry(...)`, animations, or DOM effects.
5. **Add middleware deliberately.** Keep fast-exit middleware early and
request-enriching middleware later. Export a typed `AppContext` from the root
middleware stack and use it in controllers.
6. **Validate input at the boundary.** Parse and validate `Request`, `FormData`,
params, cookies, and external payloads before they reach rendering or
persistence logic.
7. **Hydrate only when necessary.** Prefer server-rendered UI. Use
`clientEntry(...)` and `run(...)` only for real browser interactivity or
browser-only APIs.
8. **Test the narrowest meaningful layer.** Prefer router tests for route
behavior. Use component tests when the behavior is truly interactive or
DOM-specific.
9. **Finish with verification.** Re-read the route flow, confirm auth and
authorization boundaries, and run the smallest relevant test and typecheck
loop.

## Project Layout

Use these root directories consistently:

- `app/` for runtime application code
- `db/` for migrations and local database files
- `public/` for static assets served as-is
- `test/` for shared helpers, fixtures, and integration coverage
- `tmp/` for uploads, caches, local session files, and other scratch data

Inside `app/`, organize by responsibility:

- `assets/` for client entrypoints and client-owned browser behavior
- `controllers/` for route-owned handlers and route-local UI
- `data/` for schema, queries, persistence setup, migrations, and runtime data
initialization
- `m