# AI Agent Protocol & Instructions Path: `AGENTS.md` [View Raw Content on GitHub](https://raw.githubusercontent.com/remix-run/remix/HEAD/AGENTS.md) # template - AI Agent Protocol & Instructions Path: `template/AGENTS.md` [View Raw Content on GitHub](https://raw.githubusercontent.com/remix-run/remix/HEAD/template/AGENTS.md) # Agents Skill Path: `.agents/skills/add-package/agents/openai.yaml` [View Raw Content on GitHub](https://raw.githubusercontent.com/remix-run/remix/HEAD/.agents/skills/add-package/agents/openai.yaml) # add-package Path: `.agents/skills/add-package/SKILL.md` [View Raw Content on GitHub](https://raw.githubusercontent.com/remix-run/remix/HEAD/.agents/skills/add-package/SKILL.md) # author-ui-components Path: `.agents/skills/author-ui-components/SKILL.md` [View Raw Content on GitHub](https://raw.githubusercontent.com/remix-run/remix/HEAD/.agents/skills/author-ui-components/SKILL.md) # fix-issue Path: `.agents/skills/fix-issue/SKILL.md` [View Raw Content on GitHub](https://raw.githubusercontent.com/remix-run/remix/HEAD/.agents/skills/fix-issue/SKILL.md) # Agents Skill Path: `.agents/skills/make-changes/agents/openai.yaml` [View Raw Content on GitHub](https://raw.githubusercontent.com/remix-run/remix/HEAD/.agents/skills/make-changes/agents/openai.yaml) # make-changes Path: `.agents/skills/make-changes/SKILL.md` [View Raw Content on GitHub](https://raw.githubusercontent.com/remix-run/remix/HEAD/.agents/skills/make-changes/SKILL.md) # make-decision-doc Path: `.agents/skills/make-decision-doc/SKILL.md` [View Raw Content on GitHub](https://raw.githubusercontent.com/remix-run/remix/HEAD/.agents/skills/make-decision-doc/SKILL.md) # Agents Skill Path: `.agents/skills/make-demo/agents/openai.yaml` [View Raw Content on GitHub](https://raw.githubusercontent.com/remix-run/remix/HEAD/.agents/skills/make-demo/agents/openai.yaml) # make-demo Path: `.agents/skills/make-demo/SKILL.md` [View Raw Content on GitHub](https://raw.githubusercontent.com/remix-run/remix/HEAD/.agents/skills/make-demo/SKILL.md) # Agents Skill Path: `.agents/skills/make-pr/agents/openai.yaml` [View Raw Content on GitHub](https://raw.githubusercontent.com/remix-run/remix/HEAD/.agents/skills/make-pr/agents/openai.yaml) # make-pr Path: `.agents/skills/make-pr/SKILL.md` [View Raw Content on GitHub](https://raw.githubusercontent.com/remix-run/remix/HEAD/.agents/skills/make-pr/SKILL.md) # Agents Skill Path: `.agents/skills/make-tracking-issue/agents/openai.yaml` [View Raw Content on GitHub](https://raw.githubusercontent.com/remix-run/remix/HEAD/.agents/skills/make-tracking-issue/agents/openai.yaml) --- name: make-tracking-issue description: Create or revise a GitHub tracking issue for a Remix change, including the target outcome, implementor context, a concise checkbox plan, compatibility concerns, and required gates. Use when the user asks to open, draft, rewrite, or tighten a tracking issue, implementation issue, umbrella issue, or work plan in the Remix repository. --- # Make Tracking Issue ## Overview Create a focused handoff that explains what must change and how completion will be judged without turning the issue into a prescriptive implementation specification. Use `gh` for GitHub reads and writes. Creating or editing an issue is an external write, so only perform it when the user asks for the issue to be created or updated. Otherwise, return a draft. ## Workflow 1. Inspect the relevant code, package metadata, docs, and existing tests until the current state and affected boundaries are concrete. 2. Capture decisions already made by the user. Do not reopen them as alternatives or weaken them with speculative language. 3. Confirm the target repository from the git remote, search for duplicate issues, and inspect issue templates or labels when they may affect the result. 4. Draft the issue using the structure below, omitting sections that add no value. 5. Create or edit the issue with `gh`, then read it back to verify the title, body, state, and URL. ## Issue Structure ### Title Name the concrete outcome and affected area. Prefer `Refactor @remix-run/test to ...` over vague titles such as `Improve test architecture`. ### Summary State the current problem, desired end state, and why the change matters. Include a compact dependency or execution flow when ownership boundaries are central to the work. ### Context and requirements Give the implementor the non-obvious facts needed to work safely: - Current and target ownership boundaries - Public APIs, commands, or package exports that must remain available - Compatibility and migration expectations - Dependency-direction constraints - Defaults or behavior that must not change - Explicit non-goals Keep requirements semantic. Avoid locking in exact type shapes, helper names, file layouts, or parsing implementations unless the repository or user has already decided them. ### Implementation plan Write one flat checklist containing the work outcomes required to complete the change. - Use checkboxes only in this section. - Keep each item to one concise sentence. - Be thorough enough to cover implementation, integration, tests, docs, packaging, and release notes when applicable. - Describe what must be accomplished, not the exact sequence of edits or internal design. - Avoid nested checklists, per-file recipes, proposed interfaces, and command-by-command instructions. Good: ```markdown - [ ] Move test-command parsing and help behavior into `@remix-run/cli`. - [ ] Remove the standalone executable and migrate repository consumers. - [ ] Update integration and packaging coverage for the new boundary. ``` Too prescriptive: ```markdown - [ ] Add `multiple: true` to `ParseArgsStringOptionSpec` in `parse-args.ts`. - [ ] Rename `loadConfig(argv, cwd)` to `loadResolvedConfig(options, cwd)`. ``` ### Required gates List acceptance criteria as ordinary bullets, not checkboxes. Cover the narrow package checks and broader repository checks required by `AGENTS.md`, plus meaningful smoke or packaging verification. Prefer outcome language when the exact command is not important: ```markdown - Test-package tests, typecheck, and build pass. - Package metadata validation passes. - The packed package exposes the intended API and no removed executable. ``` Use exact commands only when they are established repository gates or prevent ambiguity. ### Additional context Add migration examples, release impact, likely affected areas, or out-of-scope notes only when they materially help implementation. Keep historical changelog entries and unrelated cleanup out of scope unless requested. ## Quality Rules - Lead with the desired outcome, not a chronology of investigation. - Separate implementation tasks from acceptance gates. - Preserve the user's chosen architecture and terminology. - Distinguish public behavior from internal implementation freedom. - Call out breaking changes and provide a migration path. - Do not inflate the issue with exhaustive flag, file, or test-case inventories when a grouped requirement is sufficient. - Do not add labels merely because they exist; use only labels that accurately communicate repository workflow or ownership. - Avoid creating a general abstraction as part of a focused tracking issue unless the requested change requires it. ## Before Finishing - Is the title specific enough to scan in an issue list? - Can an implementor explain the current state, target state, and ownership boundary after reading the summary? - Is the implementation plan a single flat checkbox list of outcomes? - Are gates plain bullets with no checkboxes? - Are compatibility, migration, release, and non-goal details included only where useful? - Did `gh issue view` confirm the final issue content and URL? # Agents Skill Path: `.agents/skills/publish-placeholder-package/agents/openai.yaml` [View Raw Content on GitHub](https://raw.githubusercontent.com/remix-run/remix/HEAD/.agents/skills/publish-placeholder-package/agents/openai.yaml) --- name: publish-placeholder-package description: Publish a placeholder npm package at version 0.0.0 so package names are reserved and npm OIDC permissions can be configured before CI publishing. Use when creating a brand-new package that is not ready for full release. --- # Publish Placeholder Package ## Overview Use this skill to publish a minimal placeholder package to npm at `0.0.0`. This is used to reserve the package name and unblock npm-side OIDC configuration for CI publishing. ## Workflow 1. Confirm publish target. - Collect: - npm package name (for example, `@remix-run/my-package`) - package directory in repo (for example, `packages/my-package`) - Validate the package does not already exist at `0.0.0`: ```sh npm view @0.0.0 version ``` - If it already exists, stop and report that no placeholder publish is needed. 2. Build a temporary placeholder package outside the repo. - Always publish from a temp directory to avoid shipping real package files by mistake. - Create the temp directory and write a minimal `package.json`: ```sh tmp_dir="$(mktemp -d)" cd "$tmp_dir" cat > package.json <<'JSON' { "name": "", "version": "0.0.0", "description": "Placeholder package for Remix CI/OIDC setup", "license": "MIT", "repository": { "type": "git", "url": "git+https://github.com/remix-run/remix.git", "directory": "" }, "publishConfig": { "access": "public" } } JSON ``` - Add a short README: ```sh cat > README.md <<'MD' # Placeholder Package This package is a placeholder published at `0.0.0` to reserve the npm name and configure CI publish permissions. MD ``` 3. Ensure npm auth is valid (expect re-auth/OTP). - Check session: ```sh npm whoami ``` - If not authenticated, run: ```sh npm login ``` - Expect npm to require a fresh login and/or one-time password. If prompted for OTP, request it from the user and continue. 4. Publish the placeholder. - Publish with public access: ```sh npm publish --access public ``` - If the account enforces 2FA for writes, publish with OTP: ```sh npm publish --access public --otp


