# How to publish an agent skills index for your site

> Build /.well-known/agent-skills/index.json from your SKILL.md files with a digest per skill, and check the deployed index the way an agent client reads it.

Source: https://voxgig.com/howto/publish-an-agent-skills-index

- Audience: agent-builder
- Level: advanced
- Languages: typescript
- Verified: 2026-11-21
- Published: 2026-11-21

## Short answer

Keep each agent skill as a directory with a SKILL.md, and let a build step write /.well-known/agent-skills/index.json from those files. Each entry takes its name and description from the frontmatter, plus a type, a URL, and the SHA-256 digest of the bytes served. Refuse a description with no "Use when" clause, then fetch the deployed index in CI and fail on any digest or description that disagrees.

---
## You will need

Node 22 or later, at least one written agent skill, and a site that serves static files under
`/.well-known/`. Verified 2026-11-21 against Node 22.23.5 and `yaml` 2.9.1. The index format is
the [Agent Skills Discovery draft](https://github.com/cloudflare/agent-skills-discovery-rfc)
in Cloudflare's repository, which marks itself a draft at version 0.2.0. The `agent-skills`
suffix is not in the [IANA registry](https://www.iana.org/assignments/well-known-uris) of
well-known suffixes.[^1] Serve the
files with the headers from
[publishing an OpenAPI document at a stable URL](/howto/publish-openapi-at-a-stable-url).

## Approaches compared

| Approach | When it fits | What it costs you | When to pick something else |
| --- | --- | --- | --- |
| [Build step over SKILL.md front matter](https://agentskills.io/specification) | Skills kept as directories in the repository that builds the site | A script to own, and descriptions it can check but never write for you | The skills live in a registry the build cannot read |
| [Hand-written index file](https://github.com/cloudflare/agent-skills-discovery-rfc) | One or two skills that change once a release | A digest recomputed by hand after every edit, or a client rejects the skill | Anyone edits a `SKILL.md` without touching the index |
| [NSwag](https://github.com/RicoSuter/NSwag/wiki/CommandLine) | A .NET API whose agents work from its C# or TypeScript client | No markdown output at all, so every skill body is written by hand | You want reference files generated beside the client |
| [sdkgen generated reference with a skill script](https://github.com/voxgig/sdkgen) | An sdkgen project whose skill must follow each regeneration | No `SKILL.md` from the generator, and no operation summaries in its reference | The skill describes a task, not an API |
| [Swagger Codegen docs as skill references](https://swagger.io/docs/open-source-tools/swagger-codegen/codegen-v3/generation-selective/) | A Swagger Codegen client whose markdown docs can ship inside an archive skill | Frontmatter and the "Use when" sentence by hand, over docs for every operation | Agents need one entry point rather than a page per operation |

Voxgig maintains sdkgen. It is one source of skill content among five here, and the index is
built the same way whichever one you use.

The hand-written index is the smallest change and the first to fail a client's digest check. The
build step removes that failure for the price of a script. NSwag and Swagger Codegen both
regenerate with the client, but only Swagger Codegen writes markdown a skill can carry, and
sdkgen writes reference files without the summaries the other two keep.

## Build the index from the skill files

The draft fixes the location and the fields. Each entry needs a `name`, a `type`, a
`description`, a `url`, and a `digest`, under a top-level `$schema` that a client checks
before it processes the index.

```json title="site/.well-known/agent-skills/index.json"
{
  "$schema": "https://schemas.agentskills.io/discovery/0.2.0/schema.json",
  "skills": [
    {
      "name": "bookshelf-python-client",
      "type": "archive",
      "description": "Call the Bookshelf API from Python with the swagger_client package that Swagger Codegen generated: list_books, create_book, get_book, update_book, and delete_book. Use when Python code must read or change books through the Bookshelf API.",
      "url": "/.well-known/agent-skills/bookshelf-python-client.tar.gz",
      "digest": "sha256:53e9ace500c1e825cc756792a16fc1b3605f5a450bfca3b6e90cf4e3e0e3f615",
      "version": "1.0.0"
    },
```

`build-index.mjs` reads every value from the files it describes. A skill that is a lone
`SKILL.md` is served as that file, as `skill-md`. A skill with references goes out as one
reproducible `.tar.gz`, as `archive`, because the draft gives an entry a single URL.

```js title="build-index.mjs"
export function buildIndex(src) {
  const artifacts = new Map()
  const skills = readSkills(src).map((s) => {
    let url
    let bytes
    let type
    if (s.files.length === 1) {
      type = 'skill-md'
      url = `${BASE}/${s.name}/SKILL.md`
      bytes = s.skillMd
    } else {
      type = 'archive'
      url = `${BASE}/${s.name}.tar.gz`
      bytes = pack(s.files.map((path) => ({ path, bytes: readFileSync(join(src, s.dir, path)) })))
    }
    artifacts.set(url, bytes)
    const entry = { name: s.name, type, description: s.description, url, digest: digestOf(bytes) }
    // Not a field of the draft. A v0.2.0 client must ignore it, and compares the digest instead.
    if (s.version !== undefined) entry.version = s.version
    return entry
  })
```

The draft has no version field. Version 0.2.0 replaced the old top-level `version` with
`$schema`, and a client detects a changed skill by its digest. The draft tells clients to ignore
fields it does not define. The builder copies `metadata.version` from the frontmatter for people
reading the index, a free-form key the
[Agent Skills specification](https://agentskills.io/specification) uses for a version in its own
example.

```bash
node build-index.mjs skills site
```

```text output
site/.well-known/agent-skills/index.json: 3 skills
  bookshelf-python-client  archive    2104 bytes  sha256:53e9ace500c1
  bookshelf-ts-sdk         archive    2616 bytes  sha256:3df2da03cdc2
  release-notes            skill-md    561 bytes  sha256:3c21d5538eca
```

Progressive disclosure holds because the index carries descriptions and no bodies. The three
artifacts stay behind their URLs until a task matches one.

## Write descriptions a client can match

A client loads only the names and descriptions at startup, so the description is the whole basis
for choosing a skill. The specification asks it to say what the skill does and when to use it,
with keywords. The build refuses a description that does neither.

```js title="skill-md.mjs"
const SELLING = ['ultimate', 'supercharge', 'all-in-one', 'unleash', 'next-level', 'world-class']

export function descriptionProblems(description) {
  const out = []
  if (typeof description !== 'string' || description.trim().length === 0) return ['description is missing']
  if (description.length > 1024) out.push(`description is ${description.length} characters, the limit is 1024`)
  if (!/\bUse (it |this )?when\b/.test(description)) out.push('description never says when to use the skill ("Use when ...")')
```

The word list is crude and catches the obvious cases only. The "Use when" rule does more of the
work, because a sentence that names the task is the one a client can match.

## Turn sdkgen output into a skill

sdkgen 4.44.3 has no skill output, although the [product page](https://voxgig.com/sdk) lists
Agent Skills among its surfaces. The scaffold built the TypeScript target from `api.json`, and
`generators.mjs` reads what each generator left in `generated/`.

```bash
node generators.mjs
```

```text output
sdkgen, ts target
  markdown files: 16, of them SKILL.md: 0
  README.md 6, AGENTS.md 3, CLAUDE.md 3, REFERENCE.md 1
  operation summaries in ts/REFERENCE.md: 0 of 5
Swagger Codegen, python
  markdown files: README.md, docs/Book.md, docs/DefaultApi.md
  operation summaries in them: 5 of 5
NSwag, openapi2tsclient
  commands in nswag help: 9, aspnetcore2openapi jsonschema2csclient jsonschema2tsclient new openapi2csclient openapi2cscontroller openapi2tsclient run version
  operation summaries in client.ts doc comments: 5 of 5
```

The word "skill" appears in no file of `@voxgig/sdkgen`, `@voxgig/apidef`, or `@voxgig/docgen`,
nor in the add-on packages `@voxgig/sdkgen-infrapack` 0.0.20 and `@voxgig/sdkgen-langpack` 0.0.16.
The one `SKILL.md` in the project sits in `.sdk/node_modules/aontu`, and it teaches the model
language. Version 4.45.0 with `@voxgig/apidef` 8.33.1 wrote the same `ts/` tree and no skill.

`ts/REFERENCE.md` is the useful file. `from-sdkgen.mjs` reads its entity sections and writes a
`SKILL.md` that lists `book` with its fields and five operations, then ships the reference beside
it. The "Use when" sentence is the script's, because the model holds no statement of purpose.

## Build the same skills from NSwag and Swagger Codegen output

[Swagger Codegen](https://swagger.io/docs/open-source-tools/swagger-codegen/codegen-v3/generation-selective/)
writes API and model docs with every client unless `-DapiDocs=false` or `-DmodelDocs=false`
turns them off. Its Python run produced a README and two docs carrying all five summaries.
`generate.sh` copies them under `references/` in `bookshelf-python-client`, and the build packs
the directory as an archive. Only the `SKILL.md` was written by hand.

[NSwag](https://github.com/RicoSuter/NSwag) has no route to a skill. None of the nine commands
in its 14.8.0 help writes markdown. Six generate code or an OpenAPI document, and `new`, `run`,
and `version` handle its configuration file and its version.[^2] Its TypeScript client keeps each summary as a doc comment.

```ts title="generated/nswag/client.ts"
    /**
     * List the books on the shelf
     * @return A page of books
     */
    listBooks(): Promise<Book[]> {
```

With NSwag, write the `SKILL.md` by hand against those signatures and put it in `skills/` like
any other. The build step indexes it without knowing which generator made the client.

## Check it worked

`check.mjs` reads an index as a client does. It wants the v0.2.0 `$schema`, the content types
the draft requires, and a digest that matches the bytes. It also requires each description to
equal the one in the `SKILL.md`. For an archive, it joins each tar header's `ustar` prefix to its
name, as an extractor does. It refuses a path that leaves the skill directory, a link, a device,
and any header type it does not read. `demo.mjs` serves the committed `site/` on 127.0.0.1 and
runs it.

```bash
node demo.mjs
```

```text output
bookshelf-python-client  archive  ok
bookshelf-ts-sdk         archive  ok
release-notes            skill-md ok
index ok

at startup a client reads index.json: 1604 bytes
behind the three urls, fetched only when a task matches: 5281 bytes
```

Run `node check.mjs https://example.com` against the deployed site in CI. It exits 1 when any check
fails.

```bash
node --test index.test.mjs
```

```text output
1..22
# tests 22
# suites 0
# pass 22
# fail 0
# cancelled 0
# skipped 0
# todo 0
```

The suite rebuilds `site/` and compares it byte for byte with the committed copy. It refuses an
artifact on a second origin unless that origin is allowed, as the draft's security section asks,
and also one that a redirect moves to a second origin.

## When it goes wrong

```bash
node pitfall.mjs
```

```text output
1. release-notes/SKILL.md edited after the index was written
bookshelf-python-client  archive  ok
bookshelf-ts-sdk         archive  ok
release-notes            skill-md FAIL
  digest does not match the bytes served
index FAILED

2. node build-index.mjs fixtures/marketing
index not built:
  bookshelf-helper: description never says when to use the skill ("Use when ...")
  bookshelf-helper: description sells instead of describing: ultimate, supercharge, all-in-one, unleash

3. node build-index.mjs fixtures/colon
index not built:
  bookshelf-python-client: Nested mappings are not allowed in compact mappings at line 2, column 14:
```

A client drops a skill after a one-line edit. The index was written by hand, or deployed apart
from the file. Build both in one step and deploy them together.

The build refuses a description written as advertising. It names no task, so no client can match
it. Rewrite it as what the skill does, then "Use when" and the task.

The build stops on a YAML error at a description. An unquoted `: ` inside a plain scalar starts a
mapping, so the frontmatter is not valid YAML. Quote the description, as `bookshelf-python-client`
does.

## When not to do this

Do not build an index for a single skill that changes once a year. A hand-written entry and a
`sha256sum` at release time cost less than a script.

Do not use sdkgen for skills that describe a workflow rather than an API, such as `release-notes`.
Its reference describes entities and operations, so it has nothing to say about a release process.

Do not treat sdkgen's reference as enough for an API skill. It drops operation summaries, so the
skill says how to call each operation and not what it is for.

Pick Swagger Codegen when you already ship its client, because its docs carry the summaries.
NSwag keeps every summary as a doc comment, which sdkgen drops, so a .NET team that writes its
skills by hand from typed signatures has more to work from. Do not point an entry
at a CDN you do not control, because a client that allowlists your origin refuses it.

## Related how-tos

- [Publish an OpenAPI document at a stable URL for agents](/howto/publish-openapi-at-a-stable-url)

- [Install an API skill and check a coding agent uses it](/howto/install-an-api-skill-for-a-coding-agent)

- [Generate agent skills for your API from a semantic model](/howto/generate-agent-skills-from-an-api-model)

- [Write a skill description that triggers at the right time](/howto/write-a-skill-description-that-triggers)

- [Distribute agent skills to a team](/howto/distribute-agent-skills-to-a-team)

## Last verified

Verified 2026-11-21 against Node 22.23.5, `yaml` 2.9.1, @voxgig/create-sdkgen 0.31.9,
@voxgig/sdkgen 4.44.3, @voxgig/apidef 8.32.4, Swagger Codegen 3.0.85, and NSwag 14.8.0. Every
output block is what the command preceding it printed. Each generator ran once in `generate.sh`,
and what it wrote is committed under `generated/`. NSwag ran once on the ASP.NET Core 10 runtime.
No agent client was run.

[^1]: [RFC 8615](https://www.rfc-editor.org/rfc/rfc8615.html#section-3) says anything that mints a
well-known URI must register it, and that squatting on generic terms is not encouraged. The
registry has an entry for `agent-card.json`, from the A2A protocol, but none for skills. The draft calls
its own `$schema` value an opaque identifier that need not be resolvable, which suits it, because
`schemas.agentskills.io` accepted no connection when the page was verified.

[^2]: The [command-line page](https://github.com/RicoSuter/NSwag/wiki/CommandLine) of NSwag's
wiki lists seven commands, including `webapi2openapi` and `types2openapi`. The help printed by
14.8.0 on .NET 10 lists nine, without either of those two. The same wiki page
tells its reader to see every command by running the tool and entering `help`, which is how the
nine were listed.