DEV Community

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

Posted on

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

#ai #productivity #tutorial #discuss

Last week I published shimmer-trace, a React skeleton loader that traces your real DOM and paints a pixel-perfect shimmer over it. No manual skeletons. One-line wrap. Zero CLS.

But this post isn't about the shimmer. It's about a small file I shipped alongside it that I think is going to become a standard:

AGENTS.md — a README written for AI agents, not humans.

The Problem: Your README Is Lying to the LLM

In 2026, more than half the people "reading" your library docs aren't people. They're Cursor, Claude Code, Copilot, and a hundred other agents writing code on behalf of a developer.

And here's the thing — your README.md is built for humans. It has marketing copy. Animated GIFs. "Why we built this." Friendly tone.

When an LLM reads it, it has to guess:

  • What are the exact prop names?
  • Which combinations are valid?
  • What's the default value of speed?
  • What goes wrong if I forget dummyData?

So the agent hallucinates. It invents prop names. It mixes up patterns from three other skeleton libraries. The user copy-pastes broken code and blames the library.

The Fix: Ship Two Docs 

shimmer-trace/
├── README.md       ← humans (learning, demo, vibe)
└── AGENTS.md       ← agents (exact API, patterns, mistakes)
Enter fullscreen mode Exit fullscreen mode

That's it. That's the idea. One file in your package root, written like a strict reference manual, explicitly addressed to LLMs.

How AGENTS.md Works (Diagram)

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"]
Enter fullscreen mode Exit fullscreen mode

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

🚀 Live Demo

npm install shimmer-trace
Enter fullscreen mode Exit fullscreen mode 
import { Shimmer } from 'shimmer-trace';

<Shimmer loading={loading}>
  <UserCard user={user} />
</Shimmer>
Enter fullscreen mode Exit fullscreen mode

That's it. The skeleton is auto-traced from your real DOM. No more matching width: 240px to your card by hand.

And if you're an agent reading this — go check AGENTS.md before you write the code. It will save your human a debugging session.

If you ship an npm package, add an AGENTS.md this week. Let me know your thoughts in the comments!

Top comments (0)