Agent Skills Discovery Indexes and Package Trust

An agent skill can contain instructions that shape how an agent reads files, calls tools, runs programs, or reaches network services. Finding a skill is easy compared with deciding whether to trust and execute it.

Cloudflare's Agent Skills Discovery RFC repository proposes a predictable index for downloadable skill artifacts. The current documented format is v0.2.0. It is a Cloudflare project proposal, not an IETF RFC, even though it reuses IETF rules for well-known URIs and URL resolution.

The index solves discovery and byte integrity. It does not certify the author, approve the instructions, or make installation safe.

v0.2.0 starts with an explicit schema identifier

The proposed index lives at:

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

A v0.2.0 document contains $schema and skills. The current schema identifier is:

https://schemas.agentskills.io/discovery/0.2.0/schema.json

The proposal treats this URI as an opaque version identifier. It doesn't need to resolve. A client compares it with the versions it knows and should decline to process an unfamiliar schema after warning the user.

That check matters because v0.2.0 is not backward compatible with v0.1.0. The earlier format used a files array without digests. Version 0.2.0 removes that member and adds type, url, digest, and $schema. When $schema is absent, the proposal directs clients to apply its v0.1.0 compatibility behavior rather than guessing v0.2.0.

Each skill entry has five required fields. name follows the Agent Skills naming rules. description explains the skill's purpose. type determines the distribution form. url locates the artifact. digest binds the entry to exact bytes.

The two current type values are skill-md for one SKILL.md document and archive for a packaged artifact. A client should skip an unknown type rather than choosing an extraction strategy from a filename.

Resolve URLs against the index, exactly once

The proposal applies RFC 3986 Section 5 with the index URL as the base URI. The distinction among the accepted forms is operational:

• code-review/SKILL.md resolves relative to /.well-known/agent-skills/;
• /.well-known/agent-skills/code-review/SKILL.md resolves from the current origin root;
• https://cdn.example/skills/code-review/SKILL.md selects another origin explicitly.

Resolve the URL with a standards-compliant library, then apply fetch policy to the result. Don't concatenate paths, and don't treat a cross-origin absolute URL as though the index host vouched for the artifact host.

A backend fetcher should permit HTTPS, reject credentials in URLs, cap redirects, revalidate scheme and address after every redirect, block local or private destinations, set time and byte limits, and constrain response decompression. Browser clients still need origin-aware user disclosure and normal cross-origin controls.

For an archive, the proposal prefers the response Content-Type to determine format and uses the extension only as a fallback when the media type is absent or generic. Format detection is only the first step. Extraction needs a separate security boundary.

The SHA-256 digest verifies the downloaded bytes

Every v0.2.0 entry uses this digest syntax:

sha256:{64 lowercase hexadecimal characters}

The client fetches the artifact, computes SHA-256 over the exact received bytes, formats the result the same way, and performs an exact comparison before parsing or installing anything. A mismatch means the artifact is not the indexed object. Stop and remove the temporary download.

Byte details matter. Don't normalize Markdown line endings before hashing. Don't unpack an archive and hash its extracted files. Don't hash a redirected URL string. The digest covers the artifact response bytes that the publisher used to calculate it.

This detects corruption and content substitution relative to the index. It does not prove who controlled the index, whether the publisher reviewed the skill, or whether the instructions are safe. If an attacker can update both the artifact and its digest, verification succeeds for the attacker's bytes.

Publisher authenticity therefore comes from the HTTPS origin, organizational release controls, and any additional signature or transparency system an implementation chooses. The v0.2.0 proposal specifies SHA-256 digests, not package signatures.

Treat skill installation as code intake

A single SKILL.md can direct an agent toward powerful actions. Review requested tools, filesystem scope, network destinations, credential use, external references, and conditions that trigger execution. Instructions retrieved later are additional untrusted dependencies unless their versions and integrity are controlled.

Archives add familiar package hazards. Extract into a new isolated directory. Reject absolute paths, parent traversal, device files, unsafe symbolic or hard links, duplicate path tricks, excessive file counts, oversized expansion, and nested compression beyond set limits. Never extract directly over an existing skill installation.

After safe extraction, inventory the package and review its scripts and references. Grant only the tools and network access needed for the accepted use case. A skill description is not authorization for shell execution, credential access, deployment, messaging, or deletion.

Updates repeat the complete process. A new digest proves that the bytes changed; it doesn't approve the change. Retain the previous reviewed version for rollback, identify which agents use each version, and support fast removal when a package is compromised.

Fetch and review should occur before an agent sees the instructions. Parsing a skill into the same privileged context used for approval lets hostile instructions influence the approval step. Present metadata and review results through a trusted interface, then install into a fresh, bounded execution context only after approval.

The index description is informational. Compare it with the SKILL.md frontmatter after digest verification and flag a mismatch, but don't let either description expand permissions automatically. Permission grants belong to local policy.

Provenance should remain visible from index URL through resolved artifact URL, digest, review decision, installed version, and invoking agent. That record supports technical assessment without treating the index as a trust store.

An empty index creates the wrong contract

The proposal allows an empty skills array at the syntax level. Publishing one without a maintained skill still creates a discovery surface. Clients may poll it, operators must keep its schema behavior current, and internal teams may interpret its existence as approval to add packages later.

An ownerless endpoint also obscures the adoption decision. The useful unit is a reviewed skill plus its release, integrity, revocation, and support process. An index by itself supplies none of those controls.

TKOResearch has no public skill packages, so it will not publish /.well-known/agent-skills/index.json. TARE should adopt an index only when a specific product workflow has a maintained skill, bounded permissions, package review, deterministic digest generation, version retention, revocation, monitoring, and a named security owner.

Discovery should make an approved package easier to find. It shouldn't make an unreviewed package easier to install.