# Agent-Skills
> How to publish agent skills a site can be operated by: the index, SKILL.md frontmatter, digests, and the naming rules the specification enforces.
Diese Prüfung trägt 2 % des Scores.
*Diese Leitfäden zur Behebung sind in englischer Sprache verfasst.*
A skill is a written procedure an agent can load: how to use your API, how to file a ticket in your tracker, what your product's terms of art mean. Publishing them at a known path lets an agent pick up your instructions instead of inferring them from your marketing pages.
```
/.well-known/agent-skills/index.json
/.well-known/agent-skills/deploy-a-site/SKILL.md
```
The check reports not applicable for a site with no skills and no documentation signals at all. A docs site without them is worth knowing about; a restaurant without them is not.
---
## No skills index found
Nothing at `/.well-known/agent-skills/index.json` or the Mintlify variant at `/.well-known/skills/index.json`. If you publish documentation an agent is meant to act on, an index is how it finds the procedure rather than reading the whole site.
---
## The index is not valid JSON
Served and unparseable. Check for a trailing comma, and check that the path is not falling through to an HTML error page returned with a `200`.
---
## The index declares no $schema
The specification is a draft and moving. Naming the revision you wrote against is what lets a reader validate rather than guess.
```
"$schema": "https://schemas.agentskills.io/discovery/0.2.0/schema.json"
```
---
## Skill files with no index
A `SKILL.md` exists at a conventional path and no index lists it. An agent that does not already know the filename cannot find it, so the skill is published and undiscoverable.
---
## An empty index
Valid, and lists no skills. A request spent to learn there is nothing here. Either list them or remove the file.
---
## A name the specification rejects
Names are lower-case, hyphenated, one to sixty-four characters: `^[a-z0-9-]{1,64}$`. Spaces, capitals and underscores are rejected, and the name must match the directory the skill lives in.
---
## A skill with no description
The description is what an agent reads to decide whether to load the skill at all. Without it the skill is fetched by everything or by nothing, and neither is what you wanted.
---
## A description over 1024 characters
The index is a menu, not the meal. Long descriptions belong in the skill body; the index entry exists to be scanned cheaply, and the limit is a thousand and twenty-four characters.
---
## An unrecognised type
A skill is either `skill-md`, a single Markdown document, or `archive`, a bundle with supporting files. Anything else is skipped by a reader that validates.
---
## A skill with no url
The entry names a skill and does not say where it is. Absolute or root-relative, either is fine; absent is not.
---
## A skill with no digest
The digest is what lets an agent cache a skill and know when it changed, and what lets it detect a skill that changed when it should not have. A skill is an instruction an agent will follow, so tamper evidence is not ceremony.
```
"digest": "sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
```
---
## A malformed digest
The format is `sha256:` followed by exactly sixty-four lower-case hexadecimal characters. A truncated hash, a different algorithm or upper-case hex will not validate.
---
## A skill that does not resolve
The index names it and fetching it fails, or it comes back as something other than Markdown. Same failure as a dead catalog entry: the index sends every agent that trusts it to a URL that answers nothing.
---
## SKILL.md with no frontmatter
Each skill document opens with a small block naming itself. The `name` must match both the index entry and the directory, which is what makes a skill verifiable rather than merely present.
```
---
name: deploy-a-site
description: How to deploy a project, from a fresh clone to a live URL.
---
## Before you start
…
```
---
## A very long SKILL.md
Informational. A skill over roughly five hundred lines is usually several skills, and an agent loading it pays for all of it to use any of it. Splitting by task keeps the loaded context proportional to the job.
> **Skills are read, not indexed**
>
> Unlike llms.txt, a skill is loaded into a working context and competes with the user's own request for room. Length has a direct cost here that it does not have in a sitemap.
---
Markdown-Darstellung von https://axrush.com/guides/agent-skills