Skip to content
Back to search

agent-skills-discovery-rfc

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

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/cloudflare--agent-skills-discovery-rfc/badge.svg)](/listings/cloudflare--agent-skills-discovery-rfc)

HTML

<a href="/listings/cloudflare--agent-skills-discovery-rfc"><img src="/api/listings/cloudflare--agent-skills-discovery-rfc/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 467 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Agent Skills Discovery via Well-Known URIs
  2. **Status**: Draft
  3. **Version**: 0.2.0
  4. **Published Date**: 2026-01-17
  5. **Updated Date**: 2026-03-12
  6. ## Table of Contents
  7. 1. [Abstract](#abstract)
  8. 2. [Changelog](#changelog)
  9. 3. [Terminology](#terminology)
  10. 4. [Problem](#problem)
  11. 5. [Solution](#solution)
  12. 6. [URI Structure](#uri-structure)
  13. 7. [Skill Directory Contents](#skill-directory-contents)
  14. 8. [Progressive Disclosure](#progressive-disclosure)
  15. 9. [Discovery Index](#discovery-index)
  16. 10. [Integrity and Verification](#integrity-and-verification)
  17. 11. [Archive Distribution](#archive-distribution)
  18. 12. [Examples](#examples)
  19. 13. [HTTP Considerations](#http-considerations)
  20. 14. [Client Implementation](#client-implementation)
  21. 15. [Security Considerations](#security-considerations)
  22. 16. [Relationship to Existing Specifications](#relationship-to-existing-specifications)
  23. 17. [References](#references)
  24. ## Abstract
  25. This document defines a mechanism for discovering [Agent Skills](https://agentskills.io/) using the `.well-known` URI path prefix as specified in [RFC 8615](https://datatracker.ietf.org/doc/html/rfc8615). 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.
  26. ## Changelog
  27. #### v0.2.0
  28. - rename well-known URI from `/.well-known/skills/` to `/.well-known/agent-skills/`
  29. - replace `version` field with `$schema` URI (`https://schemas.agentskills.io/discovery/0.2.0/schema.json`)
  30. - 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`
  31. - `digest` is now the SHA-256 of the single artifact (not a manifest-derived skill-level digest)
  32. - add archive safety guidance: path traversal, symlinks, decompression bombs
  33. - add URL resolution semantics per RFC 3986
  34. - add RFC 2119 / RFC 8174 keyword conventions
  35. - strengthen script execution guidance — clients SHALL NOT execute scripts by default
  36. - add "Integrity and Verification" section
  37. - add "Archive Distribution" section
  38. - add backward-compatibility guidance for v0.1.0 clients
  39. #### v0.1.0
  40. - initial draft
  41. ## Terminology
  42. 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](https://datatracker.ietf.org/doc/html/rfc2119) [RFC 8174](https://datatracker.ietf.org/doc/html/rfc8174) when, and only when, they appear in all capitals, as shown here.
  43. ## Problem
  44. Agent Skills give AI agents domain-specific capabilities through structured instructions, scripts, and resources. Today, discovering skills requires:
  45. - Searching GitHub repositories
  46. - Reading vendor documentation
  47. - Following links shared on social media
  48. - Manual configuration by end users
  49. There is no standard way to answer: "What skills does example.com publish?"
  50. ## Solution
  51. Register `agent-skills` as a well-known URI suffix. Organizations can publish skills at:
  52. ```
  53. https://example.com/.well-known/agent-skills/
  54. ```
  55. This provides a **single, predictable location** where agents and tooling can discover and fetch skills without prior configuration.
  56. ## URI Structure
  57. Publishers MUST provide an index at:
  58. ```
  59. /.well-known/agent-skills/index.json
  60. ```
  61. 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).
  62. Skill names MUST conform to the [Agent Skills specification](https://agentskills.io/specification):
  63. - 1-64 characters
  64. - Lowercase alphanumeric and hyphens only (`a-z`, `0-9`, `-`)
  65. - MUST NOT start or end with a hyphen
  66. - MUST NOT contain consecutive hyphens
  67. ## Skill Directory Contents
  68. A skill consists of a required `SKILL.md` file and optional supporting resources:
  69. ```
  70. skill-name/
  71. ├── SKILL.md # Required: instructions + metadata
  72. ├── scripts/ # Optional: executable code
  73. │ └── extract.py
  74. ├── references/ # Optional: documentation
  75. │ └── REFERENCE.md
  76. └── assets/ # Optional: templates, data files
  77. └── schema.json
  78. ```
  79. 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.
  80. The `SKILL.md` file MUST contain YAML frontmatter with `name` and `description` fields, followed by Markdown instructions.
  81. ## Progressive Disclosure
  82. Skills use a progressive loading pattern to manage context efficiently:
  83. | Level | What | When Loaded | Token Cost |
  84. |-------|------|-------------|------------|
  85. | 1 | `name` + `description` from index | At startup or when probing | ~100 tokens per skill |
  86. | 2 | Full `SKILL.md` body | When skill is activated | < 5k tokens recommended |
  87. | 3 | Referenced files (scripts, references, assets) | On demand, as needed | Unlimited |
  88. **Level 1: Index metadata.** Agents fetch `index.json` to learn what skills exist. Only the name and description are loaded into context initially.
  89. **Level 2: Skill instructions.** When a task matches a skill's description, the agent fetches the skill artifact. For `type: "skill-md"` skills, this is `SKILL.md` directly. For `type: "archive"` skills, the agent downloads the archive and extracts `SKILL.md`. The full instructions are loaded into context.
  90. **Level 3: Supporting resources.** For archive-based skills, the `SKILL.md` body references additional files via relative links. Agents load these from the unpacked archive on demand as the task requires — a form-filling task might need `references/FORMS.md`, while a simple extraction task does not.
  91. This pattern means a skill can bundle extensive reference material without paying a context cost upfront. Agents follow links as needed, loading only what the current task requires.
  92. ### Example: Progressive loading
  93. ````yaml
  94. ---
  95. name: pdf-processing
  96. description: Extract text and tables from PDF files. Use when working with PDFs or document extraction.
  97. ---
  98. # PDF Processing
  99. ## Quick Start
  100. Use pdfplumber to extract text:
  101. ```python
  102. import pdfplumber
  103. with pdfplumber.open("document.pdf") as pdf:
  104. text = pdf.pages[0].extract_text()
  105. ```
  106. ## Form Filling
  107. For filling PDF forms, see [references/FORMS.md](references/FORMS.md).
  108. ## Advanced Table Extraction
  109. For complex tables with merged cells, see [references/TABLES.md](references/TABLES.md) and run `scripts/extract_tables.py`.
  110. ````
  111. An agent handling "extract text from this PDF" loads `SKILL.md` and stops there. An agent handling "fill out this tax form" follows the link to `references/FORMS.md`. The table extraction script and reference stay unfetched until needed.
  112. ## Discovery Index
  113. Publishers MUST provide an index at `/.well-known/agent-skills/index.json`. The index enumerates all available skills, enabling clients to discover skills in a single request.
  114. ### Versioning
  115. The index MUST include a top-level `$schema` field containing a URI that identifies the index schema version. The current schema URI is:
  116. ```
  117. https://schemas.agentskills.io/discovery/0.2.0/schema.json
  118. ```
  119. The `$schema` URI is an **opaque identifier**. Clients MUST match it against known schema URIs to determine how to process the index. The URI does not need to be resolvable, though it MAY point to a [JSON Schema](https://json-schema.org/) document that describes the index format.
  120. Clients encountering an unrecognized `$schema` URI SHOULD warn the user and SHOULD NOT process the index. If `$schema` is absent, clients SHOULD treat the index as v0.1.0 for backward compatibility. Clients MUST ignore unrecognized fields.
  121. ### Index Format
  122. ```json
  123. {
  124. "$schema": "https://schemas.agentskills.io/discovery/0.2.0/schema.json",
  125. "skills": [
  126. {
  127. "name": "code-review",
  128. "type": "skill-md",
  129. "description": "Review code for bugs, security issues, and best practices.",
  130. "url": "/.well-known/agent-skills/code-review/SKILL.md",
  131. "digest": "sha256:c4d5e6f7..."
  132. },
  133. {
  134. "name": "wrangler",
  135. "type": "archive",
  136. "description": "Deploy and manage Cloudflare Workers projects.",
  137. "url": "/.well-known/agent-skills/wrangler.tar.gz",
  138. "digest": "sha256:a1b2c3d4..."
  139. }
  140. ]
  141. }
  142. ```
  143. The index contains a top-level `$schema` field and a `skills` array.
  144. **Top-level fields:**
  145. | Field | Required | Description |
  146. |-------|----------|-------------|
  147. | `$schema` | Yes | URI identifying the index schema version. See [Versioning](#versioning). |
  148. | `skills` | Yes | Array of skill entries. |
  149. **Skill entry fields:**
  150. | Field | Required | Description |
  151. |-------|----------|-------------|
  152. | `name` | Yes | Skill identifier. MUST conform to the [Agent Skills naming specification](https://agentskills.io/specification#name-field): 1-64 characters, lowercase alphanumeric and hyphens only, no leading/trailing/consecutive hyphens. |
  153. | `type` | Yes | Distribution type. MUST be `"skill-md"` (single `SKILL.md` file) or `"archive"` (bundled archive). |
  154. | `description` | Yes | Brief description of what the skill does and when to use it. Max 1024 characters per the Agent Skills spec. SHOULD match the `description` field in the skill's `SKILL.md` frontmatter. |
  155. | `url` | Yes | URL to the skill artifact. For `type: "skill-md"`, this points to the `SKILL.md` file. For `type: "archive"`, this points to the archive file. See [URL Resolution](#url-resolution). |
  156. | `digest` | Yes | SHA-256 content digest of the artifact at `url`, formatted as `sha256:{hex}` where `{hex}` is 64 lowercase hexadecimal characters. See [Integrity and Verification](#integrity-and-verification). |
  157. > [!NOTE]
  158. > In a future version, `url` may become optional for `type: "skill-md"` entries, defaulting to `/.well-known/agent-skills/{name}/SKILL.md`.
  159. ### URL Resolution
  160. The `url` field specifies where to fetch the skill artifact. URLs are resolved per [RFC 3986 Section 5](https://datatracker.ietf.org/doc/html/rfc3986#section-5) using the index URL as the base URI. URLs may be:
  161. - **Path-absolute** (resolved against the index origin): `/.well-known/agent-skills/code-review/SKILL.md`
  162. - **Absolute** (fully qualified): `https://cdn.example.com/v2/skills/code-review/SKILL.md`
  163. - **Relative** (resolved against the index URL directory): `code-review/SKILL.md`
  164. For `type: "skill-md"`, `url` conventionally follows the pattern `/.well-known/agent-skills/{name}/SKILL.md`, though publishers MAY use any URL.
  165. 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 Distribution](#archive-distribution).
  166. Clients encountering an unrecognized `type` value SHOULD skip that skill entry and MAY warn the user.
  167. ### Backward Compatibility
  168. The v0.2.0 index format is not backward-compatible with v0.1.0. Key differences:
  169. - v0.1.0 used `files` as an array of path strings with no digests. v0.2.0 removes `files` entirely, adds `type`, `url`, `digest`, and `$schema`.
  170. Clients MUST check the `$schema` field to determine how to process the index. An unrecognized `$schema` URI indicates the index structure may have changed incompatibly; see [Versioning](#versioning).
  171. ## Integrity and Verification
  172. All digests in the index use SHA-256 and are formatted as `sha256:{hex}`, where `{hex}` is 64 lowercase hexadecimal characters.
  173. The `digest` field on each skill entry is the SHA-256 hash of the raw bytes of the skill's artifact:
  174. - For `type: "skill-md"`: the SHA-256 of the `SKILL.md` file's raw bytes.
  175. - For `type: "archive"`: the SHA-256 of the archive file's raw bytes.
  176. ```
  177. sha256:{SHA-256(raw_bytes)}
  178. ```
  179. ### Verification
  180. Clients MUST verify downloaded content against the `digest` in the index. A mismatch indicates the content is corrupted or has been tampered with; clients MUST NOT use unverified content.
  181. - **Change detection**: Compare a skill's `digest` against a locally cached value. If they match, the artifact is unchanged and the client can skip re-downloading.
  182. - **Download verification**: After downloading a skill artifact, compute its SHA-256 and compare against the `digest`. Reject on mismatch.
  183. ## Archive Distribution
  184. Skills with supporting files (scripts, references, assets) are distributed as archives with `type: "archive"` in the index. The archive contains the full skill directory, including `SKILL.md` and all supporting resources.
  185. ### Supported Formats
  186. Archives SHOULD be in `.tar.gz` (gzip-compressed tar) or `.zip` format. Clients MUST support at least `.tar.gz` and `.zip`. Each format has different tradeoffs:
  187. - **`.tar.gz`**: Robust support for UNIX file permissions and symlinks.
  188. - **`.zip`**: Limited support for UNIX file permissions and symlinks (varies by implementation). Supports partial file retrieval via HTTP range requests (useful for indexing services that need to read `SKILL.md` without downloading the full archive).
  189. ### Archive Structure
  190. The archive contents represent the skill directory — files are placed at the archive root, not nested inside a wrapper directory.
  191. - The archive MUST contain a `SKILL.md` file at the root.
  192. - The archive MUST NOT contain path traversal sequences (`..`) or absolute paths.
  193. ### Archive Safety
  194. After verifying the archive's digest (see [Integrity and Verification](#integrity-and-verification)), clients unpacking an archive MUST:
  195. 1. Reject archives containing path traversal sequences (`..`) or absolute paths.
  196. 2. Reject archives containing symlinks or hard links that resolve outside the skill directory.
  197. 3. Consider enforcing a reasonable limit on total unpacked size to prevent denial-of-service via decompression bombs.
  198. ### Distribution Guidance
  199. Simple skills — those with only `SKILL.md` — SHOULD use `type: "skill-md"`. Archives are intended for skills with supporting files where a single download is more efficient and preserves directory structure, file permissions, and symlinks.
  200. ## Examples
  201. ### Simple skill (SKILL.md only)
  202. A minimal skill contains just the required `SKILL.md`:
  203. ````
  204. GET /.well-known/agent-skills/git-workflow/SKILL.md
  205. ---
  206. name: git-workflow
  207. description: Follow team Git conventions for branching and commits.
  208. ---
  209. # Git Workflow
  210. Create feature branches from `main`:
  211. ```bash
  212. git checkout -b feature/my-feature main
  213. ```
  214. Commit messages use conventional commits format:
  215. ```
  216. feat: add user authentication
  217. fix: resolve null pointer in login
  218. docs: update API reference
  219. ```
  220. ````
  221. ### Complex skill with resources
  222. A skill with scripts and reference documentation, distributed as an archive:
  223. ```
  224. wrangler.tar.gz (archive contents)
  225. ├── SKILL.md
  226. ├── scripts/
  227. │ ├── deploy.sh
  228. │ └── init.sh
  229. ├── references/
  230. │ ├── COMMANDS.md
  231. │ └── CONFIGURATION.md
  232. └── assets/
  233. └── wrangler.toml.template
  234. ```
  235. The `SKILL.md` references these files for progressive disclosure:
  236. ```yaml
  237. ---
  238. name: wrangler
  239. description: Deploy and manage Cloudflare Workers projects.
  240. ---
  241. # Wrangler
  242. ## Deployment
  243. Run `scripts/deploy.sh` to deploy your Worker.
  244. For available commands, see [references/COMMANDS.md](references/COMMANDS.md).
  245. For configuration options, see [references/CONFIGURATION.md](references/CONFIGURATION.md).
  246. ```
  247. ### Discovery index
  248. ```json
  249. {
  250. "$schema": "https://schemas.agentskills.io/discovery/0.2.0/schema.json",
  251. "skills": [
  252. {
  253. "name": "code-review",
  254. "type": "skill-md",
  255. "description": "Review code for bugs, security issues, and best practices.",
  256. "url": "/.well-known/agent-skills/code-review/SKILL.md",
  257. "digest": "sha256:c4d5e6f7..."
  258. },
  259. {
  260. "name": "git-workflow",
  261. "type": "skill-md",
  262. "description": "Follow team Git conventions for branching and commits.",
  263. "url": "/.well-known/agent-skills/git-workflow/SKILL.md",
  264. "digest": "sha256:a7b8c9d0..."
  265. },
  266. {
  267. "name": "wrangler",
  268. "type": "archive",
  269. "description": "Deploy and manage Cloudflare Workers projects.",
  270. "url": "/.well-known/agent-skills/wrangler.tar.gz",
  271. "digest": "sha256:f1e2d3c4..."
  272. }
  273. ]
  274. }
  275. ```
  276. ## HTTP Considerations
  277. Servers MUST:
  278. - Serve `/.well-known/agent-skills/index.json` with `application/json` content type
  279. - Serve `SKILL.md` files with `text/markdown` or `text/plain` content type
  280. - Serve `.tar.gz` archives with `application/gzip` content type and `.zip` archives with `application/zip` content type
  281. - Support `GET` and `HEAD` methods
  282. - Return `404 Not Found` for skills or files that do not exist
  283. Servers SHOULD:
  284. - Set appropriate `Cache-Control` headers
  285. - Include CORS headers (e.g., `Access-Control-Allow-Origin`) if skills are intended for consumption by browser-based clients
  286. Clients MUST:
  287. - Handle redirects (3xx responses)
  288. - Respect cache headers
  289. ## Client Implementation
  290. Clients discovering skills from a well-known endpoint MUST:
  291. 1. **Fetch `index.json`.** Retrieve `/.well-known/agent-skills/index.json` to enumerate available skills.
  292. 2. **Check schema version.** Match the `$schema` field against known schema URIs. If absent, treat the index as v0.1.0. Clients SHOULD NOT process an index with an unrecognized `$schema` URI and SHOULD warn the user. Clients MUST ignore unrecognized fields.
  293. 3. **Use digests for caching.** Compare each skill's `digest` against locally cached values. If the digest matches, the skill is unchanged and the client MAY skip re-downloading.
  294. 4. **Fetch and verify skill artifacts.** For skills that need updating:
  295. - For `type: "skill-md"`: Download `SKILL.md` from the skill's `url`. Compute its SHA-256 and verify against `digest`.
  296. - For `type: "archive"`: Download the archive from the skill's `url`. Compute its SHA-256 and verify against `digest`. Unpack the archive and validate its structure (see [Archive Safety](#archive-safety)).
  297. - For an unrecognized `type`: Skip the skill entry and warn the user.
  298. 5. **Apply progressive disclosure.** Load only `name` and `description` at discovery time. Load `SKILL.md` when a skill is activated. For archive-based skills, load supporting resources (scripts, references, assets) on demand as the task requires.
  299. 6. **Cache aggressively.** Skills change infrequently. Respect `Cache-Control` headers and consider caching content for the duration of a session. Use skill digests to invalidate cached content when updates are detected.
  300. 7. **Gate script execution.** Clients SHALL NOT execute files under `scripts/` by default. Clients SHALL consider implementing a permissions model that only executes scripts bundled with a skill when explicitly allowed by the user or client configuration. Consider sandboxing execution environments and restricting filesystem and network access. Never execute scripts from untrusted origins without user approval.
  301. ## Security Considerations
  302. The security considerations from [RFC 8615 Section 4](https://datatracker.ietf.org/doc/html/rfc8615#section-4) apply. Additional considerations for skills:
  303. - **Trust**: Skills contain instructions and executable code. Agents should only use skills from trusted origins. See the [Agent Skills security guidance](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview#security-considerations).
  304. - **Prompt injection**: Skill content is loaded directly into agent context. A malicious `SKILL.md` can inject instructions that alter agent behavior. Clients SHOULD validate that skill artifacts originate from trusted, allowlisted domains before loading them into context.
  305. - **Origin allowlisting**: Clients SHOULD maintain a configurable allowlist of trusted domains from which skills may be fetched. Skills from origins not on the allowlist SHOULD be rejected unless the user explicitly approves them.
  306. - **Access control**: Servers should control write access to `/.well-known/agent-skills/` carefully, especially in shared hosting environments.
  307. - **Script execution**: Clients SHALL NOT execute files under `scripts/` by default. Clients SHALL consider implementing a permissions model that only executes scripts bundled with a skill when explicitly allowed by the user or client configuration. Refer to the [Agent Skills specification](https://agentskills.io/specification) guidance on script execution.
  308. - **Digest verification**: Clients MUST verify artifact digests after download. A digest mismatch indicates the content has been tampered with or is stale; clients MUST NOT use unverified content.
  309. - **Archive safety**: Clients MUST validate archive digests before unpacking. Clients MUST reject archives containing path traversal sequences (`..`, absolute paths) or symlinks and hard links that resolve outside the skill directory. Clients SHOULD verify total unpacked size against reasonable limits to prevent denial-of-service via decompression bombs.
  310. - **External references**: Skills that fetch external resources introduce additional trust boundaries.
  311. ## Relationship to Existing Specifications
  312. This document builds on:
  313. - [RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119) - Key Words for Use in RFCs to Indicate Requirement Levels
  314. - [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986) - Uniform Resource Identifier (URI): Generic Syntax
  315. - [RFC 8174](https://datatracker.ietf.org/doc/html/rfc8174) - Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words
  316. - [RFC 8615](https://datatracker.ietf.org/doc/html/rfc8615) - Well-Known URIs
  317. - [Agent Skills Specification](https://agentskills.io/specification) - Skill format and structure
  318. ## References
  319. - [Agent Skills](https://agentskills.io/) - Open standard for agent skills
  320. - [RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119) - Key Words for Use in RFCs to Indicate Requirement Levels
  321. - [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986) - Uniform Resource Identifier (URI): Generic Syntax
  322. - [RFC 8174](https://datatracker.ietf.org/doc/html/rfc8174) - Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words
  323. - [RFC 8615](https://datatracker.ietf.org/doc/html/rfc8615) - Well-Known Uniform Resource Identifiers
  324. - [Claude Agent Skills](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview)
  325. - [OpenAI Codex Skills](https://developers.openai.com/codex/skills/)
  326. - [OpenCode Skills](https://opencode.ai/docs/skills/)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.