```

5. Wait for the placeholder to appear on npm, then configure trusted publishing.

- New package names may take a short time to become visible in the registry after `npm publish`.
- Poll until `0.0.0` resolves before running `npm trust`:

```sh
for attempt in $(seq 1 18); do
  version=$(npm view @0.0.0 version --silent 2>/dev/null || true)
  if [ "$version" = "0.0.0" ]; then
    break
  fi

  echo "Waiting for @0.0.0 to appear on npm..."
  sleep 10
done

if [ "$version" != "0.0.0" ]; then
  echo "Package did not appear on npm in time"
  exit 1
fi
```

- As soon as it resolves, configure the GitHub Actions trusted publisher from the same local machine where you published the placeholder:

```sh
npm trust github  --repo remix-run/remix --file publish.yaml --yes
```

- This follow-up should be done immediately after placeholder publish while local npm auth is already available.

6. Verify and report.

- Verify the published version:

```sh
npm view @0.0.0 version
```

- Report:
  - package name
  - published version (`0.0.0`)
  - confirmation that `npm trust github` succeeded for `.github/workflows/publish.yaml`

7. Clean up temp files.

```sh
rm -rf "$tmp_dir"
```

## Notes

- Keep placeholder publish minimal. Do not publish full source code for this step.
- This is a one-time bootstrap step. Normal releases should continue through CI.
- Do not stop after `npm publish`; the placeholder is only fully ready once `npm trust github` has been configured.


# References Skill

Path: `.agents/skills/remix/references/animate-elements.md`

[View Raw Content on GitHub](https://raw.githubusercontent.com/remix-run/remix/HEAD/.agents/skills/remix/references/animate-elements.md)


# References Skill

Path: `.agents/skills/remix/references/assets-and-browser-modules.md`

[View Raw Content on GitHub](https://raw.githubusercontent.com/remix-run/remix/HEAD/.agents/skills/remix/references/assets-and-browser-modules.md)


# References Skill

Path: `.agents/skills/remix/references/auth-and-sessions.md`

[View Raw Content on GitHub](https://raw.githubusercontent.com/remix-run/remix/HEAD/.agents/skills/remix/references/auth-and-sessions.md)


# References Skill

Path: `.agents/skills/remix/references/component-model.md`

[View Raw Content on GitHub](https://raw.githubusercontent.com/remix-run/remix/HEAD/.agents/skills/remix/references/component-model.md)


# References Skill

Path: `.agents/skills/remix/references/create-mixins.md`

[View Raw Content on GitHub](https://raw.githubusercontent.com/remix-run/remix/HEAD/.agents/skills/remix/references/create-mixins.md)


# References Skill

Path: `.agents/skills/remix/references/data-and-validation.md`

[View Raw Content on GitHub](https://raw.githubusercontent.com/remix-run/remix/HEAD/.agents/skills/remix/references/data-and-validation.md)


# References Skill

Path: `.agents/skills/remix/references/hydration-frames-navigation.md`

[View Raw Content on GitHub](https://raw.githubusercontent.com/remix-run/remix/HEAD/.agents/skills/remix/references/hydration-frames-navigation.md)


# References Skill

Path: `.agents/skills/remix/references/middleware-and-server.md`

[View Raw Content on GitHub](https://raw.githubusercontent.com/remix-run/remix/HEAD/.agents/skills/remix/references/middleware-and-server.md)


# References Skill

Path: `.agents/skills/remix/references/mixins-styling-events.md`

[View Raw Content on GitHub](https://raw.githubusercontent.com/remix-run/remix/HEAD/.agents/skills/remix/references/mixins-styling-events.md)


# References Skill

Path: `.agents/skills/remix/references/routing-and-controllers.md`

[View Raw Content on GitHub](https://raw.githubusercontent.com/remix-run/remix/HEAD/.agents/skills/remix/references/routing-and-controllers.md)


# References Skill

Path: `.agents/skills/remix/references/testing-patterns.md`

[View Raw Content on GitHub](https://raw.githubusercontent.com/remix-run/remix/HEAD/.agents/skills/remix/references/testing-patterns.md)


---
name: remix
description: Builds, reviews, and refactors Remix 3 apps using the remix package and remix/* imports. Use for application structure, routing, middleware, data, auth, UI, browser interaction, and tests; not for implementing Remix framework packages.
---

# Build and Review a Remix App

## Find Context and Documentation

Read the relevant installed documentation before using unfamiliar Remix APIs:

1. Read the app's `AGENTS.md`, `package.json`, and `tsconfig.json`, then inspect the code that owns the behavior being changed.
2. Search `node_modules/remix/INDEX.md` by task, export, or keyword, for example `grep -i 'session' node_modules/remix/INDEX.md`. For a specific function, type, or attribute, search `node_modules/remix/guides` and `node_modules/remix/src`.
3. Follow the index to the relevant guide for the workflow, then the package README for exact imports, options, behavior, and examples. If there is no relevant guide, use the API README and existing app patterns.

Treat the installed documentation as canonical, including when it differs from this skill. Do not rely on remembered Remix 2 patterns or online APIs from a newer version. If the installation has no index, inspect its `package.json` exports and matching installed READMEs, source, and types.

## Remix Mental Model

Remix builds on Web APIs such as `Request`, `Response`, `URL`, and `FormData`. Its APIs compose explicitly at runtime; do not assume file-based routing, generated route types, or a mandatory build step.

### Routes, Router, and Controllers

Remix apps generally separate routing into three parts:

- **Routes** define the URL and method contract, including typed URL generation (`app/routes.ts` in the starter).
- **The router** connects routes, middleware, and controllers (`app/router.ts`).
- **Controllers** implement the actions that handle matched routes (`app/actions/`).

This organization applies to server apps and browser apps using the SPA router. Remix's pieces are composable and replaceable; using one does not require adopting the others. Follow the existing app's choices and use the documented starter conventions when establishing a new app.

A minimal server route can return a plain Web `Response`:

```ts
// app/routes.ts
import { get, route } from 'remix/routes'

