agent-skills 1.0.0

Agent Skills Check v1.0.0

Status

• version: 1.0.0
• check identifier: agent-skills
• input contract: [email protected]
• output contract: [email protected]
• scope: site-level Agent Skills Discovery index and advertised skill artifacts

Abstract

This check validates an Agent Skills Discovery index for the scanned origin. It fetches the canonical well-known index, validates the v0.2.0 discovery shape, verifies digest-pinned skill artifacts, validates SKILL.md frontmatter or archive structure, and records security-relevant evidence without executing any advertised skill code.

Motivation

Agent Skills let agents discover task-specific instructions through progressive disclosure: a small index advertises available skills, and clients load full SKILL.md or archive artifacts only when needed. For this to be safe and useful, discovery metadata must be machine-readable, artifact URLs must be resolvable, and downloaded content must match the digest advertised by the index.

Normative Model

This version recognizes Agent Skills Discovery v0.2.0:

• canonical discovery path: /.well-known/agent-skills/index.json
• compatibility path: /.well-known/skills/index.json
• required $schema: https://schemas.agentskills.io/discovery/0.2.0/schema.json
• required top-level skills array
• required skill fields: name, type, description, url, and digest
• supported type values: skill-md and archive
• supported digest form: sha256:{64 lowercase hex}

Skill artifact URLs are resolved against the selected index URL using RFC 3986 relative-reference resolution.

skill-md artifacts are expected to be Markdown files containing YAML frontmatter with at least name and description. Archive artifacts are expected to contain a root SKILL.md and no unsafe paths or links.

Optional skill metadata such as license, compatibility, and platform-specific tool declarations is treated as review evidence. This version does not require optional metadata for conformance.

Applicability

The check applies to every scanned origin.

It first checks /.well-known/agent-skills/index.json. If the canonical path is not usable, it checks the legacy compatibility path /.well-known/skills/index.json.

When neither path exposes a usable index, the result is a warning because Agent Skills Discovery is an emerging recommendation for agent readiness.

Pass Criteria

A passing result requires:

• the canonical discovery path is reachable
• the index response is JSON-compatible and valid JSON
• $schema exactly matches the v0.2.0 schema URI
• skills is a non-empty array
• every processed skill entry has valid required fields
• every processed artifact returns HTTP 200
• every processed artifact matches its raw-byte SHA-256 digest
• skill-md artifacts contain valid SKILL.md frontmatter
• archive artifacts contain a root SKILL.md and no unsafe paths
• no high-confidence credential or prompt-injection findings are found

Warning Criteria

Warnings include:

• the canonical index is missing but the legacy compatibility path exists
• no Agent Skills index is found at either discovery path
• unknown top-level fields are present but otherwise ignored
• skill descriptions are short, vague, or do not explain when to activate the skill
• SKILL.md bodies are too thin, too large, or lack workflow, input/output, example, or validation guidance
• compatibility metadata is present but not actionable
• artifact URLs cross origin or otherwise introduce an extra trust boundary
• SKILL.md references broad tool grants, hooks, dynamic shell context, suspicious commands, external URLs, or archive scripts/

Failure Criteria

Failures include:

• the selected index is not valid JSON or not served with a JSON-compatible content type
• $schema is missing or does not exactly match the v0.2.0 schema URI
• skills is missing, not an array, or empty
• required skill entry fields are missing or invalid
• skill names, types, URLs, or digests are malformed
• advertised artifacts cannot be fetched or do not match the raw-byte SHA-256 digest
• skill-md artifacts are missing valid YAML frontmatter
• archive artifacts lack a root SKILL.md, exceed safety limits, or contain unsafe paths, absolute paths, symlinks, or hard links
• public skill text contains high-confidence credential-looking content or prompt-injection-like instructions

Quality Heuristics

The check also records skill quality warnings. These warnings are not Agent Skills Discovery conformance failures unless they make a required field invalid.

Quality warnings include:

• descriptions that are too short or do not say when an agent should activate the skill
• SKILL.md bodies that are too thin to guide a workflow
• very large SKILL.md bodies that work against progressive disclosure
• missing workflow, input/output, example, or validation guidance
• compatibility metadata that is present but not actionable

Security Heuristics

The security review is static and bounded. It does not execute code and does not claim to be malware detection.

Security failures include:

• prompt-injection-like instructions in public skill text
• credential-looking content in public skill text
• unsafe archive paths, absolute paths, symlinks, or hard links

