cloudflare/agent-skills-discovery-rfc: a well-known URI for publishing Agent Skills

The gap this draft fills: answering what skills a domain publishes

The README states the problem plainly: skills are scattered across GitHub repositories, documentation sites and social media links, and there is no standard way to answer the question "What skills does example.com publish?" Today that answer is assembled by hand, by searching repositories or reading vendor docs. The draft proposes registering agent-skills as a well-known URI suffix under RFC 8615, so the answer lives at a single predictable location. The audience is twofold: organizations that publish skills and want them discoverable, and the tool and agent authors who would otherwise hard-code per-vendor lookup logic. Note the status line at the top of the document. It reads Draft, version 0.2.0, published 2026-01-17 and updated 2026-03-12. That is the whole of the maturity signal in the repository, and it matters more than any feature list here.

How discovery works: index.json, artifact types and progressive disclosure

Publishers MUST provide an index at /.well-known/agent-skills/index.json. Each entry in that index carries a type of either "skill-md" or "archive", a url, and a digest. The url field is deliberately loose: while publishers conventionally host skill files under /.well-known/agent-skills/, the index can point anywhere, including a CDN or a versioned path. That is a sensible decoupling, and it also means the well-known path is a pointer, not a guarantee about where bytes live.

The digest is the SHA-256 of the single artifact, which is a change from the earlier draft where it was derived from a manifest. Version 0.2.0 also replaced the files array and package object with this flat, single-artifact model, and renamed the path from /.well-known/skills/ to /.well-known/agent-skills/. Anyone who built against 0.1.0 has a rename and a schema change to absorb; the changelog includes backward-compatibility guidance, which is the right place to look before upgrading.

Loading is staged. Level 1 is the name and description from the index, roughly 100 tokens per skill. Level 2 is the full SKILL.md body, recommended under 5k tokens, fetched when a task matches the description. Level 3 is referenced files, loaded on demand from an unpacked archive. A skill can therefore bundle a large references directory without paying context cost up front. The README's own example is a pdf-processing skill that links to references/FORMS.md and references/TABLES.md; an agent extracting text stops at SKILL.md, while one filling a tax form follows the forms link. Skill names must conform to the Agent Skills specification: 1 to 64 characters, lowercase alphanumerics and hyphens, no leading or trailing hyphen, no consecutive hyphens.

Publishing an index: what the example files actually give you

There is no install step in the README, and the repository is not a package. It is a specification plus examples. The top-level entries are LICENSE, README.md and examples/, and the examples directory holds four server-side implementations: examples/skills-index.astro.ts, examples/skills-index.cgi, examples/skills-index.nextjs.ts and examples/skills-index.tanstack.ts. Those filenames are the concrete starting points; pick the one matching your framework and serve the JSON at the well-known path.

A minimal SKILL.md is YAML frontmatter with name and description, followed by Markdown instructions. The README gives this example, which is reproduced here exactly as the document presents it:

---
name: pdf-processing
description: Extract text and tables from PDF files. Use when working with PDFs or document extraction.
---

# PDF Processing

## Quick Start

Use pdfplumber to extract text:

python import pdfplumber

with pdfplumber.open("document.pdf") as pdf: text = pdf.pages[0].extract_text()

## Form Filling

For filling PDF forms, see [references/FORMS.md](references/FORMS.md).

## Advanced Table Extraction

For complex tables with merged cells, see [references/TABLES.md](references/TABLES.md) and run `scripts/extract_tables.py`.

To check what a client would see, request the index path directly and confirm you get JSON rather than an HTML error page or a redirect. The README does not document a reference client or CLI for this, so there is nothing to install on the consuming side from this repository alone.

Where the draft is thin, and where it is the wrong tool

The security section is the most opinionated part, and it is opinionated in a useful direction: clients SHALL NOT execute scripts by default. That single rule removes the most obvious remote-code path, but it also means a skill whose value comes from bundled scripts will not do anything on its own. Archive distribution carries its own guidance covering path traversal, symlinks and decompression bombs, which tells you the authors expect archives to be untrusted input. If your skills need to run code on the client without an explicit opt-in, this convention is not shaped for you.

The bigger gap is authentication. The document describes discovery at a well-known path, which in practice is public and unauthenticated. There is no described flow for a private skill catalog, per-tenant indexes, or authorization on the artifact URLs. If your skills are internal, the well-known path is the wrong place to put them, and the README does not offer an alternative.

The digest story is also narrower than it first appears. Because each entry digests a single artifact, an archive-based skill is verified as one blob; the README does not describe per-file digests inside the archive, so integrity checking stops at the container. Finally, the url field's flexibility cuts both ways. Pointing at a CDN is allowed, but nothing in the index ties that URL to the domain the client probed, so a client that trusts the index is trusting whatever host the publisher names.

How this differs from installing skills the usual way

The common alternative today is manual or vendor-specific installation: a user copies a skill into a tool's skills directory, or a tool ships a curated set. That model is explicit and auditable, and it works fine when you have three skills. It does not scale to the question the draft is built around, because there is no domain-level answer to what a site publishes.

The difference in approach is the direction of the lookup. Manual installation pushes skills from a known source into a known tool. The well-known URI pulls: an agent probes a domain it already has a reason to talk to and asks what is there. That makes the index a discovery surface rather than a distribution channel. It also means the convention is only as useful as the number of clients that probe the path, and this repository does not ship one. A team that adopts it today is publishing into a namespace that client support has to catch up with.

Maintenance, licensing and what an upgrade costs

The repository is not archived, and the last push was on 2026-04-23. The README's own status block is more informative than that date: version 0.2.0, published 2026-01-17, updated 2026-03-12. The version number is still 0.x, and the changelog shows a breaking rename and a field model replacement between 0.1.0 and 0.2.0. Treat the index format as unstable while it stays below 1.0, and expect that a future revision can move the path or change entry fields again. The changelog's backward-compatibility guidance for v0.1.0 clients is the model for how you should plan your own upgrades.

There are no retrieved releases, so there is nothing to pin against. Licence is Apache-2.0, which permits commercial use and modification; the LICENSE file is at the repository root. This is not legal advice, and the patent grant and notice requirements in Apache-2.0 are worth reading directly if you plan to embed the examples in a product. The practical upgrade cost is small if you generate index.json from a build step, and annoying if you hand-maintain it, because every digest has to be recomputed whenever an artifact changes.

Editorial conclusion

Adopt it if you publish skills and want a predictable, unauthenticated discovery path that any client can probe without prior configuration; the draft's index format, digest rules and archive safety guidance are concrete enough to implement against. Do not adopt it if you need a working client today, or if your skills only make sense behind authentication, since the document does not describe an authenticated discovery flow. Before committing, read the Discovery Index and Integrity and Verification sections in full, confirm your skill names match the Agent Skills naming rules, and check that your hosting layer actually serves /.well-known/agent-skills/index.json rather than redirecting it.

Frequently asked questions

Official sources

1. cloudflare/agent-skills-discovery-rfc on GitHub
2. Issues
3. License: Apache-2.0
4. README