What we check

We fetch /.well-known/skills/index.json. It passes when it is JSON with a non-empty skills array whose first entry has a name string. Your report shows how many skills we found.

What an agent skill is

A skill is a folder with a SKILL.md file: step-by-step instructions, and optionally scripts and reference files, that an agent loads when it needs to do one specific job. The format started at Anthropic and is now an open specification at agentskills.io, supported by a range of agent products.

Agents usually fail at a product for the reason a new hire does. They lack the context: which endpoint to call first, which field is required, which error means "retry" and which means "stop". A skill gives them that context in a form they can follow.

Write a first skill

A SKILL.md starts with a short header, then instructions:

---
name: create-invoice
description: Create and send an invoice with the Acme API. Use when the user asks to bill a customer.
---

# Create an invoice

1. Look up the customer with GET /v1/customers?email=...
2. If none exists, create one with POST /v1/customers.
3. Create the invoice with POST /v1/invoices, passing customer_id and line items.
4. Send it with POST /v1/invoices/{id}/send.

Amounts are in cents. A 409 response means the invoice was already sent.

The description matters most. It is what an agent reads when it decides whether to load the skill, so say what the skill does and when to use it.

Publish the index

{
  "skills": [
    {
      "name": "create-invoice",
      "description": "Create and send an invoice with the Acme API.",
      "url": "https://acme.com/skills/create-invoice/SKILL.md"
    }
  ]
}

The well-known index is a convention that is still settling, and the field that points at each skill's files varies between implementations. We only require name on each entry. Include a description and a link so an agent can do something with it.

Keep skills current

A skill that names a renamed endpoint is worse than no skill, because the agent trusts it. Publish skills from the same pipeline as your API docs, so they change when the API does.