# Agent skills and the ai-catalog: telling agents how to use your site

> What SKILL.md agent skills are, how the skills discovery index and its digests work, what the draft ai-catalog adds, and how they fit with llms.txt.

Canonical page: https://aispeedforce.com/blog/agent-skills-and-ai-catalog/

Last updated: 2026-09-23

Agent skills are short instruction files that teach an agent to do one job with your site. A discovery index lists them, and the draft ai-catalog lets registries find them.

[Agent readiness](https://aispeedforce.com/blog/category/agent-readiness/) Published 23 September 2026 5 min read By AI SpeedForce

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](https://aispeedforce.com/blog/llms-txt-explained/) 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](https://agentskills.io/) 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](https://github.com/cloudflare/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.

From discovery to a completed task

## The ai-catalog (draft)

The Agentic Resource Discovery specification, published at [agenticresourcediscovery.org](https://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](https://aispeedforce.com/blog/api-catalog-and-link-headers/).
- **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 |

Three files, three jobs

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](https://aispeedforce.com/blog/api-catalog-and-link-headers/) 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.

Writing a good skill

For the wider picture of what agents need from a site, see the [agent readiness checklist](https://aispeedforce.com/blog/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](https://aispeedforce.com/agent-ready/) 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](https://aispeedforce.com/agent-ready/) checks both files and whether the catalog validates. If you want the skills written and wired to real APIs, our [agent engineering work](https://aispeedforce.com/services/agent-engineering/) covers it.

## Questions about this topic

### What is the difference between llms.txt and an agent skill?

llms.txt describes your site and points to what is worth reading. A skill is a set of instructions for doing one specific job, such as sending an inquiry or running a scan, written so an agent can follow it.

### Why does the skills index include a digest?

The sha256 digest lets an agent confirm it fetched exactly the file the index describes. If the file changes, the digest changes, so a stale or altered copy is easy to spot.

### Is the ai-catalog a finished standard?

No. The Agentic Resource Discovery specification behind it is a draft, so field names and allowed media types may still change. Validate against the current schema rather than older examples.

## Related posts

- [The agent readiness checklist: 22 checks for an AI-ready website](https://aispeedforce.com/blog/agent-readiness-checklist/): Agent readiness 23 September 2026. Twenty-two checks in six groups, from robots.txt and llms.txt to API catalogs, agent skills and WebMCP. What each one tells an AI agent, which ones every site needs, and which only matter if you run APIs or sell online.
- [MCP servers for business: when you need one and how to keep it safe](https://aispeedforce.com/blog/mcp-servers-for-business/): Agent readiness 23 September 2026. An MCP server exposes your systems to AI agents through one standard interface. It is worth building when agents need to act inside your business, not just read about it.
- [Markdown for agents: serving Markdown with content negotiation](https://aispeedforce.com/blog/markdown-for-agents-content-negotiation/): Agent readiness 23 September 2026. Agents read Markdown far more cheaply than HTML. Serve a Markdown copy when a request asks for text/markdown, keep HTML the default, and link the copy from every page.
- [All posts](https://aispeedforce.com/blog/)
- [More on Agent readiness](https://aispeedforce.com/blog/category/agent-readiness/)
- [Agent-readiness scan](https://aispeedforce.com/agent-ready/)

## See how your own site scores

The free agent-readiness scan checks the files, headers and endpoints this blog writes about, and tells you what to fix first.