An agent client fetches /.well-known/agent-skills/index.json from your site and drops the
release-notes skill. Someone added a step to its SKILL.md after the index was written, so
the digest in the index no longer matches the file. Both skills it keeps call themselves an
all-in-one toolkit, which gives the client no way to match either one to a task.
What you get
You will end up with a build step that writes the index from your skill files, a description check, and a CI check that reads the deployed index as a client does. This is for you if your site publishes skills for agents to install.
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
in Cloudflare’s repository, which marks itself a draft at version 0.2.0. The agent-skills
suffix is not in the IANA registry of
well-known suffixes.1 Serve the
files with the headers from
publishing an OpenAPI document 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 | 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 | 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 | 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 | 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 | 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.
{
"$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.
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 uses for a version in its own
example.
node build-index.mjs skills site
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.
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 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/.
node generators.mjs
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
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 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.
/**
* 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.
node demo.mjs
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.
node --test index.test.mjs
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
node pitfall.mjs
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
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.
Footnotes
-
RFC 8615 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$schemavalue an opaque identifier that need not be resolvable, which suits it, becauseschemas.agentskills.ioaccepted no connection when the page was verified. ↩︎ Back to text -
The command-line page of NSwag’s wiki lists seven commands, including
webapi2openapiandtypes2openapi. 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 enteringhelp, which is how the nine were listed. ↩︎ Back to text