Security warnings include:

• broad or code-modifying tool grants, including broad shell access
• hook references
• dynamic shell context injection
• suspicious shell or code-execution patterns
• external URLs that introduce additional trust boundaries
• archive scripts/ entries, recorded as review evidence because clients must not execute them by default

Evidence Model

The result emits:

• discovery paths checked, status codes, content types, lengths, and selected path
• parsed schema URI, skill counts, valid skill counts, and unknown top-level field count
• invalid skill entry summaries
• warning skill entry summaries
• resolved artifact URLs and same-origin, same-site, or external classification
• advertised and actual digest values
• digest match status
• artifact content type and byte length
• SKILL.md frontmatter validity
• archive entry counts, estimated uncompressed bytes, root SKILL.md presence, and unsafe path findings
• security findings for scripts, prompt-injection-like instructions, credential-looking text, and cross-origin artifacts

Evidence must not include full skill files, full archives, script bodies, cookies, authorization headers, or credential values.

Validation And Scoring Steps

1. discover-index - weight 0.15

Fetch canonical and legacy discovery paths, preferring the canonical well-known URI.

1. validate-index-schema - weight 0.20

Validate JSON content type, JSON syntax, $schema, and top-level fields.

1. validate-skill-entries - weight 0.15

Validate required skill fields, name syntax, description quality, type, URL, and digest syntax.

1. verify-artifacts - weight 0.20

Fetch advertised artifacts and verify raw-byte SHA-256 digests.

1. validate-skill-content - weight 0.15

Validate SKILL.md frontmatter, Markdown body quality, or archive structure.

1. security-review - weight 0.15

Detect risky scripts, unsafe archive paths, prompt-injection-like text, credential-looking content, tool grants, dynamic shell context, suspicious commands, external URLs, and cross-origin trust boundaries.

Standard Behavior

The check is isolated. It does not consume output from agents.json, A2A Agent Card, MCP server card, DNS-AID, or local Codex/Claude skill catalogs.

The check fetches only the discovery index and the bounded set of artifacts advertised by valid skill entries. It computes digests over raw response bytes. It does not execute scripts, invoke tools, install skill packages, or recursively load referenced files.

Non-Standard And Real-World Behavior

The legacy path /.well-known/skills/index.json is recognized as compatibility evidence. A site that only publishes the legacy path receives a warning even if the legacy document validates.

Unknown top-level fields are ignored for compatibility, but recorded as warnings because v0.2.0 defines $schema and skills as the discovery shape. A top-level version field is not required for v0.2.0.

Generic but compatible content types can be accepted with warnings. skill-md artifacts are strongest when served as text/markdown or text/plain; archive artifacts are strongest when served as application/zip, application/gzip, or tar-compatible media types.

Cross-origin artifacts are allowed by the discovery model, but they are recorded as a separate trust boundary.

Non-Goals And Limitations

• This check does not execute skill scripts.
• This check does not install or activate skills in Codex, Claude, OpenCode, or other agents.
• This check does not recursively inspect referenced files outside a downloaded archive.
• Archive inspection is structural and bounded; it is not a full malware scan.
• Static security heuristics may produce false positives and should be read as review findings unless marked as failures.
• The check does not require Agent Skills Discovery to be registered in the IANA Well-Known URI registry.
• Future Agent Skills Discovery schema versions should be handled by new check versions rather than changing v1.0.0 behavior.

References

• github.com/cloudflare/agent-skills-discovery-rfc
• agentskills.io/specification
• developers.openai.com/codex/skills
• platform.claude.com/docs/en/agents-and-tools/agent-skills/overview
• datatracker.ietf.org/doc/html/rfc8615
• datatracker.ietf.org/doc/html/rfc3986
• schemas.agentskills.io/discovery/0.2.0/schema.json

agent-skills v1.0.0 Changelog

• Aligned discovery validation with Agent Skills Discovery v0.2.0 $schema semantics.
• Added raw-byte digest verification for advertised artifacts.
• Added SKILL.md frontmatter validation and bounded archive structure inspection.
• Added quality review for activation descriptions, thin instructions, progressive-disclosure fit, workflow cues, and compatibility notes.
• Added security review for prompt-injection-like text, credential-looking content, broad tool grants, hook references, dynamic shell context, suspicious commands, external URLs, scripts, unsafe archive paths, and cross-origin artifact trust boundaries.