How to write an agent playbook for your product
An agent playbook is a plain markdown file that tells AI agents how to use your product, the way a README tells people. There are four common kinds: llms.txt says what to read, a skill (SKILL.md) says what an agent can do with your product and the steps to do it, auth.md says how an agent gets credentials, and AGENTS.md gives coding agents instructions inside a code repository. Most products need llms.txt and one skill; add auth.md if agents should register for users, and AGENTS.md in your open-source repos.
From our data: As of 3 Nov 2026, 174 of the 214 software vendors in our rankings published llms.txt and 7 published an A2A agent card. Cloudflare's scan of the top 200,000 domains (published 17 Apr 2026) found fewer than 15 with an MCP server card or API catalog, so most discovery files are still rare.
Which file does what
llms.txt: what to read
A curated index of your key pages at /llms.txt. Read by docs tools and coding agents that are told to look at your site.
SKILL.md: what to do
A skill describes a task and how to do it: when to use it, the steps, the commands or API calls, and the gotchas. It follows the agentskills.io format: YAML frontmatter with a name and description, then markdown instructions.
auth.md: how to get credentials
WorkOS's open protocol (21 May 2026) for agent registration, served at /auth.md: discover your OAuth metadata, pick a registration method, register, claim, use and recover the credential.
AGENTS.md: how to work in this repo
For coding agents editing code: build and test commands, code style, and conventions, at the repository root. Stewarded by the Agentic AI Foundation under the Linux Foundation, and read by Codex, Cursor, Jules, Gemini CLI, GitHub Copilot's coding agent and others. It isn't for your website.
Write a skill agents will follow
The description decides whether an agent loads the skill, so say exactly when to use it. The body should read like steps for a capable new colleague: the order to do things in, the exact commands, what success looks like, and what usually goes wrong.
---
name: example-invoices
description: Create, send and look up invoices with the Example API. Use when the user asks to bill a client, check whether an invoice was paid, or export invoices.
---
# Example invoices
1. Get a key: the user creates one at https://example.com/settings/api (test keys start with sk_test_).
2. Create a customer: POST https://api.example.com/v1/customers with name and email.
3. Create the invoice: POST /v1/invoices with customer, currency and line items (amounts in cents).
4. Send it: POST /v1/invoices/{id}/send. Check status with GET /v1/invoices/{id}.
Gotchas
- Amounts are integers in the smallest currency unit.
- 429 means rate limited: wait for the Retry-After header.
- Full API: https://example.com/openapi.jsonPublish it where agents look
/.well-known/agent-skills/index.json
Cloudflare's Agent Skills Discovery RFC (draft 0.2.0, updated 12 Mar 2026) lists each skill with a name, type, description, url and sha256 digest. isitagentready.com and Mintlify docs sites already serve one.
Link it from llms.txt
Add the skill URL to your llms.txt so agents reading the index find it.
Mention the install command
Skills can be installed into an agent's context (for example npx skills add <url>). Put the command in your docs next to your MCP server URL.
{
"$schema": "https://schemas.agentskills.io/discovery/0.2.0/schema.json",
"skills": [
{
"name": "example-invoices",
"type": "skill-md",
"description": "Create, send and look up invoices with the Example API.",
"url": "/.well-known/agent-skills/example-invoices/SKILL.md",
"digest": "sha256:<64 hex characters>"
}
]
}An example
AgentsReady publishes its own skill at /skill: it tells an agent how to check a site's agent readiness and work through the fixes in order. Our MCP server is described at /mcp-server.
Check it yourself
The first should return JSON with a skills array, the second a 200 with a text or markdown content type if you publish auth.md, and the third shows whether your llms.txt points agents at your skills, auth.md and MCP server.
curl -s https://example.com/.well-known/agent-skills/index.json | head -c 400
curl -s -o /dev/null -w "%{http_code} %{content_type}\n" https://example.com/auth.md
curl -s https://example.com/llms.txt | grep -iE "skill|auth.md|mcp"Questions
Is AGENTS.md for websites?
No. AGENTS.md lives in a code repository and tells coding agents how to build, test and change that code. For a website, use llms.txt and a skill.
What's the difference between a skill and llms.txt?
llms.txt is a reading list. A skill is a set of instructions for one job, with the steps and commands. An agent reads llms.txt to learn about you and a skill to get something done.
Do ChatGPT and Claude read /.well-known/agent-skills automatically?
Not as a general rule today; the discovery RFC is a draft. Some tools and docs platforms use it, and it's cheap to publish. Also link skills from llms.txt and your docs.
Should I write the skill myself or generate it?
Generate a first draft from your docs (Mintlify does this automatically), then edit it by hand. The steps, gotchas and the "use when" line are where a person's knowledge makes the difference.