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 remains at v0.2.0 in the September 9, 2026 source review. 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.

I would put that index on the intake side of a package-review process. Discovery gives the reviewer a specific artifact to inspect. Installation and permission decisions still belong to 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.

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.

Before publishing a first package, rehearse withdrawing it and returning consumers to the previous reviewed digest. If the index can distribute an update but operations can't identify its users or revoke it, the release process is unfinished.