Menu

1 / 2

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

DEV Community·jeetvora331·6 months ago
#NbQXt7tF
#ai#productivity#tutorial#agents#shimmer
Reading 0:00
15s threshold

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.…

Continue reading — create a free account

Join HashtagPLUS to read full articles, follow hashtags, vote, and join the conversation.