export const routes = route({
  hello: get('/hello/:name'),
})
```

```ts
// app/actions/controller.ts
import { createController } from 'remix/router'

import { routes } from '../routes.ts'

export default createController(routes, {
  actions: {
    hello(context) {
      return new Response(`Hello, ${context.params.name}!`)
    },
  },
})
```

```ts
// app/router.ts
import { createRouter } from 'remix/router'

import controller from './actions/controller.ts'
import { routes } from './routes.ts'

export const router = createRouter()
router.map(routes, controller)
```

The runtime adapter passes requests to `router.fetch(request)`. Generate URLs from the same route contract: `routes.hello.href({ name: 'Remix' })` produces `/hello/Remix`.

### Components

Remix components use JSX, but they are not React. A component's setup function runs once per instance and returns a render function. Local variables in setup preserve state between renders; event handlers change that state and call `handle.update()` to request another render:

```tsx
import { on } from 'remix/component'
import type { Handle } from 'remix/component'

function Counter(handle: Handle) {
  let count = 0

  return () => (
    
  )
}
```

Read changing props from `handle.props` during render, rather than capturing their initial values in setup. Do not apply React hooks or lifecycle assumptions.

Event handlers run only when the component is mounted or hydrated in the browser; server-rendered HTML alone is not interactive. Follow the installed interactivity guide and the app's existing browser-entry setup.

## Work Within the App

- Preserve the app's package manager, scripts, runtime, middleware order, and import conventions unless the task requires changing them. Do not replace an existing solution merely to match the starter.
- Change the narrowest owner of the behavior. Keep route-local code together and share it only when multiple areas need it.
- Prefer Web APIs, native links, buttons, and forms, plus existing first-party Remix primitives, over custom abstractions.
- Treat browser-reachable modules as public: keep secrets and trusted server logic out of them. In the starter, colocated `public/` directories mark browser-reachable source.

## Verify the Behavior

Use the app's scripts for relevant tests and typechecking, then verify the changed behavior directly. For UI changes, exercise the interaction in the browser, not just the rendered appearance. When enhancing a server-rendered page, check both ordinary document behavior and the enhanced path. Test rejection and failure paths for changes involving untrusted input or access control.

Use the installed testing guide for test patterns and CLI documentation for diagnostics. Run `remix doctor` after structural or configuration changes; review findings before applying fixes. Do not run destructive database commands or rewrite configuration merely to make a diagnostic pass. Report what was checked and what remains unverified.


# Agents Skill

Path: `.agents/skills/review-pr/agents/openai.yaml`

[View Raw Content on GitHub](https://raw.githubusercontent.com/remix-run/remix/HEAD/.agents/skills/review-pr/agents/openai.yaml)

AI Agent Protocol & Instructions

Explore Related Technologies & Topics