How to Make Your Open-Source Library Easier for AI Agents to Find, Trust, Use and Love

Signup Write New Story How to Make Your Open-Source Library Easier for AI Agents to Find, Trust, Use and Love by Arthur by Arthur | @ arthurtkachenko-rm2m8 inspiring

A practical checklist, with a real repository as the case study

More and more developers now ask an AI agent before they ask a search engine. lets imagine they are asking this question"What's a good library for extracting links from Markdown?" is as likely to go to a coding assistant as to Google.

Once an agent is inside a project, it also picks dependencies, reads documentation, and writes code against your API, often without a human opening your README at all. So a new question for OSS maintainers is how to make a project legible to agents.

I'll use a small, real project as the case study: markdown-regex, a zero-dependency TypeScript library of ready-made RegExp constants for parsing Markdown. It has a solid base: a clear install section, an API table, TypeScript types, dual ESM/CommonJS builds, and CI across several Node versions. It also has about 11 stars, which makes it a good example of a useful project that most people, and most agents, will never encounter.

Agents interact with your project in two ways, and each needs different work. In the first, they retrieve text (search results, registry pages, docs) to decide whether to recommend you. In the second, they read your repo and call your API to get a task done. The rest of this article covers both, plus the trust signals that influence each.

An agent choosing a library needs a decision rule. Most READMEs describe what the project does but never say when it's the right choice.

For a regex-based Markdown toolkit, that means saying plainly: use this for quick extraction, linting, and lightweight transforms; use a full parser like remark or markdown-it when you need a real AST, deeply nested structures, or strict CommonMark compliance. That honesty helps in two ways. Agents recommend you for jobs you're good at, and they stop recommending you for jobs you'd fail, which protects your reputation.

The repository's current tagline is "Set of constants that can help you to parse markdown content." It's accurate, but vague. Compare:

Zero-dependency, TypeScript-typed RegExp patterns for extracting headers, links, images, lists, and code from Markdown.

If your GitHub page shows no releases or packages, agents (and humans) can't easily tell which version is current or what changed. Tag versions and publish release notes. If you're in a beta or mid-rewrite, say so clearly and document the migration path, otherwise agents will keep suggesting outdated usage from older tutorials.

Keep the name, description, and README content consistent across GitHub, npm, and any articles about the project. Use the conventional README.md casing so tooling finds it.

AGENTS.md is an emerging convention: a plain Markdown file at the repository root that tells coding agents how to work in your project. Several tools read it. It should contain:

Think of it as a README written for a contributor who has zero context and can't ask questions. If you want tool-specific coverage, a small CLAUDE.md or similar can simply point to it.

llms.txt is a proposed convention for a concise, link-based summary of a project designed for language models, optionally accompanied by a longer llms-full.txt containing the complete API. Support among crawlers and agents is still uneven, so treat it as a cheap bet, not a guaranteed win. It costs almost nothing to produce and can be generated from your existing docs.

An agent writing code against your library sees your.d.ts files and editor tooltips long before it sees your README. JSDoc comments on every export are probably the single highest-leverage improvement available. Each one should include a one-line description, an example that matches, and ideally an example that doesn't.

/** * Matches Markdown links: `[text](url)`. * Capture groups: 1 = link text, 2 = URL. * * @example * 'See [docs](https://example.com)'.match(REGEXP_LINK); * // matches "[docs](https://example.com)" * * @example * ''.match(REGEXP_LINK); // images should not be treated as links */ export const REGEXP_LINK = /.../; (The regex body above is a placeholder; the point is the shape of the documentation.)

A table saying " REGEXP_LINK — link syntax — matches [text](url) " tells a reader what the constant is for, but not how it behaves. Agents (and people) need behavioral detail. For every export, document:

markdown-regex bundles two different kinds of exports in one table: patterns that match Markdown syntax, and cleanup patterns that operate on generated HTML, such as </ul><ul>. Mixing them blurs what the library is. Grouping them in the docs, or exposing cleanup helpers under a subpath export, gives both humans and models a clearer mental model.

Raw regexes force every consumer to compose their own logic. A few helpers, such as extractLinks(md) returning typed objects, let an agent solve the common case in one line with far less room for error. Agents favor APIs where the obvious call produces the right result.

Agents and humans both weigh maintenance signals when deciding whether to trust a dependency. In this repo, some easy fixes stand out:

A stray file at the root, source-fullcodetest.md, looks like leftover scratch work.

Two Jest config files ( jest.config.js and jest.config.cjs ) suggest an unfinished migration.

Open issues (17) and pull requests (2) with no visible triage make a project look abandoned even when it isn't. Close stale ones, label some as good first issue, and give contributors, human or automated, a clear on-ramp.

Badges for npm version, CI status, bundle size, and coverage compress a lot of trust information into one glance.

A SECURITY.md helps. For a regex library specifically, ReDoS (catastrophic backtracking) is the obvious concern, so run a checker such as safe-regex or recheck in CI and say so in the README.

Claims are weak; evidence is strong. Three kinds of evidence help:

Models and retrieval systems surface what appears in many independent places. Keep your npm page current. Update older articles about the project when a major version ships, since stale tutorials teach agents obsolete APIs.

Together these cover discoverability, in-repo usability, and trust with the smallest effort.

Making a project agent-friendly doesn't require special tricks. Nearly everything here is what good documentation and good maintenance already look like, made more explicit and more structured. An agent can't skim between the lines, ask a maintainer a question, or forgive a stale README.

If you state what your project is for, show exactly how it behaves, and keep the repository visibly cared for, both agents and the developers relying on them will find it easier to choose you.

The Linguistic Survivorship: Why "Russian-Speaking" Regions are a Stupid Myth