I Shipped an npm Package With an AGENTS.md File — Here's Why Every Library Should Do This

Last week I published

The key trick: I list AGENTS.md in the files array of package.json, so it ships inside the npm tarball. Every agent that has access to node_modules can read it locally. No network call. No guessing.

"files": ["dist", "AGENTS.md"]

What Goes Inside AGENTS.md

Six sections.

1. One-paragraph summary of what it does


2. Full export list — every public symbol


3. Type definitions — props, configs, enums


4. Numbered patterns — Pattern 1, 2, 3...


5. Decision tree — which pattern when


6. ❌ Common mistakes agents must avoid

Section 6 is the secret weapon. I sat with Claude and Cursor for an afternoon, watched them mis-use my library, and wrote down every wrong pattern. Then I put each one as ❌ Wrong followed by ✅ Correct. The next time an agent reads the file, those mistakes are pre-loaded into its context.

Why This Goes Beyond shimmer-trace

Right now, ecosystem docs are optimized for SEO and Twitter. But the real reader has changed. Code is increasingly written by agents reading docs at 4am with no human in the loop.

A library without an AGENTS.md is a library agents will use wrong.

Three reasons every package author should ship one:

1. 
   Fewer GitHub issues. Half the "bug reports" you get are agents using the API wrong. Document the right way explicitly and the wrong-usage issues vanish.


2. 
   Wider adoption. Cursor and Claude Code recommend the libraries they understand. If your competitor's API is hallucinated and yours is correct, guess which one ends up in the project.


3. 
   Tiny effort. It's one markdown file. You already know your API. Spend two hours and ship.

Try It

before you write the code. It will save your human a debugging session.