remix-run/react-router · error · Error

React Router agent skill files were not found

Error message

React Router agent skill files were not found

What it means

Thrown in copyAgentSkillsToAppDirStep() when the user opted into agent skills (--agent-skills or answered yes) but SKILL.md is missing at the bundled agentSkillPath (<package>/dist/agent-skills/react-router/SKILL.md). This is a packaging/distribution defect in the installed create-react-router package, not a user mistake — the agent skill assets were not shipped into dist.

Source

Thrown at packages/create-react-router/index.ts:342

async function copyAgentSkillsToAppDirStep(ctx: Context) {
  if (!ctx.agentSkills) {
    await sleep(100);
    info("Skipping agent skill.", [
      "You can add it later from ",
      color.reset(
        "https://github.com/remix-run/react-router/tree/main/.agents/skills/react-router",
      ),
      ".",
    ]);
    return;
  }

  if (!existsSync(path.join(agentSkillPath, "SKILL.md"))) {
    error(
      "Oh no!",
      "React Router agent skill files were not found in this package.",
    );
    throw new Error("React Router agent skill files were not found");
  }

  let destPath = path.join(ctx.cwd, ".agents", "skills", "react-router");

  if (existsSync(destPath)) {
    info("Agent skill:", "React Router agent skill already included");
    return;
  }

  await ensureDirectory(path.dirname(destPath));
  await cp(agentSkillPath, destPath, {
    errorOnExist: true,
    force: false,
    recursive: true,
  });
  info("Agent skill:", "Included React Router agent skill");
}

View on GitHub (pinned to 1fd704a7da)

Solutions

1. If you don't need the agent skill, disable it: --no-agent-skills.
2. Reinstall create-react-router from npm to get a complete build: npm i -g create-react-router@latest.
3. If running from a local checkout, run the package build so dist/agent-skills/react-router/SKILL.md is populated.
4. Manually copy the skill from github.com/remix-run/react-router/tree/main/.agents/skills/react-router into ./.agents/skills/react-router after scaffolding.

Example fix

// before -- broken local build missing assets
create-react-router my-app --agent-skills
// after -- skip skill, or use the published package
create-react-router my-app --no-agent-skills
# or:
npx create-react-router@latest my-app --agent-skills

import { existsSync } from 'node:fs';
import path from 'node:path';
// Confirm the bundled skill asset exists before enabling --agent-skills
const crrPkg = path.dirname(require.resolve('create-react-router/package.json'));
const skillPresent = existsSync(path.join(crrPkg, 'dist/agent-skills/react-router/SKILL.md'));
// if (!skillPresent) invoke with --no-agent-skills

try {
  await createReactRouter([dir, '--agent-skills']);
} catch (e) {
  if (/agent skill files were not found/.test(String(e?.message ?? ''))) {
    await createReactRouter([dir, '--no-agent-skills']);
  } else throw e;
}

When it happens

Trigger: Installing create-react-router from a dev build that skipped copying agent-skills into dist; a packaged tarball missing the dist/agent-skills tree; running from source without building; a broken npm publish that omitted the assets.

Common situations: Using a local/linked build of create-react-router without running the build step that copies agent-skills; an npm publish with an overly narrow 'files' field; an old/cached node_modules entry predating agent-skills.

Related errors

• "${template}" is an invalid template. Run "create-react-rout
• The provided template is not a valid local directory or tarb
• There was a problem extracting the file from the provided te
• No project directory provided
• File collisions detected in a non-interactive environment

AI-assisted analysis of remix-run/react-router@1fd704a7da (2026-08-12). Data as JSON: /api/errors/3b07a2b22119ace7. Report an issue: GitHub.