# How to write a quickstart an agent can follow

> The highest return change most developer tool companies can make. What breaks, why it costs installs, and the exact shape that works.

Source: https://armature.tech/library/write-a-quickstart-an-agent-can-follow
Published: 2026-09-03
Publisher: Armature, Inc. (https://armature.tech)

---

Of everything in agent discoverability, this is the cheapest change with the largest effect, and most companies fail it.

## The test

Open an empty project. Paste your quickstart. Run it.

That is the whole test. Nothing else. No reading the page above, no prior knowledge of the product, no account you already have.

Most quickstarts fail.

> An agent that cannot make your example work does not file a bug. It abandons the integration and picks the next candidate, usually in the same session. You lose an install you had already won.

## What breaks, in order of frequency

### The unstated environment variable

The quickstart uses `ACME_API_KEY`. The page that explains where to get it is two clicks away. The agent pastes the code, runs it, gets an authentication error, and has to go looking.

Sometimes it finds the answer. Often it decides the product is more work than the alternative.

**Fix:** name every variable in the same block, with a comment saying where it comes from.

### The assumed install step

The quickstart shows the code but not the install, because the install was on the previous page.

**Fix:** put the install command at the top of the same block. Every time. On every page that has runnable code.

### The dashboard step that is not in the code

"Create a project in the dashboard, then copy the ID." True, necessary, and invisible to an agent reading a code block.

**Fix:** put it in the code block as a comment, in sequence, so it cannot be skipped.

```js
// 1. Create a project at https://acme.dev/new and copy the project ID
// 2. npm install @acme/queue
// 3. Set ACME_API_KEY and ACME_PROJECT_ID in your environment

import { Queue } from '@acme/queue'
```

### The outdated example

The example uses an interface you replaced. The agent writes code that matches the page, and it fails.

**Fix:** state the current version on the page, in the text, near the top. And test the examples in continuous integration so they cannot rot.

### The fragment

The code block is three lines from the middle of a file. It has no imports, no setup, and no way to run.

**Fix:** make it a complete file. Longer is fine. Complete is the requirement.

## The shape that works

One block. Complete. Redundant on purpose.

```js
// Acme Queue quickstart
// Current version: 4.2.1 (September 2026)
//
// 1. npm install @acme/queue
// 2. Get an API key at https://acme.dev/keys
// 3. Set ACME_API_KEY in your environment
// 4. Run this file: node quickstart.js

import { Queue } from '@acme/queue'

const queue = new Queue({
  apiKey: process.env.ACME_API_KEY,   // required
  region: 'eu',                        // optional, defaults to 'us'
})

await queue.send('welcome-email', { to: 'someone@example.com' })

console.log('Sent. See it at https://acme.dev/dashboard')
```

Six things that block does that most quickstarts do not:

1. Names the product and the current version.
2. Includes the install command.
3. Names every prerequisite in order, including the ones outside the code.
4. Is a complete, runnable file.
5. Marks which options are required and which have defaults.
6. Ends with a way to verify it worked.

That last one matters more than it looks. An agent that can confirm the call succeeded stops there. An agent that cannot confirm anything keeps going, and often keeps changing things.

## Redundancy is correct

The instinct of a good technical writer is to avoid repeating the install command on every page. That instinct is right for a human reading in order and wrong for an agent arriving from a search.

The agent lands on one page. It may never see the page above it. Every page with runnable code should carry everything needed to run that code.

## Name things once

The quickstart is where naming mismatches do their damage. If the product is "Acme Queue", the package is `@acme/q`, and the import is `AcmeQ`, the agent has to guess a mapping, and sometimes it guesses a package that is not yours.

Write the mapping explicitly:

```
Product: Acme Queue
Package: @acme/queue
Import:  import { Queue } from '@acme/queue'
CLI:     acme-queue
```

## Test it the way an agent will

Two tests, both cheap.

**The paste test.** Empty project, paste, run. Do it yourself, without using anything you know about the product.

**The agent test.** Give a coding agent a repository and a one-line request that your product answers. Watch what it does. The place it stalls is your bug.

Run the agent test five times, not once. The same agent on the same repository disagrees with itself about a quarter of the time, so one run tells you nothing.

## Keep it working

Examples rot. Put the quickstart in continuous integration: extract the code block, run it against the current release, fail the build when it breaks.

That single job protects the highest value page you have.

## Why this is worth doing first

Everything else in agent discoverability is slower. Templates take months. Framework integrations take quarters. Training data takes years.

The quickstart takes an afternoon, and it is the last step of every session you nearly won.

## Common questions

### What makes a quickstart work for a coding agent?

It runs when pasted into an empty project, with no unstated prerequisites. Every install command, every environment variable and every import is in the same block, and the code is a complete file rather than a fragment.

### Why do quickstarts fail for agents?

Usually an unstated prerequisite. An environment variable mentioned on another page, an install step assumed from the previous section, a dashboard action that never appears in code, or an example using an interface that changed.

### What happens when a quickstart fails?

The agent does not report a bug. It abandons the integration and picks a different product, usually within the same session. You lose an install you had already won.

### Should the quickstart repeat information from other pages?

Yes. Redundancy is correct here. The agent may have arrived at this page directly from a search and may never load the page above it in the navigation.

### How do I test my quickstart?

Open an empty project, paste the quickstart, and run it, with no other knowledge of your product. If it does not run, that is the bug. Then do the same with a coding agent and watch where it stalls.

## Read next

- [Documentation for coding agents](https://armature.tech/library/documentation-for-coding-agents) (Markdown: https://armature.tech/library/documentation-for-coding-agents.md)
- [Audit your documentation for coding agents](https://armature.tech/library/audit-your-docs-for-coding-agents) (Markdown: https://armature.tech/library/audit-your-docs-for-coding-agents.md)
- [Agent discoverability: the complete guide](https://armature.tech/library/agent-discoverability) (Markdown: https://armature.tech/library/agent-discoverability.md)
- [Package naming for coding agents](https://armature.tech/library/package-naming-for-coding-agents) (Markdown: https://armature.tech/library/package-naming-for-coding-agents.md)
- [Optimising a README and a repository for agents](https://armature.tech/library/readme-and-repository-optimization) (Markdown: https://armature.tech/library/readme-and-repository-optimization.md)
- [Time to first successful call, when the developer is an agent](https://armature.tech/library/time-to-first-successful-call) (Markdown: https://armature.tech/library/time-to-first-successful-call.md)

---

Armature helps software products get discovered and used by coding agents.
Service: https://armature.tech/discoverability · Results: https://armature.tech/leaderboards/sectors · Contact: contact@armature.tech