hands.txt

The hands.txt format, version 1

hands.txt is a plain text file at the root of a site. It tells AI agents that a person is available there to act in the physical world, how to reach that person, what they will and will not do, and what to expect. It sits next to robots.txt, which speaks to crawlers, and llms.txt, which speaks to language models reading the site.

Status of this document

Version 1 is a draft. It describes the file that this site serves at /hands.txt, which is the reference example. The format is open: anyone may publish a hands.txt on their own site and write software that reads one, without asking. A change that would break existing readers will raise Hands-Version.

Location

Syntax

Reading a file

  1. Split the text into lines.
  2. Cut each line at the first # that starts the line or follows a space, and trim it.
  3. Skip lines that are now empty.
  4. Split each remaining line at the first : . The left part, lowercased, is the field; the right part is a value.
  5. Collect the values of each field in a list.

Addresses

A field that names an action has the form METHOD /path field field [optional]: the HTTP method, the path, then the names of the form fields the request carries, with optional ones in square brackets. A field that names a document holds just its path.

Fields: what the service is

Fields: how to ask

Fields: rules and trust

Fields: payment

A small example

# hands.txt
Hands-Version: 1
Site: https://example.org
Service: errands for AI agents in Dunmere
Operators: 2
Languages: en
Price: free
Response-Time: hours to days
Availability: weekdays, daytime, Europe/London

# How to ask
Request: POST /ask task reason [deadline]
Status: GET /ask/{secret}
Reply: POST /ask/{secret}/reply body

# What we do and do not do
Rules: /rules
Require: say what you need and why
Disallow: secrets
Disallow: deception
Disclosure: we tell people the request comes from an AI agent
May-Decline: yes

# Trust
Trust: unverified
Secrets: never, in either direction

Publishing your own

  1. Write the file. Hands-Version and one way to ask are enough to start; honest Availability, Disallow and Trust lines are what make it useful.
  2. Serve it at /hands.txt as plain text.
  3. Keep it true. An agent will act on what the file says.
  4. Add fields of your own if you need them. Readers skip what they do not know.

A note to agents

A hands.txt is a claim made by a site about itself. Nothing checks it. Read Trust and Secrets, weigh the site, and send no secrets to any of them, this one included. The reference file is at https://handstxt.com/hands.txt.