cloudflare/agent-skills-discovery-rfc

cloudflare/agent-skills-discovery-rfc

Description: A mechanism for discovering Agent Skills using the .well-known URI path prefix as specified in RFC 8615 for discovering Agent Skills.

License: Apache-2.0

Stars: 304

Forks: 15

Open issues: 4

Created: 2026-01-21T14:38:12Z

Pushed: 2026-04-23T21:02:00Z

Default branch: main

Fork: no

Archived: no

README:

Agent Skills Discovery via Well-Known URIs

Status: Draft Version: 0.2.0 Published Date: 2026-01-17 Updated Date: 2026-03-12

Table of Contents

1. [Abstract](#abstract) 2. [Changelog](#changelog) 3. [Terminology](#terminology) 4. [Problem](#problem) 5. [Solution](#solution) 6. [URI Structure](#uri-structure) 7. [Skill Directory Contents](#skill-directory-contents) 8. [Progressive Disclosure](#progressive-disclosure) 9. [Discovery Index](#discovery-index) 10. [Integrity and Verification](#integrity-and-verification) 11. [Archive Distribution](#archive-distribution) 12. [Examples](#examples) 13. [HTTP Considerations](#http-considerations) 14. [Client Implementation](#client-implementation) 15. [Security Considerations](#security-considerations) 16. [Relationship to Existing Specifications](#relationship-to-existing-specifications) 17. [References](#references)

Abstract

This document defines a mechanism for discovering Agent Skills using the .well-known URI path prefix as specified in RFC 8615. Skills are currently scattered across GitHub repositories, documentation sites, and other sources. A well-known URI provides a predictable location for agents and tools to discover skills published by an organization or project.

Changelog

v0.2.0

• rename well-known URI from /.well-known/skills/ to /.well-known/agent-skills/
• replace version field with $schema URI (https://schemas.agentskills.io/discovery/0.2.0/schema.json)
• replace files array and package object with a flat single-artifact model: each skill entry now has type ("skill-md" or "archive"), url, and digest
• digest is now the SHA-256 of the single artifact (not a manifest-derived skill-level digest)
• add archive safety guidance: path traversal, symlinks, decompression bombs
• add URL resolution semantics per RFC 3986
• add RFC 2119 / RFC 8174 keyword conventions
• strengthen script execution guidance — clients SHALL NOT execute scripts by default
• add "Integrity and Verification" section
• add "Archive Distribution" section
• add backward-compatibility guidance for v0.1.0 clients

v0.1.0

• initial draft

Terminology

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 RFC 2119 RFC 8174 when, and only when, they appear in all capitals, as shown here.

Problem

Agent Skills give AI agents domain-specific capabilities through structured instructions, scripts, and resources. Today, discovering skills requires:

• Searching GitHub repositories
• Reading vendor documentation
• Following links shared on social media
• Manual configuration by end users

There is no standard way to answer: "What skills does example.com publish?"

Solution

Register agent-skills as a well-known URI suffix. Organizations can publish skills at:

https://example.com/.well-known/agent-skills/

This provides a single, predictable location where agents and tooling can discover and fetch skills without prior configuration.

URI Structure

Publishers MUST provide an index at:

/.well-known/agent-skills/index.json

Each skill in the index includes a url field pointing to its artifact. While publishers conventionally host skill files under /.well-known/agent-skills/, the url field allows skills to be hosted at any location (e.g., on a CDN or at a versioned path).

Skill names MUST conform to the Agent Skills specification:

• 1-64 characters
• Lowercase alphanumeric and hyphens only (a-z, 0-9, -)
• MUST NOT start or end with a hyphen
• MUST NOT contain consecutive hyphens

Skill Directory Contents

A skill consists of a required SKILL.md file and optional supporting resources:

skill-name/
├── SKILL.md # Required: instructions + metadata
├── scripts/ # Optional: executable code
│ └── extract.py
├── references/ # Optional: documentation
│ └── REFERENCE.md
└── assets/ # Optional: templates, data files
└── schema.json

Skills consisting of SKILL.md alone are typically distributed as individual files (type: "skill-md" in the index). Skills with supporting resources are distributed as archives (type: "archive" in the index). See [Discovery Index](#discovery-index) for details.

The SKILL.md file MUST contain YAML frontmatter with name and description fields, followed by Markdown instructions.

Progressive Disclosure

Skills use a progressive loading pattern to manage context efficiently:

| Level | What | When Loaded | Token Cost | |-------|------|-------------|------------| | 1 | name + description from index | At startup or when probing | ~100 tokens per skill | | 2 | Full SKILL.md body | When skill is activated | [!NOTE] > In a future version, url may become optional for type: "skill-md" entries, defaulting to /.well-known/agent-skills/{name}/SKILL.md.

URL Resolution

The url field specifies where to fetch the skill artifact. URLs are resolved per RFC 3986 Section 5 using the index URL as the base URI. URLs may be:

• Path-absolute (resolved against the index origin): /.well-known/agent-skills/code-review/SKILL.md
• Absolute (fully qualified): https://cdn.example.com/v2/skills/code-review/SKILL.md
• Relative (resolved against the index URL directory): code-review/SKILL.md

For type: "skill-md", url conventionally follows the pattern /.well-known/agent-skills/{name}/SKILL.md, though publishers MAY use any URL.

For type: "archive", url points to the archive file. Clients SHOULD determine the archive format from the server's Content-Type header, falling back to the URL file extension if the header is absent or generic (e.g., application/octet-stream). See [Archive…