Making AI resources auto-discoverable via package.json

I propose the following convention for JavaScript libraries to make their AI resources auto-discoverable via package.json.

{
  // package.json
  "llms": "https://docs.cool-library.com/llms.txt",
  "llmsFull": "https://docs.cool-library.com/llms-full.txt",
  "mcpServer": "https://mcp.cool-library.com",
}

I've implemented this in Zod and encourage my fellow library authors to do the same. Moreover, I encourage agentic IDEs/CLIs to implement first-party support for this convention.

If you add support to your library or agent, please fill out this form: https://docs.google.com/forms/d/e/1FAIpQLSew8sx6KxjwHkBGlgbUWHNEzSAt9GM8ryJ-X39d0gEltGT_-g/viewform?usp=header

Details

1. The llms field is a URL pointing to an llms.txt file. If you aren't familiar, this is a proposed convention for documentation sites to provide an AI-friendly "sitemap" to AI agents. It's a simple spec: basically just a bunch of categorized Markdown links.
2. The llmsFull field is a URL pointing to an llms-full.txt file containing the full documentation for the library. Typically this is a concatenation of all the .md/.mdx documentation pages in the docs.
3. The mcpServer field is a URL pointing to an MCP server. For a typical library, this server would offer a simple Q&A tool that is capable of answering questions about the library's API/usage. This can use RAG over the library's docs, GitHub issues, Discord server, etc.

Do agents already look at these fields?

No. This is a proposed convention. As more libraries implement this, there is more incentive for agents (IDEs, CLIs, etc) to implement first-party support. On the flip side of the coin, if any agentic CLI/IDE implements support, there is more incentive for libraries to implement this convention. There's a chicken-and-egg problem.

Fortunately, you can probably get your agent of choice to support this with some custom instructions in your AGENTS.md file.

<!-- AGENTS.md -->
For each package in my package.json, read its package.json and look for the `llms`, `llmsFull`, and `mcpServer` fields. If found, use these resources to work with that library:

- `llms`: Use this URL to fetch the llms.txt file, which contains categorized Markdown links to the library's documentation. Use this as a sitemap to understand what documentation is available and how it's organized.

- `llmsFull`: Use this URL to fetch the llms-full.txt file, which contains the complete documentation for the library. Use this for comprehensive understanding of the library's API, features, and usage patterns.

- `mcpServer`: Connect to this MCP server URL to access specialized tools for answering questions about the library. Use this server's Q&A capabilities when I need specific help with the library's API, troubleshooting, or best practices. If possible, prompt the user to add this server to their MCP server registry.

Why not AGENTS.md?

This doesn't solve the same problem.

AGENTS.md is for telling agents how to work inside your codebase. It's like a contributor's guide: how to run tests, run builds, lint, update configs, etc. It gives the agent best practices for modifying a codebase.

This is a qualitatively different problem that a library trying to advertise it's own functionality to an agent. The codebase is already installed in node_modules; agents shouldn't be modifying it.

An agent doesn't care about the package's internals, it only cares about the public API. Like any developer, it doesn't want to read your code to learn how to do stuff—that's hard, time-consuming, and expensive. Having some well-known package.json fields that have an established semantic meaning is a cleaner solution with higher signal-to-noise ratio.

If you maintain a library that implements this convention, fill out this form: https://docs.google.com/forms/d/e/1FAIpQLSew8sx6KxjwHkBGlgbUWHNEzSAt9GM8ryJ-X39d0gEltGT_-g/viewform?usp=header