Agent skills are short instruction files, usually named SKILL.md, that teach an AI agent how to do one specific job with your site: send an inquiry, run a report, look up an order. A discovery index at /.well-known/agent-skills/index.json lists your skills with a checksum for each, and the draft ai-catalog at /.well-known/ai-catalog.json lets agents and registries find them.
If llms.txt is the introduction to your site, skills are the how-to guides. They turn "this business has a contact form" into "here is exactly how to send a valid inquiry for your user, and what to tell them afterwards".
What a skill is
A skill is a Markdown file with a short header and plain instructions. The header gives it a name and a description; the description is what an agent reads to decide whether this skill fits the task in front of it. The body says how to do the job.
---
name: example-send-inquiry
description: Send one project inquiry on behalf of a user who asked you to.
---
# Send a project inquiry
POST https://example.com/contact/send
Fields: name, email, message (20+ characters) ...The format grew out of agent tooling, where skills package reusable know-how, and the open Agent Skills project documents it. Publishing skills on your website applies the same idea outward: you write the instructions once, and any capable agent can follow them.
The discovery index and digests
A proposed discovery format, the Agent Skills Discovery RFC, puts an index at /.well-known/agent-skills/index.json. It declares a $schema and lists each skill with its name, type, description, URL and a digest in the form sha256:<hex>.
The digest is the useful part. An agent that fetches a skill can hash it and compare. If the two match, it has the file the publisher intended. If they do not, the file changed after the index was written, or something in between altered it. Regenerate the index whenever a skill changes; we compute ours at build time so the two can never disagree.
The ai-catalog (draft)
The Agentic Resource Discovery specification, published at agenticresourcediscovery.org and currently a draft, defines /.well-known/ai-catalog.json: one manifest listing the agent-facing resources a host publishes, such as skills, MCP server cards and agent cards. Each entry has an identifier, a display name, a media type and a URL, plus a few example queries so registries can index it.
Two things we learned implementing it:
- Media types are strict. Validators check entries against a fixed list of discovery types. A skill is listed as
text/markdown; profile="urn:air:agent-skills". Plain API descriptions do not belong here; they belong in an API catalog. - The host block is small. Extra fields you might expect, like a site URL or description, can fail schema validation. Keep to the fields the current schema allows.
Because it is a draft, check the published schema before relying on any example, including ours.
How they fit with llms.txt
| File | Answers | Location |
|---|---|---|
| llms.txt | What is this site and what should I read? | /llms.txt |
| Skills index | How do I do a specific job here? | /.well-known/agent-skills/index.json |
| ai-catalog.json | What agent resources does this host publish? | /.well-known/ai-catalog.json |
They are complementary, not alternatives. llms.txt orients a language model. The skills index and ai-catalog tell an agent what it can do and how. The API catalog describes the endpoints the skills call. Link them to each other: on this site, the homepage Link header points to both llms.txt and the skills index, and the ai-catalog lists all three of our skills.
Writing skills that work
- One job per skill. "Send an inquiry" and "understand what we do" are different skills with different rules.
- A description that says when to use it, in the words a user might use. The description is how the agent chooses.
- Exact mechanics: the request, the fields, limits, response codes and what each error means.
- Boundaries: what the agent must not do. Ours say to act only when the user asked, to use the user's real details, and to show the message before sending.
- Accurate facts: a skill that describes your business should say what you do and do not claim, so agents do not invent it for you.
For the wider picture of what agents need from a site, see the agent readiness checklist.
An example from this site
This site publishes three skills, each with one job. One helps an agent describe what we do accurately, including what we do not claim. One explains how to send a project inquiry for a user who asked for it: the endpoint, the fields, the limits, the error responses, and the rule that the user sees the message before it is sent. The third explains how to run our agent-readiness scan through its JSON API and how to explain the result to a user.
All three are listed in /.well-known/agent-skills/index.json with their digests, and in /.well-known/ai-catalog.json with example queries such as "is example.com ready for AI agents". The skill files are plain Markdown, so you can read them in a browser and judge whether they would make sense to an agent.
Keeping skills current
A skill is documentation that an agent will act on literally, so stale instructions do real harm. If an endpoint changes, a field is renamed or a limit moves, update the skill in the same change, regenerate the index so the digest matches, and review the ai-catalog entry. Treat skills like code: keep them in version control, review changes, and test them by asking an agent to follow them against your live site.
Next step
Start with one skill for the most common thing an agent would do on your site. Publish it with an index and digest, then list it in an ai-catalog. The free agent-readiness scan checks both files and whether the catalog validates. If you want the skills written and wired to real APIs, our agent engineering work covers it.