Include React Router Agent Skills in Official Templates

[brookslybrand]

Decsions

After discussing with the Steering Committee, this is what we have decided on. Happy to hear further from the community if there's confusion or differing opinions

• ✅ Move remix-run/agent-skills into remix-run/react-router repo and archive existing repo
• ✅ Add inclusion of skills as a step in the CLI
• ✅ Make default "yes" to adding Agent Skill in CLI
• ✅ Publish docs to node_modules
  • The full published docs will be a subset, likely excluding api (this is just a repeat of JSDocs), community, etc.
  • Agent Skills will be updated to encourage agents to look for the official docs in node_modules when more information is needed

---

React Router has official templates for new projects and official agent skills that teach AI coding agents how to work with React Router correctly. Today those two entry points are separate. This proposal suggests bringing them together so projects created from the official templates can include React Router agent skills by default, or through an explicit create-react-router option.

The goal is to make new React Router apps easier for AI agents to work on without requiring users to discover and install the skills separately.

Current State

React Router agent skills currently live in remix-run/agent-skills and cover all 3 modes. React Router templates currently live in remix-run/react-router-templates.

Because the skills are separate from the templates:

• New React Router projects do not automatically get our official Agent Skills.
• Users must know the skills exist and install them after project creatio.
• The skills are not tied to to any specific React Router version.

Proposed Future State

React Router should ship agent skills from the React Router repo and make them available to projects created from the official templates.

At a high level:

• Move or mirror the React Router skills into the React Router repo under a path like .agents/skills/react-router. This aligns with the remix-run/remix repo which hosts it's Agent Skills directly in the repo.
• Keep the skills versioned with the React Router branch that owns them. E.g. existing skills at the time of this writing will live on the v7 branch, and main will update to be whatever the current version is.
• Update the official templates so generated projects can include the appropriate React Router skill files.

This would let React Router v7 keep v7-specific guidance on a v7 branch while React Router v8 can evolve its own skills on main.

Template Integration

There are two reasonable options for including the skills in generated apps.

Option A: Include Skills Automatically

Every official template includes the relevant React Router skill files by default.

Benefits:

• Best default experience for users working with AI coding agents.
• No extra installation step.
• Official templates become self-describing for both humans and agents.
• Fewer generated apps miss the guidance.

Tradeoffs:

• Adds files to every generated project, including projects whose users do not care about agent workflows.
• Requires us to treat the skill files as part of the generated project surface.

Option B: Add a CLI Step

create-react-router asks whether to include React Router agent skills, or exposes a flag such as:

npx create-react-router@latest --with-agent-skills

We could make this the default experience (at least in v8), giving the most middle-ground option between A and B.

Benefits:

• Keeps generated projects smaller for users who do not want agent-specific files.
• Makes the feature explicit and discoverable.
• Leaves room for future choices, such as which agent format to install.

Tradeoffs:

• It adds more questions to the CLI, making it less simple
• The CLI has to maintain one more project-creation branch.

Documentation Source

There is a second decision point around how much documentation should live directly in the skill.

The Remix skill points agents toward README files inside the published remix package, for example under node_modules/remix/src/.../README.md. That works because the package can be the source of deeper reference material while the skill stays focused on workflow and high-level rules.

React Router could follow a similar model, but it would likely require shipping more documentation inside the React Router packages. That may or may not be something we want.

There are two options here:

• Keep the current React Router skill model, where the skill includes focused reference files.
• Move toward a Remix-style model, where the skill is a guide layer and deeper docs live in node_modules.

For this proposal, these do not need to block the template integration. We can start by shipping the current skill content with the templates, then separately decide whether React Router packages should include additional docs for agents to reference.

[brookslybrand]

Potentially worth looking into Tanstack Intent: https://tanstack.com/intent/latest

I am not that interest in being dependent on a 3rd party solution, but their approach ties skills to direct dependencies, which could be nice

[brookslybrand]

We are planning to ship docs/ to node_modules, which largely precludes the need for this.

See Decisions

[brookslybrand]

Another thought on our templates more generally: right now we really only surface Framework Mode templates. We also surface several adapters still. I would prefer if we had starters for each mode and reduced the number of templates. That's likely a place for another discussion, but the proliferation of templates is not super ideal, and some we've struggled with for years. Inevitably though if we get rid of a template, someone will complain.

This is not in the main body because it's not a fully formed though, and something I just wanted to see if folks had thoughts on

[brophdawg11]

I think we have to keep cloudflare because IIRC their own cli uses our template?

[brookslybrand]

Re: Cloudflare. We should maybe just ask them to stop then.

If we could narrow down to just 3 starter templates and have examples or docs for other setups I feel like that would be more ideal personally

[brophdawg11]

I think at the very least we would need 4 starter templates (Data/Framework + RSC/Non-RSC). It'd be worth seeing the docs for setting up your own express custom server but it's probably going to be a good bit of npm install commands and boilerplate copying that feels better suited for a template IMO - so that would get us to 5

data mode
framework mode (rr serve)
frsamework mode (express)
rsc data mode
rsc framework mode

[brookslybrand]

That makes sense @brophdawg11

Thoughts on moving it off express and onto @remix-run/fetch-router``/@remix-run/node-fetch-server/ the appropriate middleware? Or given that these are all much new libraries, is having a canonical express` template safer?

[brophdawg11]

IMO express is probably safer/more appropriate for RR folks who are likely choosing react/RR because it's battle tested. Advanced folks who want to use RR with fetch-router/node-fetch-server should be able to figure it out.

[SimJoSt]

How do you plan on solving the chicken-and-egg problem with extending the docs with instructions on how to do an upgrade to the next version? Like deprecations and migration steps, etc.
Or do you just add them to the docs of the next version and the first step is the upgrade the package version, so the new docs become available?

[brophdawg11]

For the most part, our major upgrades are pretty straightforward/boring because it usually just requires adopting the current future flags. Docs for those exist in the current version so for example, if you're on 7.18 and you tell your agent to "adopt all future flags", it should be able to find https://reactrouter.com/7.18.0/upgrading/future in node_modules and tackle that.

Stuff like deprecations/minimum versions/etc used to show up in the next version upgrade guide (https://reactrouter.com/upgrading/v7) but starting with v8 we're also putting that in the current version docs (https://reactrouter.com/upgrading/future) so that will also be readily available for the agent in the latest release of 8.x whenever 9.x becomes available.