Agent Skills Discovery Indexes and Package Trust

A SHA-256 match can confirm that a downloaded skill is exactly the artifact named in an index. It cannot tell you whether that skill should be allowed to run commands, read credentials, or change a deployment.

Cloudflare's Agent Skills Discovery proposal is at v0.2.0 as of September 9, 2026. The repository calls it a draft; “RFC” in its name does not mean an IETF RFC. Its contribution is a predictable package index with byte digests.

Use the index to select an artifact for review. Verify its bytes, inspect its instructions and scripts, then apply the installation policy of the environment that will run it.

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.

Keep artifact transport separate from artifact identity

Define which bytes your download library exposes before relying on a digest check. HTTP content encoding, archive compression, and the files inside an archive are different layers. Agree with the publisher on the artifact bytes covered by the digest, and use a fixture that catches accidental newline rewriting or hashing after extraction.

For example, a reviewer can approve a single Markdown file while refusing a later update that adds a shell script and an external download. Both versions may have correct hashes. The second version needs a new permission review because its behavior changed, not because integrity verification failed.

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 into a staging area and review through a context that treats the package as untrusted data. Feeding its instructions directly into the privileged agent that decides installation creates an avoidable prompt-injection path. Present the review result through a trusted interface and let the environment's approval policy control installation and permissions.

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.

Publish the index with a reviewed package

The proposal permits an empty skills array. An organization with no packages gains little from maintaining an empty endpoint; its presence does not establish a release or review process.

For the first package, keep the index entry linked to a reviewed artifact, digest and permission decision. Name the owner who can withdraw a release and identify the agents using it. Rehearse returning those consumers to the previous reviewed version before distributing an update.

The useful release check is whether operators can contain a bad package after discovery succeeds.