Issue Station
Sign In
Tools hereToolbox

nextjs - ✅(Solved) Fix 'AGENTS.md outperforms skills in our agent evals' - compressed index is not being created in AGENTS.md [1 pull requests, 1 comments, 2 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
vercel/next.js#89238•Fetched 2026-04-08 02:03:06
View on GitHub
Comments
1
Participants
2
Timeline
5
Reactions
0
Author
spatulatomspatulatom
Participants
github-actions[bot]github-actions[bot]spatulatomspatulatom
Timeline (top)
closed ×1commented ×1issue_type_added ×1labeled ×1

PR fix notes

PR #88961: feat(next-codemod): add agents-md command for AI coding agents

Description (problem / solution / changelog)

Summary

Adds a new agents-md subcommand to @next/codemod that generates a Next.js documentation index for AI coding agents (Claude, Cursor, GitHub Copilot, etc.).

Usage

# Interactive mode - prompts for version and target file
npx @next/codemod agents-md

# Non-interactive mode
npx @next/codemod agents-md --version 15.1.0 --output CLAUDE.md

# Auto-detect version, specify output
npx @next/codemod agents-md --output AGENTS.md

What it does

  1. Downloads the Next.js documentation matching your project's version to .next-docs/ (via git sparse-checkout)
  2. Generates a compact index of all doc files grouped by directory
  3. Injects the index into CLAUDE.md or AGENTS.md between marker comments
  4. Adds .next-docs/ to .gitignore

The index helps AI agents prefer local documentation over pre-trained knowledge, ensuring answers match your Next.js version.

Options

OptionDescription
--version <version>Specify Next.js version (auto-detected from package.json if not provided)
--output <file>Target file path (e.g., CLAUDE.md, AGENTS.md)

Output format

The generated index is a single line with pipe separators:

<!-- NEXT-AGENTS-MD-START -->[Next.js Docs Index]|root: ./.next-docs|IMPORTANT: Prefer retrieval-led reasoning...|dir:{file1.mdx,file2.mdx}|...<!-- NEXT-AGENTS-MD-END -->

Test plan

  • Build passes
  • Tested interactive mode
  • Tested non-interactive mode with --version and --output
  • Tested auto-detect version with --output only
  • Verified .gitignore is updated
  • Verified index is injected correctly (new file and existing file)

Eval results

Tested against 19 Next.js-specific agent evals with 100% pass rate:

EvalResult
agent-000-app-router-migration-simple✅✅✅ (89.5s)
agent-021-avoid-fetch-in-effect✅✅✅ (90.4s)
agent-022-prefer-server-actions✅✅✅ (67.1s)
agent-023-avoid-getserversideprops✅✅✅ (102.5s)
agent-024-avoid-redundant-usestate✅✅✅ (62.9s)
agent-025-prefer-next-link✅✅✅ (69.5s)
agent-026-no-serial-await✅✅✅ (96.2s)
agent-027-prefer-next-image✅✅✅ (68.0s)
agent-028-prefer-next-font✅✅✅ (64.2s)
agent-029-use-cache-directive✅✅✅ (76.6s)
agent-030-app-router-migration-hard✅✅✅ (220.8s)
agent-031-proxy-middleware✅✅✅ (92.4s)
agent-032-use-cache-directive✅✅✅ (71.3s)
agent-033-forbidden-auth✅✅✅ (100.6s)
agent-034-async-cookies✅✅✅ (68.7s)
agent-035-connection-dynamic✅✅✅ (65.2s)
agent-036-after-response✅✅✅ (68.7s)
agent-037-updatetag-cache✅✅✅ (70.3s)
agent-038-refresh-settings✅✅✅ (71.8s)
Overall19/19/19 (100%, 100%, 100%)

Legend: ✅✅✅ = Build/Lint/Test

Changed files

  • packages/next-codemod/.gitignore (modified, +2/-1)
  • packages/next-codemod/bin/agents-md.ts (added, +207/-0)
  • packages/next-codemod/bin/next-codemod.ts (modified, +24/-0)
  • packages/next-codemod/lib/__tests__/agents-md.test.js (added, +142/-0)
  • packages/next-codemod/lib/agents-md.ts (added, +644/-0)

Code Example

Operating System:
  Platform: darwin
  Arch: arm64
  Version: Darwin Kernel Version 24.2.0
  Available memory (MB): 36864
  Available CPU cores: 12
Binaries:
  Node: 20.18.1
  npm: 10.8.2
  Yarn: N/A
  pnpm: N/A
Relevant Packages:
  next: 15.5.10
  eslint-config-next: N/A
  react: 19.0.0
  react-dom: 19.0.0
  typescript: 5.7.3
Next.js Config:
  output: N/A
RAW_BUFFERClick to expand / collapse

Link to the code that reproduces this issue

https://vercel.com/blog/agents-md-outperforms-skills-in-our-agent-evals

To Reproduce

  1. npx @next/codemod@canary agents-md

This functionality is part of the official @next/codemod package.

This command does three things:

  1. Detects your Next.js version

  2. Downloads matching documentation to .next-docs/

  3. Injects the compressed index into your AGENTS.md - THE COMPRESSED INDEX IS NOT BEING CREATED

Current vs. Expected behavior

https://vercel.com/blog/agents-md-outperforms-skills-in-our-agent-evals

Provide environment information

Operating System:
  Platform: darwin
  Arch: arm64
  Version: Darwin Kernel Version 24.2.0
  Available memory (MB): 36864
  Available CPU cores: 12
Binaries:
  Node: 20.18.1
  npm: 10.8.2
  Yarn: N/A
  pnpm: N/A
Relevant Packages:
  next: 15.5.10
  eslint-config-next: N/A
  react: 19.0.0
  react-dom: 19.0.0
  typescript: 5.7.3
Next.js Config:
  output: N/A

Which area(s) are affected? (Select all that apply)

Not sure

Which stage(s) are affected? (Select all that apply)

Other (Deployed)

Additional context

No response

extent analysis

TL;DR

The issue with the compressed index not being created in the AGENTS.md file may be resolved by verifying the successful execution of the npx @next/codemod@canary agents-md command and checking the .next-docs/ directory for the downloaded documentation.

Guidance

  • Verify that the npx @next/codemod@canary agents-md command completes without errors, as this command is responsible for detecting the Next.js version, downloading matching documentation, and injecting the compressed index into AGENTS.md.
  • Check the .next-docs/ directory to ensure that the documentation is being downloaded correctly, as this is a prerequisite for creating the compressed index.
  • If the issue persists, try running the command with additional logging or debugging options to gather more information about the failure.
  • Review the official @next/codemod package documentation and the referenced pull request to ensure that the command is being used correctly and that there are no known issues with the version being used.

Notes

The provided information does not include specific error messages or detailed logs, which could help identify the root cause of the issue. Therefore, the suggestions are focused on verifying the command execution and checking the downloaded documentation.

Recommendation

Apply workaround: Try running the command with additional logging or debugging options to gather more information about the failure, as the root cause of the issue is not immediately clear from the provided information.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…
#cache error#pipeline error#runtime error#dependency conflict#environment setup

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING