Proposal: keep the top level for the spec, put extensions in metadata with Kubernetes-style prefixed keys

[yordis]

Problem

Several threads are each solving the same question: where do fields that the spec does not define go, and how are they named?

• Open frontmatter schema + `x-` prefix for extension fields #192 proposed opening the top level with an x- prefix (closed in favor of Open frontmatter schema (with namespacing guidance) #211).
• Open frontmatter schema (with namespacing guidance) #211 proposes opening the top level, prefixed with {AGENT_NAME}- or nested under {AGENT_NAME}:.
• docs: reserve the io.modelcontextprotocol/ key prefix in the metadata map #546 reserves the io.modelcontextprotocol/ prefix inside metadata.
• metadata is specified as string values, but a shipping runtime stores nested maps and booleans there #514 and Clarify whether SKILL.md metadata supports arbitrary values or only strings #474 ask whether metadata values are strings only, because shipping runtimes already store nested maps, booleans, and lists there.
• Proposals such as RFC: metadata.activation — normalized hook lifecycle events for portable skill declarations #408 (metadata.activation) and [Proposal]: Add an optional source field under metadata for update tracking of manually installed skills #564 (metadata.source) each pick their own unprefixed key inside metadata.

The spec today says only "We recommend making your key names reasonably unique to avoid accidental conflicts." That leaves every client to invent its own convention, and in practice several have skipped metadata entirely. Goose uses top-level author, version, and tags. Claude Code defines its own top-level fields.

This proposal tries to settle all of the above with one rule.

Proposal

1. The top level of the frontmatter is reserved for fields defined by the Agent Skills spec. Clients and authors must not add new top-level fields.
2. Every extension goes in metadata, under a prefixed key, using the same syntax as Kubernetes labels and annotations:
   • prefix/name, where prefix is a DNS subdomain the author or client controls (for example io.modelcontextprotocol/ or example.com/).
   • name is at most 63 characters, starts and ends with an alphanumeric character, and may contain -, _, and . in between.
   • Keys without a prefix are reserved for the skill author's private use, and clients should not depend on them.
3. agentskills.io/ is reserved for the spec itself. The MCP reservation in docs: reserve the io.modelcontextprotocol/ key prefix in the metadata map #546 becomes one instance of the general rule instead of a special case.
4. A field moves to the top level only after it has proven itself as a prefixed key, ideally across more than one client. Promotion must say which form wins when both are present, and how long the prefixed form stays supported.
5. Values stay strings. Structured values are encoded (for example as JSON) inside the string.

Example:

---
name: pdf-processing
description: Extract text and tables from PDF files.
metadata:
  author: example-org
  example.com/hooks: '["pre-tool-use"]'
  io.modelcontextprotocol/test-marker: "true"
  example.com/source: "https://github.com/example/skills"
---

Why Kubernetes is the right model

Kubernetes has run this exact pattern for about a decade, across a very large ecosystem of independent vendors, without coordination.

• A fixed envelope with an open extension map. Every Kubernetes object has the same top-level shape (apiVersion, kind, metadata, spec, status). Vendors do not add top-level fields; they add prefixed keys to metadata.annotations. The core schema stayed stable while the ecosystem grew around it.

• Domain prefixes prevent collisions without a registry. Owning a domain is owning a namespace, so nobody has to coordinate names. kubernetes.io/ and k8s.io/ are reserved for the core project, which is what point 3 above does for agentskills.io/.

• Annotation first, field later. Kubernetes incubates features as annotations and promotes them to real fields only after they prove themselves:

  • kubernetes.io/ingress.class became spec.ingressClassName.
  • The seccomp.security.alpha.kubernetes.io/* annotations became securityContext.seccompProfile.
  • The container.apparmor.security.beta.kubernetes.io/* annotations became securityContext.appArmorProfile.

  Each promotion came with a rule for which form wins and a deprecation window. That is the process point 4 asks for.

• String values are deliberate. Annotations are map[string]string. Structured data is encoded, for example kubectl.kubernetes.io/last-applied-configuration holds a JSON document. Every parser stays trivial, and no client has to agree on a type system for someone else's data.

Why an open top level hurts the spec

• It spends names the spec may need later. If clients use top-level version, author, or tags with different meanings, the spec can never standardize those names cleanly. It inherits every conflicting meaning already in use. Prefixed keys leave the plain names free for the spec to define.
• Readers and validators cannot tell spec fields from vendor fields. With a closed top level, anything unprefixed at the top is standard by construction.
• It is hard to undo. CONTRIBUTING notes that it is much easier to add to a specification than to remove from it. A top-level field that clients ship can effectively never be removed. A prefixed key in metadata can be ignored, deprecated, or promoted.
• It costs almost nothing. metadata already exists and is already the documented place for extensions. This proposal adds a key syntax and a promotion rule; it adds no new fields.

Addressing the main objections

• "Nesting under metadata is less pleasant to write" (the main argument in Open frontmatter schema (with namespacing guidance) #211): one level of nesting is the price of a stable core. Kubernetes users make the same trade on every object.
• "Runtimes already store nested maps and booleans" (metadata is specified as string values, but a shipping runtime stores nested maps and booleans there #514): those can be encoded as strings. If the community prefers, the spec could tolerate non-string values with a SHOULD while keeping strings as the defined type. Either way, it should be stated explicitly instead of left implicit.
• "Existing top-level extensions would become non-conforming": they can be grandfathered with a deprecation window, and clients can read both forms during the transition, the same way Kubernetes handled each annotation-to-field promotion.

Spec change if accepted

A small edit to the metadata field section of docs/specification.mdx: replace "We recommend making your key names reasonably unique" with the key syntax above, reserve agentskills.io/, state that new top-level fields are reserved for the spec, and describe the promotion rule. #546 could be folded into the same change.

cc @jonathanhefner (#211, #192) and @tobi-oye (#546), since this would overlap with both.