TalentDelta

Our site is fully accessible by humans and agents (via WebMCP).

Learn

Write a README for an agent template

The README is the pack. It is the first file a reader opens, the only file every tool reads, and the difference between a pack somebody runs and a pack somebody closes.

Guide · 4 min read · Updated 5 October 2026

Four sections, in this order

A reader arrives with three questions in a fixed order: is this for me, what am I getting, and how do I start. Answer them in that order and most of the work is done.

SectionAnswersLength
Who it is forIs this for me?Two lines
What is includedWhat do I get?A list
QuickstartHow do I start?Five steps at most
What it expectsWhat will break?A list

The order is the whole trick. A quickstart above the list of contents answers a question the reader has not asked yet, and a reader who has to hunt for what they got usually stops. GitHub's guidance for a repository README asks the same four things in the same order (About the repository README file).

the four sections as a skeleton, filled in
## Who it is for
Finance teams that get invoices as PDFs and check them by hand.

## What is included
- skills/read-invoices/ — reads the PDF text and the line items
- skills/match-to-po/ — matches each line to an open purchase order
- config.template.yaml — names the folder it may read

## Quickstart
1. Unpack the folder.
2. Put skills/ where your harness looks for skills.
3. Start the harness and ask it to read the folder.
4. Open the flags it writes, and check the first five by hand.

## What it expects
- A harness that reads SKILL.md (this pack was written in Hermes)
- Its own API key, with read access to one folder
- Invoices as PDFs with a text layer, not scans

Who it is for

Name the job, not the technology. Someone scanning a catalogue is asking whether this pack is for the work they are doing this week, and a sentence about the tools it uses does not answer that.

This is also the place to say who it is not for. A pack that admits it assumes an existing skill folder spares a reader without one a wasted afternoon, and spares you a question you would rather not answer twice.

the first three lines of a README that works
# Invoice reader
Reads a folder of invoices, matches each line to a purchase order,
and flags the ones a person needs to look at. Read-only: it changes nothing.

The quickstart

Five steps at most, each one a line, in the order a reader does them: unpack it, put it where the harness looks, start it, run it, look at the result.

Name the harness you wrote it in

The quickstart is written for one tool, and naming that tool in the first line saves every reader who uses a different one from guessing whether the rest applies to them.

If it needs more than five steps, the sixth belongs under what it expects. A quickstart that sprawls is read as a warning, which is the wrong first impression for a pack that works.

If you would rather start from a template than from a blank file, makeareadme.com has one to copy.

What it expects

Everything the pack assumes and does not ship: a tool, a version of that tool, a file the reader has to bring, an account somewhere. This is the section a reader consults when the quickstart fails, and the one whose absence earns a pack its first complaint.

When the pack changes, say so in one line and let the build history show the rest. Every version carries its own change note, which is what Run your first agent template tells a reader to check before pulling.

Where to go next