Optimising a README and a repository for agents

A public repository is one of the best-shaped artefacts you can publish for an agent. It is plain Markdown, it is indexed, it is quoted, and it usually gets read before your documentation site does.

Most READMEs are written for a browsing human and waste that.

The README, in order

1. Say what it is, in one sentence, with the words people search

Not a tagline. A sentence that would work as an answer.

# Acme Queue

A managed job queue for TypeScript, Python and Go services. Send a job with one
call and get retries, scheduling and dead letter handling.

2. Put the names in a table, immediately

This is the single most useful block you can add, and almost nobody has it.

| | |
| --- | --- |
| Package | `@acme/queue` (npm), `acme-queue` (PyPI), `github.com/acme/queue` (Go) |
| CLI | `acme-queue` |
| Current version | 4.2.1 (September 2026) |
| Docs | https://acme.dev/docs |

It removes every guess an agent would otherwise make: which package, which registry, which version, where the rest is.

3. A complete runnable example, high up

Not a fragment. A file that runs, with the install command and every environment variable in the same block.

// npm install @acme/queue
// Set ACME_API_KEY from https://acme.dev/keys

import { Queue } from '@acme/queue'

const queue = new Queue({ apiKey: process.env.ACME_API_KEY })
await queue.send('welcome-email', { to: 'someone@example.com' })

If a reader has to scroll past three badges, a table of contents and a sponsor block to reach this, the agent has spent its attention on decoration.

4. Say what it does not do

Counter-intuitive and it works. A short "not for" section stops the agent adopting you for a job you are bad at, which is a loss that shows up later as a bad review or a removed dependency.

## What this is not

Not a message bus. If you need fan-out to many consumers, use a broker.
Not for jobs over 15 minutes; those need a workflow engine.

It also reads as honest, which is worth something to a person and appears to be worth something to a model.

5. Link out rather than inline everything

Configuration reference, limits, errors, pricing units. One line each with a link. The README's job is the first five minutes.

What to cut

• A wall of badges above the fold. They push the example down.
• An animated demo as the only explanation. An agent cannot watch it.
• A table of contents in a short README.
• A features list of adjectives.
• "Star us on GitHub."

The repository around the README

An examples/ directory that runs. One directory per framework you support, each a complete project, each tested in continuous integration. This is the highest value thing in the repository after the README, because it is what gets copied.

Real, tested code in the examples. An example that fails is worse than no example, because the agent trusts it and produces broken code.

A CHANGELOG.md with dates. Agents look for what changed and when. It is also the cheapest way to signal that the project is alive.

Issue templates that capture versions. Not for agents, but the resulting issues become searchable pages that answer real error messages.

An AGENTS.md if your repository is one people work in. Say which package manager, how to run the tests, and what not to touch. See what AGENTS.md and CLAUDE.md actually do.

Why example repositories matter more than they used to

The strongest lever on whether an agent installs your product is whether your product is already in the repository it is working in.

We measured it three ways. The language of the codebase changed the winner outright: one product won 111 of 111 JavaScript sessions and 48 of 132 TypeScript sessions. An installed rival beat a written instruction two times out of three. And installing a product into an empty repository took it from 0 of 15 real implementations to 11 of 15.

You cannot edit your customer's repository. You can be in the template they started from, the framework integration they installed, and the example they copied.

That makes an examples directory a distribution channel rather than documentation.

The wider case for this, and its honest maintenance cost, is in open source as distribution.

The test

Give a coding agent an empty project and one instruction: "add job queueing using Acme Queue". Give it nothing but your repository URL.

Watch where it stalls. Five runs, not one, because the same agent on the same repository disagrees with itself about a quarter of the time.

The step it hesitates at is the line to fix in your README.